050e954abd1b6dfe87255d5adee0d72cfd6c2e18
[charm.git] / doc / converse / cmi.tex
1 \chapter{Machine Interface and Scheduler}
2
3 This chapter describes two of Converse's modules: the CMI, and the
4 CSD.  Together, they serve to transmit messages and schedule the
5 delivery of messages. First, we describe the machine model assumed by
6 Converse.
7
8 \section{Machine Model}
9 \label{model}
10
11 Converse treats the parallel machine as a collection of nodes, where
12 each node is comprised of a number of processors that share memory 
13 In some cases, the number of processors per node may be exactly one  
14 (e.g. Distributed memory multicomputers such as IBM SP.)  
15 In addition, each of the processors may have multiple threads running on
16 them which share code and data but have different stacks.
17 Functions and macros are provided for handling shared memory across
18 processors and querying node information. These are discussed in section
19 \ref{globalvars}
20
21 \section{Defining Handler Numbers}
22 \label{handler1}
23
24 When a message arrives at a processor, it triggers the execution of a
25 {\em handler function}, not unlike a UNIX signal handler.  The handler
26 function receives, as an argument, a pointer to a copy of the message.
27 The message itself specifies which handler function is to be
28 called when the message arrives.  Messages are contiguous sequences of
29 bytes.  The message has two parts: the header, and the data.  The data
30 may contain anything you like.  The header contains a {\em handler
31 number}, which specifies which handler function is to be executed when
32 the message arrives.  Before you can send a message, you have to
33 define the handler numbers.
34
35 Converse maintains a table mapping handler numbers to function
36 pointers.  Each processor has its own copy of the mapping.  There is a
37 caution associated with this approach: it is the user's responsibility
38 to ensure that all processors have identical mappings.  This is easy
39 to do, nonetheless, and the user must be aware that this is (usually)
40 required.
41
42 The following functions are provided to define the handler numbers:
43
44 \function{typedef void (*CmiHandler)(void *)}
45 \index{CmiHandler}
46 \desc{Functions that handle Converse messages must be of this type.}
47
48 \function{int CmiRegisterHandler(CmiHandler h)}
49 \index{CmiRegisterHandler}
50 \desc{This represents the standard technique for associating numbers
51 with functions.  To use this technique, the Converse user registers
52 each of his functions, one by one, using CmiRegisterHandler.  One must
53 register exactly the same functions in exactly the same order on all
54 processors.  The system assigns monotonically increasing numbers to
55 the functions, the same numbers on all processors.  This insures
56 global consistency.  CmiRegisterHandler returns the number which was
57 chosen for the function being registered.}
58
59 \function {int CmiRegisterHandlerGlobal(CmiHandler h)}
60 \index{CmiRegisterHandlerLocal}
61 \desc{This represents a second registration technique.   The Converse
62 user registers his functions on processor zero, using
63 CmiRegisterHandlerGlobal.  The Converse user is then responsible for
64 broadcasting those handler numbers to other processors, and installing
65 them using CmiNumberHandler below.  The user should take care not to
66 invoke those handlers until they are fully installed.}
67
68 \function {int CmiRegisterHandlerLocal(CmiHandler h)}
69 \index{CmiRegisterHandlerLocal}
70 \desc{This function is used when one wishes to register functions
71 in a manner that is not consistent across processors.  This function
72 chooses a locally-meaningful number for the function, and records it
73 locally.  No attempt is made to ensure consistency across processors.}
74
75 \function {void CmiNumberHandler(int n, CmiHandler h)}
76 \index{CmiNumberHandler}
77 \desc{Forces the system to associate the specified handler number {\em n}
78 with the specified handler function {\em h}.  If the function number
79 {\em n} was previously mapped to some other function, that old mapping
80 is forgotten.  The mapping that this function creates is local to the
81 current processor.  CmiNumberHandler can be useful in combination with
82 CmiRegisterGlobalHandler.  It can also be used to implement
83 user-defined numbering schemes: such schemes should keep in mind that
84 the size of the table that holds the mapping is proportional to the
85 largest handler number --- do not use big numbers!}
86
87 Note: of the three registration methods, the CmiRegisterHandler method
88 is by far the simplest, and is strongly encouraged.  The others are
89 primarily to ease the porting of systems that already use similar
90 registration techniques.  One may use all three registration methods
91 in a program.  The system guarantees that no numbering conflicts will
92 occur as a result of this combination.
93
94 \section{Writing Handler Functions}
95 \label{handler2}
96
97 A message handler function is just a C function that accepts a void
98 pointer (to a message buffer) as an argument, and returns nothing.  The
99 handler may use the message buffer until it returns, at which time
100 Converse will automatically free the message buffer.  This behavior
101 can be overrided using CmiGrabBuffer:
102
103 \function{void CmiGrabBuffer(void **pbuf)}
104 \index{CmiGrabBuffer}
105 \desc{A handler function receives a pointer to a message buffer
106 as an argument.  Normally, it is supposed to copy the data out of the
107 message buffer before it returns, at which time Converse automatically
108 frees the message buffer.  However, a handler function may use
109 CmiGrabBuffer to claim ownership of the message buffer (and therefore
110 prevent Converse from freeing it).  Assuming, for example, that the
111 handler function called its argument {\tt msg}, it would call {\tt
112 CmiGrabBuffer(\&msg)}.  Afterward, {\tt msg} contains a pointer to the
113 message, or a copy of it.  From that point forward, it is the user's
114 responsibility to free the message using \param{CmiFree.}}
115
116 \section{Building Messages}
117
118 To send a message, one first creates a buffer to hold the message.
119 The buffer must be large enough to hold the header and the data.
120 The buffer can be in any kind of memory: it could be a local variable,
121 it could be a global, it could be allocated with {\tt malloc}, and
122 finally, it could be allocated with {\tt CmiAlloc}.  The Converse user
123 fills the buffer with the message data.  One puts a handler number
124 in the message, thereby specifying which handler function the message
125 should trigger when it arrives.  Finally, one uses a message-transmission
126 function to send the message.
127
128 The following functions are provided to help build message buffers:
129
130 \function{void *CmiAlloc(int size)}
131 \index{CmiAlloc}
132 \desc{Allocates memory of size \param{size} in heap and returns pointer to 
133 the usable space.  There are some message-sending functions that
134 accept only message buffers that were allocated with CmiAlloc.  Thus,
135 this is the preferred way to allocate message buffers.}
136
137 \function{void CmiFree(void *ptr)}
138 \index{CmiFree}
139 \desc{This function frees the memory pointed to by \param{ptr}. \param{ptr}
140 should be a pointer that was previously returned by \param{CmiAlloc}.}
141
142 \function {\#define CmiMsgHeaderSizeBytes}
143 \index{CmiMsgHeaderSizeBytes}
144 \desc{This constant contains the size of the message header.  When one
145 allocates a message buffer, one must set aside enough space for the header
146 and the data.  This macro helps you to do so.}
147
148 \function {void CmiSetHandler(int *MessageBuffer, int HandlerId)}
149 \index{CmiSetHandler}
150 \desc{This macro sets the handler number of a message to \param{HandlerId}.}
151
152 \function {int CmiGetHandler(int *MessageBuffer)}
153 \index{CmiGetHandler}
154 \desc{This call returns the handler of a message in the form of a
155 handler number.}
156  
157 \function {CmiHandler CmiGetHandlerFunction(int *MessageBuffer)}
158 \index{CmiGetHandlerFunction}
159 \desc{This call returns the handler of a message in the form of a
160 function pointer.}
161
162 \section{Sending Messages}
163
164 The following functions allow you to send messages.  Our model is that
165 the data starts out in the message buffer, and from there gets
166 transferred ``into the network''.  The data stays ``in the network''
167 for a while, and eventually appears on the target processor.  Using
168 that model, each of these send-functions is a device that transfers
169 data into the network.  None of these functions wait for the data to
170 be delivered.
171
172 On some machines, the network accepts data rather slowly.  We don't
173 want the process to sit idle, waiting for the network to accept the
174 data.  So, we provide several variations on each send function:
175
176 \begin{itemize}
177
178 \item{{\bf sync}: a version that is as simple as possible, pushing the
179 data into the network and not returning until the data is ``in the
180 network''.  As soon as a sync function returns, you can reuse the
181 message buffer.}
182
183 \item{{\bf async}: a version that returns almost instantaneously, and then
184 continues working in the background.  The background job transfers the
185 data from the message buffer into the network.  Since the background job
186 is still using the message buffer when the function returns, you can't
187 reuse the message buffer immediately.  The background job sets a flag
188 when it is done and you can then reuse the message buffer.}
189
190 \item{{\bf sync and free}: a version that returns almost instantaneously,
191 and then continues working in the background.  The background job
192 transfers the data from the message buffer into the network.  When the
193 background job finishes, it {\tt CmiFree}s the message buffer.  In
194 this situation, you can't reuse the message buffer at all.  Of course,
195 to use a function of this type, you must allocate the message buffer
196 using {\tt CmiAlloc}.}
197
198 \end{itemize}
199
200 \function{void CmiSyncSend(unsigned int destPE, unsigned int size, void *msg)}
201 \index{CmiSyncSend}
202 \desc{Sends \param{msg} of size \param{size} bytes to processor
203 \param{destPE}.  When it returns, you may reuse the message buffer.}
204
205 \function{void CmiSyncSendAndFree(unsigned int destPE, unsigned int size, void *msg)}
206 \index{CmiSyncSendAndFree}
207 \desc{Sends \param{msg} of size \param{size} bytes to processor
208 \param{destPE}.  When it returns, the message buffer has been freed
209 using {\tt CmiFree}}
210
211 \function{CmiCommHandle CmiAsyncSend(unsigned int destPE, unsigned int size, void *msg)}
212 \index{CmiAsyncSend}
213 \desc{Sends \param{msg} of size \param{size} bytes to processor
214 \param{destPE}.  It returns a communication handle which can be
215 tested using CmiAsyncMsgSent: when this returns true, you may reuse
216 the message buffer.}
217
218 \function{void CmiSyncVectorSend(int destPE, int len, int sizes[], char *msgComps[])}
219 \desc{Concatenates several pieces of data and sends them to processor
220 \param{destPE}.  The data consists of \param{len} pieces residing in
221 different areas of memory, which are logically concatenated.  The
222 \param{msgComps} array contains pointers to the pieces; the size of
223 \param{msgComps[i]} is taken from \param{sizes[i]}. 
224 When it returns, \param{sizes}, \param{msgComps} and the message
225 components specified in \param{msgComps} can be immediately reused.}
226
227 \function{void CmiSyncVectorSendAndFree(int destPE, int len, int sizes[], char *msgComps[])}
228 \desc{Concatenates several pieces of data and sends them to processor
229 \param{destPE}.  The data consists of \param{len} pieces residing in
230 different areas of memory, which are logically concatenated.  The
231 \param{msgComps} array contains pointers to the pieces; the size of
232 \param{msgComps[i]} is taken from \param{sizes[i]}. 
233 The message components specified in \param{msgComps} are {\tt
234 CmiFree}d by this function therefore, they should be dynamically
235 allocated using \param{CmiAlloc()}.  However, the \param{sizes} and
236 \param{msgComps} array themselves are not freed.}
237
238 \function{CmiCommHandle CmiAsyncVectorSend(int destPE, int len, int sizes[], char *msgComps[])}
239 \desc{Concatenates several pieces of data and sends them to processor
240 \param{destPE}.  The data consists of \param{len} pieces residing in
241 different areas of memory, which are logically concatenated.  The
242 \param{msgComps} array contains pointers to the pieces; the size of
243 \param{msgComps[i]} is taken from \param{sizes[i]}. 
244 The individual pieces of data as well as the arrays \param{sizes} and
245 \param{msgComps} should not be overwritten or freed before the
246 communication is complete.  This function returns a communication
247 handle which can be tested using CmiAsyncMsgSent: when this returns
248 true, the input parameters can be reused.}
249
250 \function{int CmiAsyncMsgSent(CmiCommHandle handle)}
251 \index{CmiAsyncMsgSent}
252 \desc{Returns true if the communication specified by the given
253 CmiCommHandle has proceeded to the point where the message buffer can
254 be reused.}
255
256 \function{void CmiReleaseCommHandle(CmiCommHandle handle)}
257 \index{CmiReleaseCommHandle}
258 \desc{Releases the communication handle \param{handle} and
259 associated resources. It does not free the message buffer.}
260
261 \function{void CmiMultipleSend(unsigned int destPE, int len, int sizes[], char
262 *msgComps[])}
263 \index{CmiMultipleSend}
264 \desc{This function allows the user to send many multiple messages that may be
265 destined for the SAME PE in one go. This is more efficient than sending
266 each message to the destination node separately. This function assumes
267 that the handlers that are to receive this message have already been set.
268 If this is not done, the behavior of the function is undefined.
269
270 In the function, The {\bf destPE} parameter identifies the destination
271 processor.
272
273 The {\bf len} argument identifies the {\it number} of messages that are to
274 be sent in one go. 
275
276 The {\bf sizes[]} array is an array of sizes of each of these messages.
277
278 The {\bf msgComps[]} array is the array of the messages. 
279
280 The indexing in each array is from 0 to len - 1.
281
282 {\bf Note:}
283
284 Before calling this function, the program needs to initialise the system
285 to be able to provide this service. This is done by calling the function
286 {\bf void CmiInitMultipleSendRoutine(void) }. Unless this function is
287 called, the system will not be able to provide the service to the user.
288 }
289
290 \section{Broadcasting Messages}
291
292 \function{void CmiSyncBroadcast(unsigned int size, void *msg)}
293 \index{CmiSyncBroadcast}
294 \desc{Sends \param{msg} of length \param{size} bytes to all processors
295 excluding the processor on which the caller resides. }
296
297 \function{void CmiSyncBroadcastAndFree(unsigned int size, void *msg)}
298 \index{CmiSyncBroadcastAndFree}
299 \desc{Sends \param{msg} of length \param{size} bytes to all processors
300 excluding the processor on which the caller resides.  Uses {\tt
301 CmiFree} to deallocate the message buffer for \param{msg} when the
302 broadcast completes. Therefore \param{msg} must point to a buffer
303 allocated with {\tt CmiAlloc}.}
304
305 \function{void CmiSyncBroadcastAll(unsigned int size, void *msg)}
306 \index{CmiSyncBroadcastAll}
307 \desc{Sends \param{msg} of length \param{size} bytes to all processors
308 including the processor on which the caller resides. This function
309 does not free the message buffer for \param{msg}.}
310
311 \function{void CmiSyncBroadcastAllAndFree(unsigned int size, void *msg)}
312 \index{CmiSyncBroadcastAllAndFree}
313 \desc{Sends \param{msg} of length \param{size} bytes to all processors
314 including the processor on which the caller resides. This function
315 frees the message buffer for \param{msg} before returning, so
316 \param{msg} must point to a dynamically allocated buffer.}
317
318 \function{CmiCommHandle CmiAsyncBroadcast(unsigned int size, void *msg)}
319 \index{CmiAsyncBroadcast}
320 \desc{Initiates asynchronous broadcast of message \param{msg} of
321 length \param{size} bytes to all processors excluding the processor on
322 which the caller resides. It returns a communication handle which
323 could be used to check the status of this send using
324 \param{CmiAsyncMsgSent()}. \param{msg} should not be overwritten or
325 freed before the communication is complete.}
326
327 \function{CmiCommHandle CmiAsyncBroadcastAll(unsigned int size, void *msg)}
328 \index{CmiAsyncBroadcastAll}
329 \desc{Initiates asynchronous broadcast of message \param{msg} of
330 length \param{size} bytes to all processors including the processor on
331 which the caller resides. It returns a communication handle which
332 could be used to check the status of this send using
333 \param{CmiAsyncMsgSent()}. \param{msg} should not be overwritten or
334 freed before the communication is complete.}
335
336 \section{Multicasting Messages}
337
338 \function{typedef ... CmiGroup;}
339 \index{CmiGroup}
340 \desc{A CmiGroup represents a set of processors.  It is an opaque type.
341 Group IDs are useful for the multicast functions below.}
342
343 \function{CmiGroup CmiEstablishGroup(int npes, int *pes);}
344 \index{CmiGroup}
345 \desc{Converts an array of processor numbers into a group ID.  Group
346 IDs are useful for the multicast functions below.  Caution: this call
347 uses up some resources.  In particular, establishing a group uses 
348 some network bandwidth (one broadcast's worth) and a small amount of
349 memory on all processors.}
350
351 \function{void CmiSyncMulticast(CmiGroup grp, unsigned int size, void *msg)}
352 \index{CmiSyncBroadcast}
353 \desc{Sends \param{msg} of length \param{size} bytes to all members
354 of the specified group.  Group IDs are created using
355 \param{CmiEstablishGroup}.}
356
357 \function{void CmiSyncMulticastAndFree(CmiGroup grp, unsigned int size, void *msg)}
358 \index{CmiSyncBroadcastAndFree}
359 \desc{Sends \param{msg} of length \param{size} bytes to all members
360 of the specified group.  Uses {\tt CmiFree} to deallocate the
361 message buffer for \param{msg} when the broadcast completes. Therefore
362 \param{msg} must point to a buffer allocated with {\tt CmiAlloc}.
363 Group IDs are created using \param{CmiEstablishGroup}.}
364
365 \function{CmiCommHandle CmiAsyncMulticast(CmiGroup grp, unsigned int size, void *msg)}
366 \index{CmiAsyncBroadcast}
367 \desc{Not yet implemented. Initiates asynchronous broadcast of
368 message \param{msg} of length \param{size} bytes to all members of
369 the specified group.  It returns a communication handle which could
370 be used to check the status of this send using
371 \param{CmiAsyncMsgSent()}. \param{msg} should not be overwritten or
372 freed before the communication is complete.
373 Group IDs are created using \param{CmiEstablishGroup}.}
374
375 \function{void CmiSyncListSend(int npes, int *pes, unsigned int size, void *msg)}
376 \index{CmiSyncBroadcast}
377 \desc{Not yet implemented. Sends \param{msg} of length \param{size} bytes
378 to all processors in the list.  Group IDs are created using
379 \param{CmiEstablishGroup}.}
380
381 \function{void CmiSyncMulticastAndFree(int npes, int *pes, unsigned int size, void *msg)}
382 \index{CmiSyncBroadcastAndFree}
383 \desc{Not yet implemented. Sends \param{msg} of length \param{size}
384 bytes to all processors in the list.  Uses {\tt CmiFree} to deallocate the
385 message buffer for \param{msg} when the broadcast completes. Therefore
386 \param{msg} must point to a buffer allocated with {\tt CmiAlloc}.
387 Group IDs are created using \param{CmiEstablishGroup}.}
388
389 \function{CmiCommHandle CmiAsyncMulticast(int npes, int *pes, unsigned int size, void *msg)}
390 \index{CmiAsyncBroadcast}
391 \desc{Not yet implemented. Initiates asynchronous broadcast of
392 message \param{msg} of length \param{size} bytes to all processors
393 in the list.  It returns a communication handle which could
394 be used to check the status of this send using
395 \param{CmiAsyncMsgSent()}. \param{msg} should not be overwritten or
396 freed before the communication is complete.
397 Group IDs are created using \param{CmiEstablishGroup}.}
398
399 \section{Scheduling Messages}
400 \label{schedqueue}
401
402 The scheduler queue is a powerful priority queue.  The following
403 functions can be used to place messages into the scheduler queue.
404 These messages are treated very much like newly-arrived messages: when
405 they reach the front of the queue, they trigger handler functions,
406 just like messages transmitted with Cmi functions.  Note that unlike
407 the Cmi send functions, these cannot move messages across processors.
408
409 Every message inserted into the queue has a priority associated with
410 it.  Converse priorities are arbitrary-precision numbers between 0 and
411 1.  Priorities closer to 0 get processed first, priorities closer to 1
412 get processed last.  Arbitrary-precision priorities are very useful in
413 AI search-tree applications. Suppose we have a heuristic suggesting
414 that tree node N1 should be searched before tree node N2. We therefore
415 designate that node N1 and its descendants will use high priorities,
416 and that node N2 and its descendants will use lower priorities. We
417 have effectively split the range of possible priorities in two. If
418 several such heuristics fire in sequence, we can easily split the
419 priority range in two enough times that no significant bits remain,
420 and the search begins to fail for lack of meaningful priorities to
421 assign. The solution is to use arbitrary-precision priorities, aka
422 bitvector priorities.
423
424 These arbitrary-precision numbers are represented as bit-strings: for
425 example, the bit-string ``0011000101'' represents the binary number
426 (.0011000101).  The format of the bit-string is as follows: the
427 bit-string is represented as an array of unsigned integers. The most
428 significant bit of the first integer contains the first bit of the
429 bitvector.  The remaining bits of the first integer contain the next
430 31 bits of the bitvector.  Subsequent integers contain 32 bits
431 each. If the size of the bitvector is not a multiple of 32, then the
432 last integer contains 0 bits for padding in the least-significant bits
433 of the integer.
434
435 Some people only want regular integers as priorities.  For
436 simplicity's sake, we provide an easy way to convert integer
437 priorities to Converse's built-in representation.
438
439 In addition to priorities, you may choose to enqueue a message
440 ``LIFO'' or ``FIFO''.  Enqueueing a message ``FIFO'' simply pushes it
441 behind all the other messages of the same priority.  Enqueueing a
442 message ``LIFO'' pushes it in front of other messages of the same
443 priority.
444
445 Messages sent using the CMI functions take precedence over everything
446 in the scheduler queue, regardless of priority.
447
448 \function{void CsdEnqueueGeneral(void *Message, int strategy, int priobits, int *prioptr)}
449 \index{CsdEnqueueGeneral}
450 \desc{This call enqueues a message to the scheduler's queue, to
451 be sorted according to its priority and the queueing \param{strategy}.
452 The meaning of the \param{priobits} and \param{prioptr} fields depend
453 on the value of \param{strategy}, which can be any of the following:
454
455 \begin{itemize}
456 \item{{\tt CQS\_QUEUEING\_BFIFO}: the priobits and prioptr point to
457 a bit-string representing an arbitrary-precision priority.  The message
458 is pushed behind all other message of this priority.}
459
460 \item{{\tt CQS\_QUEUEING\_BLIFO}: the priobits and prioptr point to
461 a bit-string representing an arbitrary-precision priority.  The message
462 is pushed in front all other message of this priority.}
463
464 \item{{\tt CQS\_QUEUEING\_IFIFO}: the prioptr is a pointer to a
465 signed integer.  The integer is converted to a bit-string priority,
466 normalizing so that the integer zero is converted to the bit-string
467 ``1000...'' (the ``middle'' priority).  To be more specific, the
468 conversion is performed by adding 0x80000000 to the integer, and then
469 treating the resulting 32-bit quantity as a 32-bit bitvector priority.
470 The message is pushed behind all other messages of this priority.}
471
472 \item{{\tt CQS\_QUEUEING\_ILIFO}: the prioptr is a pointer to a
473 signed integer.  The integer is converted to a bit-string priority,
474 normalizing so that the integer zero is converted to the bit-string
475 ``1000...'' (the ``middle'' priority).  To be more specific, the
476 conversion is performed by adding 0x80000000 to the integer, and then
477 treating the resulting 32-bit quantity as a 32-bit bitvector priority.
478 The message is pushed in front of all other messages of this
479 priority.}
480
481 \item{{\tt CQS\_QUEUEING\_FIFO}: the prioptr and priobits are ignored.
482 The message is enqueued with the middle priority ``1000...'', and is
483 pushed behind all other messages with this priority.}
484
485 \item{{\tt CQS\_QUEUEING\_LIFO}: the prioptr and priobits are ignored.
486 The message is enqueued with the middle priority ``1000...'', and is
487 pushed in front of all other messages with this priority.}
488
489 \end{itemize}
490
491 Caution: the priority itself is {\em not copied} by the scheduler.
492 Therefore, if you pass a pointer to a priority into the scheduler, you
493 must not overwrite or free that priority until after the message has
494 emerged from the scheduler's queue.  It is normal to actually store
495 the priority {\em in the message itself}, though it is up to the user
496 to actually arrange storage for the priority.
497 }
498
499 \function {void CsdEnqueue(void *Message)}
500 \index{CsdEnqueue}
501 \desc{This macro is a shorthand for 
502 {\tt CsdEnqueueGeneral(Message, CQS\_QUEUEING\_FIFO,0, NULL)} 
503 provided here for backward compatibility.}
504
505 \function{void CsdEnqueueFifo(void *Message)}
506 \index{CsdEnqueueFifo}
507 \desc{This macro is a shorthand for 
508 {\tt CsdEnqueueGeneral(Message, CQS\_QUEUEING\_FIFO,0, NULL)} 
509 provided here for backward compatibility.}
510
511 \function{void CsdEnqueueLifo(void *Message)}
512 \index{CsdEnqueueLifo}
513 \desc{This macro is a shorthand for
514 {\tt CsdEnqueueGeneral(Message, CQS\_QUEUEING\_LIFO,0, NULL)} 
515 provided here for backward compatibility.}
516
517 \function{int CsdEmpty()}
518 \index{CsdEmpty}
519 \desc{This function returns non-zero integer when the scheduler's queue
520 is empty, zero otherwise.}
521
522 \section{Polling for Messages}
523 \label{polling}
524
525 As we stated earlier, Converse messages trigger handler functions when
526 they arrive.  In fact, for this to work, the processor must
527 occasionally poll for messages.  When the user starts Converse, he can
528 put it into one of several modes.  In the normal mode, the message
529 polling happens automatically.  However {\em user-calls-scheduler}
530 mode is designed to let the user poll manually.  To do this, the user
531 must use one of two polling functions: CmiDeliverMsgs, or
532 CsdScheduler.  CsdScheduler is more general, it will notice any
533 Converse event.  CmiDeliverMsgs is a lower-level function that ignores
534 all events except for recently-arrived messages.  (In particular, it
535 ignores messages in the scheduler queue).  You can save a tiny amount
536 of overhead by using the lower-level function.  We recommend the use
537 of CsdScheduler for all applications except those that are using only
538 the lowest level of Converse, the Cmi.  A third polling function,
539 CmiDeliverSpecificMsg, is used when you know the exact event you want
540 to wait for: it does not allow any other event to occur.
541
542 \function {void CsdScheduler(int NumberOfMessages)}
543 \index{CsdScheduler}
544 \desc{This call invokes the Converse scheduler, which repeatedly
545 delivers messages to their handlers (i.e. invokes the handler for each
546 message it selects).  In each iteration, the scheduler first looks for
547 any message that has arrived from another processor, and delivers it.
548 If there isn't any, it selects a message from the locally enqueued
549 messages, and delivers it.  The {\tt NumberOfMessages} parameter
550 specifies how many messages should be processed (i.e. delivered to
551 their handlers). If set to -1, the scheduler continues delivering
552 messages until CsdExitScheduler() is called from a message handler.
553 if {\tt NumberOfMessages} is 0, the scheduler continues delivering
554 messages until it exhausts its supply of messages (i.e. becomes idle)
555 or some handler calls CsdExitScheduler().}
556
557 \function{int CmiDeliverMsgs(int MaxMsgs)}
558 \index{CmiDeliverMsgs}
559 \desc{Retrieves messages from the network message queue and invokes 
560 corresponding handler functions for arrived messages. This function 
561 returns after either the network message queue becomes empty or after
562 \param{MaxMsgs} messages have been retrieved and their handlers called. 
563 It returns the difference between total messages delivered and \param{MaxMsgs}.
564 The handler is given a pointer to the message as  its parameter.}
565
566 \function{void CmiDeliverSpecificMsg(int HandlerId)}
567 \index{CmiDeliverSpecificMsg}
568 \desc{Retrieves messages from the network queue and delivers the first
569 message with its handler field equal to \param{HandlerId}. This functions
570 leaves alone all other messages. It returns after the invoked handler
571 function returns.}
572
573 \function {void CsdExitScheduler(void)}
574 \index{CsdExitScheduler}
575 \desc{This call causes CsdScheduler to stop processing messages when
576 control has returned back to it. The scheduler then returns to its
577 calling routine.}
578
579 \section{Scheduler Callbacks}
580 \label{schedcallbacks}
581
582 Scheduler callbacks are provided for programmers who want to utilize in
583 some way the event of scheduler becoming idle, or the scheduler becoming
584 busy again.  Typically, these callbacks are useful for determining idle
585 time in complex multilingual programs.  The callback function should not
586 contain calls to scheduler related functions.  Also, the callback
587 functions should not block indefinitely.  Doing so will cause the
588 conditional callbacks to fail.  Following functions are provided for
589 controlling the scheduler callbacks.
590
591 \function{void CsdStartNotifyIdle(void)}
592 \index{CsdStartNotifyIdle}
593 \desc{This call causes CsdScheduler to invoke callback functions for
594 idle and busy notifications. Initially, the scheduler does not call
595 any callback functions.}
596
597 \function{void CsdStopNotifyIdle(void)}
598 \index{CsdStopNotifyIdle}
599 \desc{This call causes CsdScheduler to stop invoking callback functions
600 for idle and busy norifications.}
601
602 \function{void CsdSetNotifyIdle(void (* fIdle)(void), void (* fBusy)(void))}
603 \index{CsdSetNotifyIdle}
604 \desc{This call registers the functions to be called when CsdScheduler becomes
605 idle (\param{fIdle}) or busy (\param{fBusy}). These functions can be
606 overridden with another call to CsdSetNotifyIdle.}
607
608 \internal{
609 \section{Global Pointer}
610
611 \function{int CmiGptrCreate(GlobalPtr *gptr, void *lptr, unsigned int size)}
612 \desc{This function creates a global pointer by initializing contents of
613 \param{*gptr} to point to memory on the local processor pointed to by
614 \param{lptr} of \param{size} bytes. \param{*gptr} could then be sent to other 
615 processors, and could be used by \param{CmiGet()} and \param{CmiPut()}
616 to read and write this memory by remote processors. This functions returns
617 a positive integer on success.}
618
619 \function{void *CmiGptrDref(GlobalPtr *gptr)}
620 \desc{This function returns the address of local memory associated
621 with global pointer \param{gptr}.}
622
623 \function{int CmiSyncGet(GlobalPtr *gptr, void *lptr, unsigned int size)}
624 \desc{Copies \param{size} bytes from 
625 memory pointed to by global pointer \param{gptr}
626 to local memory pointed to by \param{lptr}. 
627 This is a synchronous operation and the calling processor blocks until
628 the data is transferred to local memory. This function returns
629 a positive integer on success.}
630
631 \function{CommHandle CmiGet(GlobalPtr *gptr, void *lptr, unsigned int size)}
632 \desc{Initiates copying of \param{size} bytes from 
633 memory pointed to by global pointer \param{gptr}
634 to local memory pointed to by \param{lptr}. 
635 This function returns a  communication handle which could be used
636 to  enquire about the status of this operation.}
637
638 \function{CommHandle CmiPut(GlobalPtr *gptr, void *lptr, unsigned int size)}
639 \desc{Initiates copying of \param{size} bytes from a processor's local
640 memory pointed to by \param{lptr} to the memory pointed to by global
641 pointer \param{gptr}.  This function returns a  communication handle
642 which could be used to  enquire about the status of this operation.}
643 }
644
645 \section{The Timer}
646
647 \function{double CmiTimer(void)}
648 \index{CmiTimer}
649 \desc{Returns current value of the timer in seconds. This is
650 typically the time spent since the \param{ConverseInit()} call.
651 The precision of this timer is the best available on the particular machine,
652 and usually has at least microsecond accuracy.}
653
654 \section{Processor Ids}
655
656 \function{int CmiNumPe(void)}
657 \index{CmiNumPe}
658 \desc{Returns the total number of processors on which the 
659 parallel program is being run.}
660
661 \function{int CmiMyPe(void)}
662 \index{CmiMyPe}
663 \desc{Returns the logical processor identifier of processor on which the 
664 caller resides. A processor Id is between \param{0} and \param{CmiNumPe()-1}.}
665
666 Also see the calls in Section~\ref{utility}.  % put a ref here..??
667
668 \input{cpvmacros}
669
670 \section{Input/Output}
671
672 \function{void CmiPrintf(char *format, arg1, arg2, ...)}
673 \index{CmiPrintf}
674 \desc{This function does an atomic \param{printf()} on \param{stdout}. 
675 On machine with host, this is implemented on top of the messaging 
676 layer using asynchronous sends.}
677
678 \function{int CmiScanf(char *format, void *arg1, void *arg2, ...)}
679 \index{CmiScanf}
680 \desc{This function performs an atomic \param{scanf} from \param{stdin}.
681 The processor, on which the caller resides, blocks for input. On machines with
682 host, this is implemented on top of the messaging layer using asynchronous
683 send and blocking receive.}
684
685 \function{void CmiError(char *format, arg1, arg2, ...)}
686 \index{CmiError}
687 \desc{This function does an atomic \param{printf()} on \param{stderr}. 
688 On machines with host, this is implemented on top of the messaging 
689 layer using asynchronous sends.}
690
691 \internal{
692 \section{Processor Groups}
693
694 \function{void CmiPgrpCreate(Pgrp *group)}
695 \desc{Creates a processor-group with calling processsor as the root processor.}
696
697 \function{void CmiPgrpDestroy(Pgrp *group)}
698 \desc{Frees resources associated with a processor group \param{group}.}
699
700 \function{void CmiAddChildren(Pgrp *group, int penum, int size, int procs[])}
701 \desc{Adds \param{size} processors from array \param{procs[]} to the
702 processor-group \param{group} as children of processor penum. This function
703 could be called only by the root processor of processor-group \param{group}.}
704
705 \function{CommHandle CmiAsyncMulticast(Pgrp *group, unsigned int size, void *msg)}
706 \desc{Initiates asynchronous broadcast of message \param{msg} of
707 length \param{size} bytes to all processors belonging to \param{group}
708 excluding the processor on which the caller resides. It returns a
709 communication handle which could be used to check the status of this
710 send using \param{CmiAsyncMsgSent()}. \param{msg} should not be
711 overwritten or freed before the communication is complete. \note{Caller
712 need not belong to \param{group}.}} 
713
714 \function{int CmiPgrpRoot(Pgrp *group)}
715 \desc{Returns the processor id of root of processor-group \param{group}. }
716
717 \function{int CmiNumChildren(Pgrp *group, int penum)}
718 \desc{Returns  number of children of processor \param{penum} 
719 in the processor-group \param{group}.}
720
721 \function{int CmiParent(Pgrp *group, int penum)}
722 \desc{Returns  processor id of parent of processor \param{penum} 
723 in the processor-group \param{group}.}
724
725 \function{void CmiChildren(Pgrp *group, int node, int *children)}
726 \desc{Fills in array \param{children} with processor ids of all the
727 children processor \param{node} in processor-group \param{group}. This
728 array should at least be of size \param{CmiNumChildren()}.}
729 }
730
731 \section{Spanning Tree Calls}
732
733 Sometimes, it is convenient to view the nodes of the machine as a
734 tree.  For this purpose, Converse defines a tree over the nodes.  We
735 provide functions to obtain the parent and children of each node.  On
736 those machines where the communication topology is relevant, we
737 arrange the tree to optimize communication performance.
738
739 \function{int CmiSpanTreeRoot()}
740 \index{CmiSpanTreeRoot}
741 \desc{Returns the processor number of the root of the spanning tree.}
742
743 \function{int CmiSpanTreeParent(int procNum)}
744 \index{CmiSpanTreeParent}
745 \desc{This function returns the processor number of the parent of
746 \param{procNum} in the spanning tree.}
747
748 \function{int CmiNumSpanTreeChildren(int procNum)}
749 \index{CmiNumSpanTreeChildren}
750 \desc{Returns the number of children of \param{procNum} in the spanning tree.}
751
752 \function{void CmiSpanTreeChildren(int procNum, int *children)}
753 \index{CmiSpanTreeChildren}
754 \desc{This function fills the array \param{children} with processor
755 numbers of children of \param{procNum} in the spanning tree.}
756