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