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