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