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