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