doc/libraries/irecv.tex

   1 The \irecv{} library provides asynchronous communication mode for
   2 use in chare arrays in the message-passing style. The control flow of a
   3 message-passing program is broken into two parts (to provide the efficient
   4 "split phase" structure): nonblocking communication operations and
   5 iwait with callback functions as continuations. It thus provides a style
   6 that MPI programmers may find intuitive. This library aids in porting
   7 existing MPI codes to \charmpp{} without using expensive context-switching
   8 of threads. In this approach, a chare array element is used to
   9 represent a virtual processor.
  10
  11 There are three functions in \irecv{} library.
  12
  13 \function{void send(buf, size, dest, tag, refno)}
  14 \args{void *buf;}
  15 \args{int size, dest, tag, refno;}
  16 \desc{
  17 Sends message which is pointed by \uw{buf} to another array element whose
  18 index is specified by \uw{dest} with \uw{tag} and \uw{refno}.
  19 \uw{buf} is a message buffer containing the data to be sent; \uw{size} is
  20 the total size of the message in bytes.
  21 Like in {\tt MPI\_send}, the \uw{tag} is used for matching message on
  22 destination array element. The integer \uw{refno} is a reference number,
  23 usually the iteration number.
  24 }
  25
  26 \function{void irecv(buf, size, source, tag, refno)}
  27 \args{void *buf;}
  28 \args{int size, source, tag, refno;}
  29 \desc{
  30 This function registers \uw{tag} and \uw{buf} with the library.
  31 When the desired message arrives, it copies the matching message
  32 into the location given by the \uw{buf}.
  33 }
  34
  35 \function{void iwaitAll(f, data, refno)}
  36 \args{recvCallBack f;}
  37 \args{void *data;}
  38 \args{int refno;}
  39 \desc{
  40 This function registers a callback function \uw{f} with the library. This
  41 function is invoked with \uw{data} as its argument when all the previously issued \kw{irecv}s with \uw{refno} as reference number complete.
  42 }
  43
  44 To use the \irecv{} library, first one has to create a chare array, which
  45 is inherited from class \kw{receiver}. The sender entry methor of the
  46 chare array element prepares the message buffer and calls \kw{send} function
  47 to send message to another array element; The receiver specifies the
  48 matching tags and buffer to get the message. After \kw{irecv}, the receiver
  49 needs to call \kw{iwaitAll} function to wait for all the \kw{irecv} function
  50 calls to complete. However, \kw{iwaitAll} is a nonblocking function.
  51 The callback function will be called after the relevant \kw{irecv} calls
  52 complete.
  53
  54 Here is an example:
  55
  56 \begin{alltt}
  57      int size = 100;
  58      for (int i=0; i<size; i++) buf[i] = data[i];
  59      send(buf, size*sizeof(double), neighbor, tag, iter);
  60      irecv(buf, size*sizeof(double), neighbor, tag, iter);
  61      iwaitAll(callfunc, this, iter);
  62 \end{alltt}
  63
  64 and callback function can be declared as:
  65
  66 \begin{alltt}
  67      void callfunc(void *obj)
  68      \{
  69        ... do something with obj
  70      \}
  71 \end{alltt}