add irecv.tex
[charm.git] / doc / libraries / irecv.tex
1 \section{Irecv Library}
2
3 {\sc Irecv} library provides asynchronous communication mode for chare array. The program breaks into two parts("split phase" structure): nonblocking send, receives and iwait, and callback functions. It provides a style that mpi programmers may find intuitive. 
4
5 There are there functions in Irecv library.
6
7 1 void generic(receiverMsg *);
8 Message type "receiverMsg" is a varsize message. There are four fields need to be filled after allocating the message:
9 int tag: regular tag;
10 int sendFrom: sending object index;
11 int refno: reference number, usually the iteration number.
12 char *buf:   message buffer
13   
14
15 2 void irecv(int tag, char *pointer, int size, int senderTag, int refno);
16 irecv will register tags and pointer to the library, that it copy the matching message(with tags) into the location given by the "pointer".
17
18 3 void iwaitAll(recvCallBack f, void *data, int refno);
19 Wait for all the previously issued irecvs to complete, and then it calls the callback function "f" with "data" as argument.
20
21 To use Irecv library, create a chare array which is inherited from class "receiver". The sender jneed to allocate the "receiverMsg" message, fill in fields and invoke 'generic' method in the remote object; The receiver will specify the matching tags and buffer to get the message. After irecv, calling iwaitAll to wait all the receive functions calls complete. However, the iwaitAll is nonblocking and the callback functions will be called after receive calls complete.
22
23 Here is an example:
24
25 \begin{verbatim}
26      int size = 100;
27      for (int i=0; i<size; i++) buf[i] = data[i];
28      send(buf, size*sizeof(double), neighbor, tag, iter);
29
30      irecv(buf, size*sizeof(double), neighbor, tag, iter);
31
32      iwaitAll(callfunc, this, iter);
33 \end{verbatim}
34
35 and callback function can be declared as:
36
37 \begin{verbatim}
38      void callfunc(void *obj)
39      {
40      }
41 \end{verbatim}