Added multicast.
[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 \section{Broadcasting Messages}
262
263 \function{void CmiSyncBroadcast(unsigned int size, void *msg)}
264 \index{CmiSyncBroadcast}
265 \desc{Sends \param{msg} of length \param{size} bytes to all processors
266 excluding the processor on which the caller resides. }
267
268 \function{void CmiSyncBroadcastAndFree(unsigned int size, void *msg)}
269 \index{CmiSyncBroadcastAndFree}
270 \desc{Sends \param{msg} of length \param{size} bytes to all processors
271 excluding the processor on which the caller resides.  Uses {\tt
272 CmiFree} to deallocate the message buffer for \param{msg} when the
273 broadcast completes. Therefore \param{msg} must point to a buffer
274 allocated with {\tt CmiAlloc}.}
275
276 \function{void CmiSyncBroadcastAll(unsigned int size, void *msg)}
277 \index{CmiSyncBroadcastAll}
278 \desc{Sends \param{msg} of length \param{size} bytes to all processors
279 including the processor on which the caller resides. This function
280 does not free the message buffer for \param{msg}.}
281
282 \function{void CmiSyncBroadcastAllAndFree(unsigned int size, void *msg)}
283 \index{CmiSyncBroadcastAllAndFree}
284 \desc{Sends \param{msg} of length \param{size} bytes to all processors
285 including the processor on which the caller resides. This function
286 frees the message buffer for \param{msg} before returning, so
287 \param{msg} must point to a dynamically allocated buffer.}
288
289 \function{CmiCommHandle CmiAsyncBroadcast(unsigned int size, void *msg)}
290 \index{CmiAsyncBroadcast}
291 \desc{Initiates asynchronous broadcast of message \param{msg} of
292 length \param{size} bytes to all processors excluding the processor on
293 which the caller resides. It returns a communication handle which
294 could be used to check the status of this send using
295 \param{CmiAsyncMsgSent()}. \param{msg} should not be overwritten or
296 freed before the communication is complete.}
297
298 \function{CmiCommHandle CmiAsyncBroadcastAll(unsigned int size, void *msg)}
299 \index{CmiAsyncBroadcastAll}
300 \desc{Initiates asynchronous broadcast of message \param{msg} of
301 length \param{size} bytes to all processors including the processor on
302 which the caller resides. It returns a communication handle which
303 could be used to check the status of this send using
304 \param{CmiAsyncMsgSent()}. \param{msg} should not be overwritten or
305 freed before the communication is complete.}
306
307 \section{Multicasting Messages}
308
309 \function{typedef ... CmiGroup;}
310 \index{CmiGroup}
311 \desc{A CmiGroup represents a set of processors.  It is an opaque type.
312 Group IDs are useful for the multicast functions below.}
313
314 \function{CmiGroup CmiEstablishGroup(int npes, int *pes);}
315 \index{CmiGroup}
316 \desc{Converts an array of processor numbers into a group ID.  Group
317 IDs are useful for the multicast functions below.  Caution: this call
318 uses up some resources.  In particular, establishing a group uses 
319 some network bandwidth (one broadcast's worth) and a small amount of
320 memory on all processors.}
321
322 \function{void CmiSyncMulticast(CmiGroup grp, unsigned int size, void *msg)}
323 \index{CmiSyncBroadcast}
324 \desc{Sends \param{msg} of length \param{size} bytes to all members
325 of the specified group.  Group IDs are created using
326 \param{CmiEstablishGroup}.}
327
328 \function{void CmiSyncMulticastAndFree(CmiGroup grp, unsigned int size, void *msg)}
329 \index{CmiSyncBroadcastAndFree}
330 \desc{Sends \param{msg} of length \param{size} bytes to all members
331 of the specified group.  Uses {\tt CmiFree} to deallocate the
332 message buffer for \param{msg} when the broadcast completes. Therefore
333 \param{msg} must point to a buffer allocated with {\tt CmiAlloc}.
334 Group IDs are created using \param{CmiEstablishGroup}.}
335
336 \function{CmiCommHandle CmiAsyncMulticast(CmiGroup grp, unsigned int size, void *msg)}
337 \index{CmiAsyncBroadcast}
338 \desc{Not yet implemented. Initiates asynchronous broadcast of
339 message \param{msg} of length \param{size} bytes to all members of
340 the specified group.  It returns a communication handle which could
341 be used to check the status of this send using
342 \param{CmiAsyncMsgSent()}. \param{msg} should not be overwritten or
343 freed before the communication is complete.
344 Group IDs are created using \param{CmiEstablishGroup}.}
345
346 \function{void CmiSyncListSend(int npes, int *pes, unsigned int size, void *msg)}
347 \index{CmiSyncBroadcast}
348 \desc{Not yet implemented. Sends \param{msg} of length \param{size} bytes
349 to all processors in the list.  Group IDs are created using
350 \param{CmiEstablishGroup}.}
351
352 \function{void CmiSyncMulticastAndFree(int npes, int *pes, unsigned int size, void *msg)}
353 \index{CmiSyncBroadcastAndFree}
354 \desc{Not yet implemented. Sends \param{msg} of length \param{size}
355 bytes to all processors in the list.  Uses {\tt CmiFree} to deallocate the
356 message buffer for \param{msg} when the broadcast completes. Therefore
357 \param{msg} must point to a buffer allocated with {\tt CmiAlloc}.
358 Group IDs are created using \param{CmiEstablishGroup}.}
359
360 \function{CmiCommHandle CmiAsyncMulticast(int npes, int *pes, unsigned int size, void *msg)}
361 \index{CmiAsyncBroadcast}
362 \desc{Not yet implemented. Initiates asynchronous broadcast of
363 message \param{msg} of length \param{size} bytes to all processors
364 in the list.  It returns a communication handle which could
365 be used to check the status of this send using
366 \param{CmiAsyncMsgSent()}. \param{msg} should not be overwritten or
367 freed before the communication is complete.
368 Group IDs are created using \param{CmiEstablishGroup}.}
369
370 \section{Scheduling Messages}
371 \label{schedqueue}
372
373 The scheduler queue is a powerful priority queue.  The following
374 functions can be used to place messages into the scheduler queue.
375 These messages are treated very much like newly-arrived messages: when
376 they reach the front of the queue, they trigger handler functions,
377 just like messages transmitted with Cmi functions.  Note that unlike
378 the Cmi send functions, these cannot move messages across processors.
379
380 Every message inserted into the queue has a priority associated with
381 it.  Converse priorities are arbitrary-precision numbers between 0 and
382 1.  Priorities closer to 0 get processed first, priorities closer to 1
383 get processed last.  Arbitrary-precision priorities are very useful in
384 AI search-tree applications. Suppose we have a heuristic suggesting
385 that tree node N1 should be searched before tree node N2. We therefore
386 designate that node N1 and its descendants will use high priorities,
387 and that node N2 and its descendants will use lower priorities. We
388 have effectively split the range of possible priorities in two. If
389 several such heuristics fire in sequence, we can easily split the
390 priority range in two enough times that no significant bits remain,
391 and the search begins to fail for lack of meaningful priorities to
392 assign. The solution is to use arbitrary-precision priorities, aka
393 bitvector priorities.
394
395 These arbitrary-precision numbers are represented as bit-strings: for
396 example, the bit-string ``0011000101'' represents the binary number
397 (.0011000101).  The format of the bit-string is as follows: the
398 bit-string is represented as an array of unsigned integers. The most
399 significant bit of the first integer contains the first bit of the
400 bitvector.  The remaining bits of the first integer contain the next
401 31 bits of the bitvector.  Subsequent integers contain 32 bits
402 each. If the size of the bitvector is not a multiple of 32, then the
403 last integer contains 0 bits for padding in the least-significant bits
404 of the integer.
405
406 Some people only want regular integers as priorities.  For
407 simplicity's sake, we provide an easy way to convert integer
408 priorities to Converse's built-in representation.
409
410 In addition to priorities, you may choose to enqueue a message
411 ``LIFO'' or ``FIFO''.  Enqueueing a message ``FIFO'' simply pushes it
412 behind all the other messages of the same priority.  Enqueueing a
413 message ``LIFO'' pushes it in front of other messages of the same
414 priority.
415
416 Messages sent using the CMI functions take precedence over everything
417 in the scheduler queue, regardless of priority.
418
419 \function{void CsdEnqueueGeneral(void *Message, int strategy, int priobits, int *prioptr)}
420 \index{CsdEnqueueGeneral}
421 \desc{This call enqueues a message to the scheduler's queue, to
422 be sorted according to its priority and the queueing \param{strategy}.
423 The meaning of the \param{priobits} and \param{prioptr} fields depend
424 on the value of \param{strategy}, which can be any of the following:
425
426 \begin{itemize}
427 \item{{\tt CQS\_QUEUEING\_BFIFO}: the priobits and prioptr point to
428 a bit-string representing an arbitrary-precision priority.  The message
429 is pushed behind all other message of this priority.}
430
431 \item{{\tt CQS\_QUEUEING\_BLIFO}: the priobits and prioptr point to
432 a bit-string representing an arbitrary-precision priority.  The message
433 is pushed in front all other message of this priority.}
434
435 \item{{\tt CQS\_QUEUEING\_IFIFO}: the prioptr is a pointer to a
436 signed integer.  The integer is converted to a bit-string priority,
437 normalizing so that the integer zero is converted to the bit-string
438 ``1000...'' (the ``middle'' priority).  To be more specific, the
439 conversion is performed by adding 0x80000000 to the integer, and then
440 treating the resulting 32-bit quantity as a 32-bit bitvector priority.
441 The message is pushed behind all other messages of this priority.}
442
443 \item{{\tt CQS\_QUEUEING\_ILIFO}: the prioptr is a pointer to a
444 signed integer.  The integer is converted to a bit-string priority,
445 normalizing so that the integer zero is converted to the bit-string
446 ``1000...'' (the ``middle'' priority).  To be more specific, the
447 conversion is performed by adding 0x80000000 to the integer, and then
448 treating the resulting 32-bit quantity as a 32-bit bitvector priority.
449 The message is pushed in front of all other messages of this
450 priority.}
451
452 \item{{\tt CQS\_QUEUEING\_FIFO}: the prioptr and priobits are ignored.
453 The message is enqueued with the middle priority ``1000...'', and is
454 pushed behind all other messages with this priority.}
455
456 \item{{\tt CQS\_QUEUEING\_LIFO}: the prioptr and priobits are ignored.
457 The message is enqueued with the middle priority ``1000...'', and is
458 pushed in front of all other messages with this priority.}
459
460 \end{itemize}
461
462 Caution: the priority itself is {\em not copied} by the scheduler.
463 Therefore, if you pass a pointer to a priority into the scheduler, you
464 must not overwrite or free that priority until after the message has
465 emerged from the scheduler's queue.  It is normal to actually store
466 the priority {\em in the message itself}, though it is up to the user
467 to actually arrange storage for the priority.
468 }
469
470 \function {void CsdEnqueue(void *Message)}
471 \index{CsdEnqueue}
472 \desc{This macro is a shorthand for 
473 {\tt CsdEnqueueGeneral(Message, CQS\_QUEUEING\_FIFO,0, NULL)} 
474 provided here for backward compatibility.}
475
476 \function{void CsdEnqueueFifo(void *Message)}
477 \index{CsdEnqueueFifo}
478 \desc{This macro is a shorthand for 
479 {\tt CsdEnqueueGeneral(Message, CQS\_QUEUEING\_FIFO,0, NULL)} 
480 provided here for backward compatibility.}
481
482 \function{void CsdEnqueueLifo(void *Message)}
483 \index{CsdEnqueueLifo}
484 \desc{This macro is a shorthand for
485 {\tt CsdEnqueueGeneral(Message, CQS\_QUEUEING\_LIFO,0, NULL)} 
486 provided here for backward compatibility.}
487
488 \function{int CsdEmpty()}
489 \index{CsdEmpty}
490 \desc{This function returns non-zero integer when the scheduler's queue
491 is empty, zero otherwise.}
492
493 \section{Polling for Messages}
494 \label{polling}
495
496 As we stated earlier, Converse messages trigger handler functions when
497 they arrive.  In fact, for this to work, the processor must
498 occasionally poll for messages.  When the user starts Converse, he can
499 put it into one of several modes.  In the normal mode, the message
500 polling happens automatically.  However {\em user-calls-scheduler}
501 mode is designed to let the user poll manually.  To do this, the user
502 must use one of two polling functions: CmiDeliverMsgs, or
503 CsdScheduler.  CsdScheduler is more general, it will notice any
504 Converse event.  CmiDeliverMsgs is a lower-level function that ignores
505 all events except for recently-arrived messages.  (In particular, it
506 ignores messages in the scheduler queue).  You can save a tiny amount
507 of overhead by using the lower-level function.  We recommend the use
508 of CsdScheduler for all applications except those that are using only
509 the lowest level of Converse, the Cmi.  A third polling function,
510 CmiDeliverSpecificMsg, is used when you know the exact event you want
511 to wait for: it does not allow any other event to occur.
512
513 \function {void CsdScheduler(int NumberOfMessages)}
514 \index{CsdScheduler}
515 \desc{This call invokes the Converse scheduler, which repeatedly
516 delivers messages to their handlers (i.e. invokes the handler for each
517 message it selects).  In each iteration, the scheduler first looks for
518 any message that has arrived from another processor, and delivers it.
519 If there isn't any, it selects a message from the locally enqueued
520 messages, and delivers it.  The {\tt NumberOfMessages} parameter
521 specifies how many messages should be processed (i.e. delivered to
522 their handlers). If set to -1, the scheduler continues delivering
523 messages until CsdExitScheduler() is called from a message handler.
524 if {\tt NumberOfMessages} is 0, the scheduler continues delivering
525 messages until it exhausts its supply of messages (i.e. becomes idle)
526 or some handler calls CsdExitScheduler().}
527
528 \function{int CmiDeliverMsgs(int MaxMsgs)}
529 \index{CmiDeliverMsgs}
530 \desc{Retrieves messages from the network message queue and invokes 
531 corresponding handler functions for arrived messages. This function 
532 returns after either the network message queue becomes empty or after
533 \param{MaxMsgs} messages have been retrieved and their handlers called. 
534 It returns the difference between total messages delivered and \param{MaxMsgs}.
535 The handler is given a pointer to the message as  its parameter.}
536
537 \function{void CmiDeliverSpecificMsg(int HandlerId)}
538 \index{CmiDeliverSpecificMsg}
539 \desc{Retrieves messages from the network queue and delivers the first
540 message with its handler field equal to \param{HandlerId}. This functions
541 leaves alone all other messages. It returns after the invoked handler
542 function returns.}
543
544 \function {void CsdExitScheduler(void)}
545 \index{CsdExitScheduler}
546 \desc{This call causes CsdScheduler to stop processing messages when
547 control has returned back to it. The scheduler then returns to its
548 calling routine.}
549
550 \internal{
551 \section{Global Pointer}
552
553 \function{int CmiGptrCreate(GlobalPtr *gptr, void *lptr, unsigned int size)}
554 \desc{This function creates a global pointer by initializing contents of
555 \param{*gptr} to point to memory on the local processor pointed to by
556 \param{lptr} of \param{size} bytes. \param{*gptr} could then be sent to other 
557 processors, and could be used by \param{CmiGet()} and \param{CmiPut()}
558 to read and write this memory by remote processors. This functions returns
559 a positive integer on success.}
560
561 \function{void *CmiGptrDref(GlobalPtr *gptr)}
562 \desc{This function returns the address of local memory associated
563 with global pointer \param{gptr}.}
564
565 \function{int CmiSyncGet(GlobalPtr *gptr, void *lptr, unsigned int size)}
566 \desc{Copies \param{size} bytes from 
567 memory pointed to by global pointer \param{gptr}
568 to local memory pointed to by \param{lptr}. 
569 This is a synchronous operation and the calling processor blocks until
570 the data is transferred to local memory. This function returns
571 a positive integer on success.}
572
573 \function{CommHandle CmiGet(GlobalPtr *gptr, void *lptr, unsigned int size)}
574 \desc{Initiates copying of \param{size} bytes from 
575 memory pointed to by global pointer \param{gptr}
576 to local memory pointed to by \param{lptr}. 
577 This function returns a  communication handle which could be used
578 to  enquire about the status of this operation.}
579
580 \function{CommHandle CmiPut(GlobalPtr *gptr, void *lptr, unsigned int size)}
581 \desc{Initiates copying of \param{size} bytes from a processor's local
582 memory pointed to by \param{lptr} to the memory pointed to by global
583 pointer \param{gptr}.  This function returns a  communication handle
584 which could be used to  enquire about the status of this operation.}
585 }
586
587 \section{The Timer}
588
589 \function{double CmiTimer(void)}
590 \index{CmiTimer}
591 \desc{Returns current value of the timer in seconds. This is
592 typically the time spent since the \param{ConverseInit()} call.
593 The precision of this timer is the best available on the particular machine,
594 and usually has at least microsecond accuracy.}
595
596 \section{Processor Ids}
597
598 \function{int CmiNumPe(void)}
599 \index{CmiNumPe}
600 \desc{Returns the total number of processors on which the 
601 parallel program is being run.}
602
603 \function{int CmiMyPe(void)}
604 \index{CmiMyPe}
605 \desc{Returns the logical processor identifier of processor on which the 
606 caller resides. A processor Id is between \param{0} and \param{CmiNumPe()-1}.}
607
608 Also see the calls in Section~\ref{utility}.  % put a ref here..??
609
610 \input{cpvmacros}
611
612 \section{Input/Output}
613
614 \function{void CmiPrintf(char *format, arg1, arg2, ...)}
615 \index{CmiPrintf}
616 \desc{This function does an atomic \param{printf()} on \param{stdout}. 
617 On machine with host, this is implemented on top of the messaging 
618 layer using asynchronous sends.}
619
620 \function{int CmiScanf(char *format, void *arg1, void *arg2, ...)}
621 \index{CmiScanf}
622 \desc{This function performs an atomic \param{scanf} from \param{stdin}.
623 The processor, on which the caller resides, blocks for input. On machines with
624 host, this is implemented on top of the messaging layer using asynchronous
625 send and blocking receive.}
626
627 \function{void CmiError(char *format, arg1, arg2, ...)}
628 \index{CmiError}
629 \desc{This function does an atomic \param{printf()} on \param{stderr}. 
630 On machines with host, this is implemented on top of the messaging 
631 layer using asynchronous sends.}
632
633 \internal{
634 \section{Processor Groups}
635
636 \function{void CmiPgrpCreate(Pgrp *group)}
637 \desc{Creates a processor-group with calling processsor as the root processor.}
638
639 \function{void CmiPgrpDestroy(Pgrp *group)}
640 \desc{Frees resources associated with a processor group \param{group}.}
641
642 \function{void CmiAddChildren(Pgrp *group, int penum, int size, int procs[])}
643 \desc{Adds \param{size} processors from array \param{procs[]} to the
644 processor-group \param{group} as children of processor penum. This function
645 could be called only by the root processor of processor-group \param{group}.}
646
647 \function{CommHandle CmiAsyncMulticast(Pgrp *group, unsigned int size, void *msg)}
648 \desc{Initiates asynchronous broadcast of message \param{msg} of
649 length \param{size} bytes to all processors belonging to \param{group}
650 excluding the processor on which the caller resides. It returns a
651 communication handle which could be used to check the status of this
652 send using \param{CmiAsyncMsgSent()}. \param{msg} should not be
653 overwritten or freed before the communication is complete. \note{Caller
654 need not belong to \param{group}.}} 
655
656 \function{int CmiPgrpRoot(Pgrp *group)}
657 \desc{Returns the processor id of root of processor-group \param{group}. }
658
659 \function{int CmiNumChildren(Pgrp *group, int penum)}
660 \desc{Returns  number of children of processor \param{penum} 
661 in the processor-group \param{group}.}
662
663 \function{int CmiParent(Pgrp *group, int penum)}
664 \desc{Returns  processor id of parent of processor \param{penum} 
665 in the processor-group \param{group}.}
666
667 \function{void CmiChildren(Pgrp *group, int node, int *children)}
668 \desc{Fills in array \param{children} with processor ids of all the
669 children processor \param{node} in processor-group \param{group}. This
670 array should at least be of size \param{CmiNumChildren()}.}
671 }
672
673 \section{Spanning Tree Calls}
674
675 Sometimes, it is convenient to view the nodes of the machine as a
676 tree.  For this purpose, Converse defines a tree over the nodes.  We
677 provide functions to obtain the parent and children of each node.  On
678 those machines where the communication topology is relevant, we
679 arrange the tree to optimize communication performance.
680
681 \function{int CmiSpanTreeRoot()}
682 \index{CmiSpanTreeRoot}
683 \desc{Returns the processor number of the root of the spanning tree.}
684
685 \function{int CmiSpanTreeParent(int procNum)}
686 \index{CmiSpanTreeParent}
687 \desc{This function returns the processor number of the parent of
688 \param{procNum} in the spanning tree.}
689
690 \function{int CmiNumSpanTreeChildren(int procNum)}
691 \index{CmiNumSpanTreeChildren}
692 \desc{Returns the number of children of \param{procNum} in the spanning tree.}
693
694 \function{void CmiSpanTreeChildren(int procNum, int *children)}
695 \index{CmiSpanTreeChildren}
696 \desc{This function fills the array \param{children} with processor
697 numbers of children of \param{procNum} in the spanning tree.}
698