Criminy.
[charm.git] / doc / converse / scheduler.tex
1
2 \chapter{Scheduler Calls}
3
4 %These are the calls/macros provided by the Converse scheduler.
5 %All declarations are in converse.h.
6
7 \internal{
8 \function {void CsdInit(void)}
9 This call initializes the Converse scheduler, it is called from
10 ConverseInit().
11 }
12
13 \function {void CsdScheduler(int NumberOfMessages)}
14 \index{CsdScheduler}
15 \desc{This call invokes the Converse scheduler, which repeatedly
16 delivers messages to their handlers (i.e. invokes the handler for each
17 message it selects).  Each message header encodes a pointer to its
18 handler as described in the next chapter. 
19 In each iteration, the scheduler first looks for any
20 message that  has arrived from another processor, and delivers it.
21 If there isn't any, it selects a message from the locally enqueued
22 messages (see below), and delivers it.
23 The {\tt NumberOfMessages}
24 parameter specifies how many messages should be processed (i.e. delivered
25 to their handlers). If set to -1, the scheduler continues delivering
26 messages until CsdExitScheduler() is called from a message handler.
27 if {\tt NumberOfMessages} is 0, the scheduler continues delivering messages
28 until it exhausts its supply of messages (i.e. becomes idle) or some 
29 handler calls CsdExitScheduler().}
30
31 \function {void CsdExitScheduler(void)}
32 \index{CsdExitScheduler}
33 \desc{This call causes the scheduler
34 to stop processing messages when control has returned back to it.
35 The scheduler then returns to its calling routine.}
36
37 \function{void CsdEnqueueGeneral(void *Message, int strategy, int priobits, int *prioptr)}
38 \index{CsdEnqueueGeneral}
39 \desc{This call enqueues a message to the scheduler's queue, to be processed in 
40 accordance with the queueing \param{strategy}. \param{priobits} and
41 \param{prioptr} specify information about priority associated with the message
42 if prioritized queueing strategies are used. \param{strategy} can take values 
43 defined in {\tt converse.h} depending upon the queueing strategy (FIFO or LIFO)
44 and the nature of priority information used (none, integer or bit-vector).
45 These predefined constants are: 
46 {\tt CQS\_QUEUEING\_FIFO}, {\tt CQS\_QUEUEING\_LIFO},
47 {\tt CQS\_QUEUEING\_IFIFO}, {\tt CQS\_QUEUEING\_ILIFO},
48 {\tt CQS\_QUEUEING\_BFIFO}, and\\  {\tt CQS\_QUEUEING\_BLIFO}.
49 This call is usually made from
50 a message handler when the message is not to be processed immediately,
51 but may be processed later (e.g. depending on the message's priority).
52 Also, it is used to enqueue local ready entities, such as threads.
53 \note{It is necessary to grab the ownership of the message buffer before queuing
54 because on returning from the handler, the system can reuse the buffer.}}
55
56 \function {void CsdEnqueue(void *Message)}
57 \index{CsdEnqueue}
58 \function{void CsdEnqueueFifo(void *Message)}
59 \index{CsdEnqueueFifo}
60 \desc{
61         This macro is a shorthand for 
62         {\tt CsdEnqueueGeneral(Message, CQS\_QUEUEING\_FIFO,0, NULL)} 
63         provided here for backward compatibility.
64 }
65
66
67 \function{void CsdEnqueueLifo(void *Message)}
68 \index{CsdEnqueueLifo}
69 \desc{
70         This macro is a shorthand for
71         {\tt CsdEnqueueGeneral(Message, CQS\_QUEUEING\_LIFO,0, NULL)} 
72         provided here for backward compatibility.
73 }
74
75 \function{int CsdEmpty()}
76 \index{CsdEmpty}
77 \desc{
78         This function returns non-zero integer when the scheduler's queue
79         is empty, zero otherwise.
80 }