Criminy.
[charm.git] / doc / converse / cmi.tex
1 \chapter{Converse Machine Interface}
2
3 \internal{
4 \section{Initialization and Wrap-Up}
5
6 \function{void ConverseInit(char *argv[])}
7 \index{ConverseInit}
8 \desc{This function initializes the machine interface. It should be
9 called prior to any other Converse functions. 
10 Multiple calls to this function in a process should
11 be avoided. \param{argv} is in similar format as passed to
12 \param{main(argc, argv)}. 
13 They would be utilized by \param{ConverseInit()} to initialize
14 machine specific parameters such as number of processors.}
15
16 \function{void ConverseExit(void)}
17 \index{ConverseExit}
18 \desc{This function frees the resources acquired by Converse and wraps up. 
19 Any other Converse function should not be called after a call to this function.
20 \note{It does not terminate the calling
21 process. A separate call to \param{exit()} is needed after 
22 \param{ConverseExit()} to achieve this.}}
23 }
24
25
26 \section{Converse Handlers and Handler Numbers}
27
28 Prior to sending a message, the Converse user writes a function that
29 the receiver of the message should use to {\em handle} the message.
30 The Converse user puts a reference to that function in the message,
31 and sends it to the destination processor.  The destination processor
32 automatically calls the user's {\em handler} function, passing it the
33 contents of the message.
34
35 Ideally, this would be achieved by putting a pointer to the
36 handler-function in the message.  However, in parallel programs
37 running on heterogeneous machines, sending a function-pointer in a
38 message doesn't work.  As a substitute, we use function-numbers.
39 During program initialization time, the handler-functions are assigned
40 numbers, and messages contain handler-numbers to specify which handler
41 should process the message.  
42
43 The following set of facilities are provided to assign handler-numbers
44 to handler-functions, and to store handler-numbers in messages.  Note
45 that while they may be called ``handler-numbers'', they can be used as
46 a general substitute for function-pointers in messages.  Of the
47 registration functions, the one which is normally used in Converse
48 programs is CmiRegisterHandler.
49
50 \function{typedef void (*CmiHandler)(void *)}
51 \index{CmiHandler}
52 \desc{Functions that handle Converse messages must be of this type.}
53
54 \function {\#define CmiMsgHeaderSizeBytes}
55 \index{CmiMsgHeaderSizeBytes}
56 \desc{Messages are stored in message buffers.  The first few bytes
57 of the message-buffer is always the CMI header.  This constant,
58 defined in {\tt converse.h}, denotes the size of the CMI message
59 header in bytes.  Every message buffer must allocate these many bytes
60 at its beginning for the header.}
61
62 \function {int CmiRegisterHandler(CmiHandler h)}
63 \index{CmiRegisterHandler}
64 \desc{This call registers a message handler with the CMI and returns a
65 handler index which can be subsequently used to specify the handler
66 for a message. All processors must register the same handlers, in the
67 same order, so that the handler-numbers remain consistent across
68 processes. All handlers must be registered on a processor before any
69 messages are received or sent by that processor.  For this purpose, it
70 is useful to register all handlers at the initialization stage of an
71 application.}
72
73 \function {void CmiSetHandler(int *MessageBuffer, int HandlerId)}
74 \index{CmiSetHandler}
75 \desc{This macro sets the handler field of a message to \param{HandlerId}.}
76  
77 \function {int CmiGetHandler(int *MessageBuffer)}
78 \index{CmiGetHandler}
79 \desc{This call returns the handler field of a message \param{MessageBuffer}.}
80  
81 \function {CmiHandler CmiGetHandlerFunction(int *MessageBuffer)}
82 \index{CmiGetHandlerFunction}
83 \desc{This call returns the handler function pointer for a message.}
84
85 \section{Point-To-Point Communication}
86
87 \function{void CmiSyncSend(unsigned int destPE, unsigned int size, void *msg)}
88 \index{CmiSyncSend}
89 \desc{Sends \param{msg} of size \param{size} bytes to processor
90 \param{destPE}. Message buffer for \param{msg} could be reused after
91 the call returns.
92 The first CmiMsgHeaderSizeBytes bytes of \param{msg} must be set aside
93 for use by the system.  (This applies to all the calls below that send
94 or broadcast a message.)}
95
96 \function{void CmiSyncSendAndFree(unsigned int destPE, unsigned int size, void *msg)}
97 \index{CmiSyncSendAndFree}
98 \desc{Sends \param{msg} of size \param{size} bytes to processor
99 \param{destPE} and frees the message buffer for \param{msg}.}
100
101 \function{CmiCommHandle CmiAsyncSend(unsigned int destPE, unsigned int size, void *msg)}
102 \index{CmiAsyncSend}
103 \desc{Initiates an asynchronous send of \param{msg} of length
104 \param{size} bytes to processor \param{destPE} and returns a
105 communication handle which could be used to enquire the status of this
106 communication. Message buffer for \param{mesg} should not be reused or freed
107 until communication is complete.}
108
109 \function{int CmiAsyncMsgSent(CmiCommHandle handle)}
110 \index{CmiAsyncMsgSent}
111 \desc{Returns the status of asynchronous send specified by
112 communication handle \param{handle}.}
113
114 \function{void CmiReleaseCommHandle(CmiCommHandle handle)}
115 \index{CmiReleaseCommHandle}
116 \desc{Releases the communication handle \param{handle} and
117 associated resources. It does not free the message buffer.
118 \param{handle} could be reused by CMI for another communication after
119 this call succeeds.}
120
121 \function{CmiCommHandle CmiAsyncVectorSend(int destPE, int len, int sizes[], char *msgComps[])}
122 \desc{Initiates an asynchronous send of data to processor
123 \param{destPE}.  The data consists of \param{len} pieces residing in
124 different areas of memory, which are logically concatenated.  The
125 \param{msgComps} array contains pointers to the pieces; the size of
126 \param{msgComps[i]} is taken from \param{sizes[i]}. 
127 This function returns a communication handle which could be used to enquire
128 about the status of communication using \param{CmiAsyncMsgSent()}.
129 Individual pieces of data as well as the arrays \param{sizes} and
130 \param{msgComps} should not be overwritten or freed before the
131 communication is complete.}
132
133 \function{void CmiSyncVectorSend(int destPE, int len, int sizes[], char *msgComps[])}
134 \desc{Synchronous send of data to processor
135 \param{destPE}.  The data consists of \param{len} pieces residing in
136 different areas of memory, which are logically concatenated.  The
137 \param{msgComps} array contains pointers to the pieces; the size of
138 \param{msgComps[i]} is taken from \param{sizes[i]}. 
139 \param{sizes}, \param{msgComps} and the message components specified in
140 \param{msgComps} could be reused after the function call returns.
141 }
142
143 \function{void CmiSyncVectorSendAndFree(int destPE, int len, int sizes[], char *msgComps[])}
144 \desc{Synchronous send of data to processor
145 \param{destPE}.  The data consists of \param{len} pieces residing in
146 different areas of memory, which are logically concatenated.  The
147 \param{msgComps} array contains pointers to the pieces; the size of
148 \param{msgComps[i]} is taken from \param{sizes[i]}. 
149 The message components specified in \param{msgComps} are freed by this function
150 therefore, they should be dynamically allocated using \param{CmiAlloc()}.
151 However, the \param{sizes} and \param{msgComps} array themselves are not
152 freed. 
153 }
154
155 \function{void CmiGrabBuffer(void **pbuf)}
156 \index{CmiGrabBuffer}
157 \desc{Transfers the ownership of the buffer pointed to by
158 \param{*pbuf} to the calling procedure. On machines where 
159 \param{*pbuf} points to a
160 system buffer which cannot be allocated to the user, 
161 CMI copies the buffer contents to newly allocated user
162 space and updates \param{*pbuf} to point to the new buffer.
163 In either case, the user should eventually free the buffer by calling
164 \param{CmiFree}.}
165
166 \function{int CmiDeliverMsgs(int MaxMsgs)}
167 \index{CmiDeliverMsgs}
168 \desc{Retrieves messages from the network message queue and invokes 
169 corresponding handler functions for arrived messages. This function 
170 returns after either the network message queue becomes empty or after
171 \param{MaxMsgs} messages have been retrieved and their handlers called. 
172 It returns the difference between total messages delivered and \param{MaxMsgs}.
173 The handler is given a pointer to the message as  its parameter.
174 Normally, the delivered message is owned by CMI,  and so the handler
175 should not free it, or store it for later use.  
176 If the handler wishes to  use the message later (for example, by
177 enqueueing the message with the scheduler), it must call
178 \param{CmiGrabBuffer()} to
179 acquire the  ownership of the message buffer.}
180
181 \function{void CmiDeliverSpecificMsg(int HandlerId)}
182 \index{CmiDeliverSpecificMsg}
183 \desc{Retrieves messages from the network queue and delivers the first message
184 with its handler field equal to \param{HandlerId}. This functions queues
185 the remaining messages retrieved from the network. It returns after the 
186 invoked handler function returns.}
187
188 \internal{
189 \section{Global Pointer}
190
191 \function{int CmiGptrCreate(GlobalPtr *gptr, void *lptr, unsigned int size)}
192 \desc{This function creates a global pointer by initializing contents of
193 \param{*gptr} to point to memory on the local processor pointed to by
194 \param{lptr} of \param{size} bytes. \param{*gptr} could then be sent to other 
195 processors, and could be used by \param{CmiGet()} and \param{CmiPut()}
196 to read and write this memory by remote processors. This functions returns
197 a positive integer on success.}
198
199 \function{void *CmiGptrDref(GlobalPtr *gptr)}
200 \desc{This function returns the address of local memory associated
201 with global pointer \param{gptr}.}
202
203 \function{int CmiSyncGet(GlobalPtr *gptr, void *lptr, unsigned int size)}
204 \desc{Copies \param{size} bytes from 
205 memory pointed to by global pointer \param{gptr}
206 to local memory pointed to by \param{lptr}. 
207 This is a synchronous operation and the calling processor blocks until
208 the data is transferred to local memory. This function returns
209 a positive integer on success.}
210
211 \function{CommHandle CmiGet(GlobalPtr *gptr, void *lptr, unsigned int size)}
212 \desc{Initiates copying of \param{size} bytes from 
213 memory pointed to by global pointer \param{gptr}
214 to local memory pointed to by \param{lptr}. 
215 This function returns a  communication handle which could be used
216 to  enquire about the status of this operation.}
217
218 \function{CommHandle CmiPut(GlobalPtr *gptr, void *lptr, unsigned int size)}
219 \desc{Initiates copying of \param{size} bytes from a processor's local
220 memory pointed to by \param{lptr} to the memory pointed to by global
221 pointer \param{gptr}.  This function returns a  communication handle
222 which could be used to  enquire about the status of this operation.}
223 }
224
225 \section{Broadcast}
226
227 \function{void CmiSyncBroadcast(unsigned int size, void *msg)}
228 \index{CmiSyncBroadcast}
229 \desc{Sends \param{msg} of length \param{size} bytes to all processors
230 excluding the processor on which the caller resides. }
231
232 \function{void CmiSyncBroadcastAndFree(unsigned int size, void *msg)}
233 \index{CmiSyncBroadcastAndFree}
234 \desc{Sends \param{msg} of length \param{size} bytes to all processors
235 excluding the processor on which the caller resides. Frees the message buffer
236 for \param{msg} when the broadcast completes. Therefore \param{msg} must
237 point to a dynamically allocated buffer.}
238
239 \function{void CmiSyncBroadcastAll(unsigned int size, void *msg)}
240 \index{CmiSyncBroadcastAll}
241 \desc{Sends \param{msg} of length \param{size} bytes to all processors
242 including the processor on which the caller resides. This function
243 does not free the message buffer for \param{msg}.}
244
245 \function{void CmiSyncBroadcastAllAndFree(unsigned int size, void *msg)}
246 \index{CmiSyncBroadcastAllAndFree}
247 \desc{Sends \param{msg} of length \param{size} bytes to all processors
248 including the processor on which the caller resides. This function
249 frees the message buffer for \param{msg} before returning, so
250 \param{msg} must point to a dynamically allocated buffer.}
251
252 \function{CmiCommHandle CmiAsyncBroadcast(unsigned int size, void *msg)}
253 \index{CmiAsyncBroadcast}
254 \desc{Initiates asynchronous broadcast of message \param{msg} of
255 length \param{size} bytes to all processors excluding the processor on
256 which the caller resides. It returns a communication handle which
257 could be used to check the status of this send using
258 \param{CmiAsyncMsgSent()}. \param{msg} should not be overwritten or
259 freed before the communication is complete.}
260
261 \function{CmiCommHandle CmiAsyncBroadcastAll(unsigned int size, void *msg)}
262 \index{CmiAsyncBroadcastAll}
263 \desc{Initiates asynchronous broadcast of message \param{msg} of
264 length \param{size} bytes to all processors including the processor on
265 which the caller resides. It returns a communication handle which
266 could be used to check the status of this send using
267 \param{CmiAsyncMsgSent()}. \param{msg} should not be overwritten or
268 freed before the communication is complete.}
269
270 \section{Timer}
271
272 \function{double CmiTimer(void)}
273 \index{CmiTimer}
274 \desc{Returns current value of the timer in seconds. This is
275 typically the time spent since the \param{ConverseInit()} call.
276 The precision of this timer is the best available on the particular machine,
277 and usually has at least microsecond accuracy.}
278
279 \section{Processor Ids}
280
281 \function{int CmiNumPe(void)}
282 \index{CmiNumPe}
283 \desc{Returns total number of processors in the machine on which the 
284 parallel program is being run.}
285
286 \function{int CmiMyPe(void)}
287 \index{CmiMyPe}
288 \desc{Returns the logical processor identifier of processor on which the 
289 caller resides. A processor Id is between \param{0} and \param{CmiNumPe()-1}.}
290
291 Also see the calls in Section~\ref{utility}.  % put a ref here..??
292
293 \section{Memory Management}
294
295 \function{void *CmiAlloc(int size)}
296 \index{CmiAlloc}
297 \desc{Allocates memory of size \param{size} in heap and returns pointer to 
298 the usable space. All the converse entities (e.g. messages) should be 
299 allocated with \param{CmiAlloc} and not with standard C library 
300 functions such as \param{malloc} because converse uses \param{CmiFree} to free 
301 these entities internally. \note{Currently this function is a simple wrapper
302 around \param{malloc}. However, in future, sophisticated memory allocation
303 strategies will be incorporated into converse.}}
304
305 \function{int CmiSize(void *ptr)}
306 \index{CmiSize}
307 \desc{This function returns the allocated size of memory pointed to by 
308 \param{ptr}. \param{ptr} should be returned by an earlier call to 
309 \param{CmiAlloc}.}
310
311 \function{void CmiFree(void *ptr)}
312 \index{CmiFree}
313 \desc{This function frees the memory pointed to by \param{ptr}. \param{ptr}
314 should be returned by an earlier call to \param{CmiAlloc}.}
315
316
317 \section{Input/Output}
318
319 \function{void CmiPrintf(char *format, arg1, arg2, ...)}
320 \index{CmiPrintf}
321 \desc{This function does an atomic \param{printf()} on \param{stdout}. 
322 On machine with host, this is implemented on top of the messaging 
323 layer using asynchronous sends.}
324
325 \function{int CmiScanf(char *format, void *arg1, void *arg2, ...)}
326 \index{CmiScanf}
327 \desc{This function performs an atomic \param{scanf} from \param{stdin}.
328 The processor, on which the caller resides, blocks for input. On machines with
329 host, this is implemented on top of the messaging layer using asynchronous
330 send and blocking receive.}
331
332 \function{void CmiError(char *format, arg1, arg2, ...)}
333 \index{CmiError}
334 \desc{This function does an atomic \param{printf()} on \param{stderr}. 
335 On machines with host, this is implemented on top of the messaging 
336 layer using asynchronous sends.}
337
338 \internal{
339 \section{Processor Groups}
340
341 \function{void CmiPgrpCreate(Pgrp *group)}
342 \desc{Creates a processor-group with calling processsor as the root processor.}
343
344 \function{void CmiPgrpDestroy(Pgrp *group)}
345 \desc{Frees resources associated with a processor group \param{group}.}
346
347 \function{void CmiAddChildren(Pgrp *group, int penum, int size, int procs[])}
348 \desc{Adds \param{size} processors from array \param{procs[]} to the
349 processor-group \param{group} as children of processor penum. This function
350 could be called only by the root processor of processor-group \param{group}.}
351
352 \function{CommHandle CmiAsyncMulticast(Pgrp *group, unsigned int size, void *msg)}
353 \desc{Initiates asynchronous broadcast of message \param{msg} of
354 length \param{size} bytes to all processors belonging to \param{group}
355 excluding the processor on which the caller resides. It returns a
356 communication handle which could be used to check the status of this
357 send using \param{CmiAsyncMsgSent()}. \param{msg} should not be
358 overwritten or freed before the communication is complete. \note{Caller
359 need not belong to \param{group}.}} 
360
361 \function{int CmiPgrpRoot(Pgrp *group)}
362 \desc{Returns the processor id of root of processor-group \param{group}. }
363
364 \function{int CmiNumChildren(Pgrp *group, int penum)}
365 \desc{Returns  number of children of processor \param{penum} 
366 in the processor-group \param{group}.}
367
368 \function{int CmiParent(Pgrp *group, int penum)}
369 \desc{Returns  processor id of parent of processor \param{penum} 
370 in the processor-group \param{group}.}
371
372 \function{void CmiChildren(Pgrp *group, int node, int *children)}
373 \desc{Fills in array \param{children} with processor ids of all the
374 children processor \param{node} in processor-group \param{group}. This
375 array should at least be of size \param{CmiNumChildren()}.}
376 }
377
378 \section{Spanning Tree Calls}
379
380 Converse defines a spanning tree organization of the processor procNums along
381 with routines for accessing elements of that tree.  The spanning tree
382 routines come in handy when writing programs with collective communication
383 because message communication patterns can be made to proceed along the
384 spanning tree arcs to avoid bottlenecks at a single procNum.
385
386 \function{int CmiSpanTreeRoot()}
387 \index{CmiSpanTreeRoot}
388 \desc{Returns the processor number of the root of the spanning tree.}
389
390 \function{int CmiSpanTreeParent(int procNum)}
391 \index{CmiSpanTreeParent}
392 \desc{This function returns the processor number of the parent of
393 \param{procNum} in the spanning tree.}
394
395 \function{int CmiNumSpanTreeChildren(int procNum)}
396 \index{CmiNumSpanTreeChildren}
397 \desc{Returns the number of children of \param{procNum} in the spanning tree.}
398
399 \function{void CmiSpanTreeChildren(int procNum, int *children)}
400 \index{CmiSpanTreeChildren}
401 \desc{This function fills the array \param{children} with processor
402 numbers of children of \param{procNum} in the spanning tree.}
403