manual: added a section on MeshStreamer
[charm.git] / doc / charm++ / alltoall.tex
1 \subsection{All-to-All}
2
3 All-to-All is a frequently encountered pattern of communication in
4 parallel programs where each processing element sends a message to
5 every other processing element. Variations on this pattern are also
6 common. A processing element may want to send multiple messages to the
7 same destination over time, for example, and not every pair of
8 processors may need to communicate. In Charm++ we classify these
9 scenarios under a single API with the aim of improving any type of
10 Many-to-Many communication pattern.
11
12 Note that we are currently extending support for All-to-All
13 communication in Charm++ and so the API may change in the
14 future. 
15
16 \subsubsection{MeshStreamer}
17
18 MeshStreamer optimizes the case of All-to-All and Many-to-Many
19 communication on regular 2D and 3D machine topologies. Messages sent
20 using MeshStreamer are routed along the dimensions of the specified
21 topology and aggregated at intermediate destinations. When using it,
22 the first step is to create a MeshStreamer group. 
23
24 \begin{alltt}
25 MeshStreamer(int totalBufferCapacity, int numRows, 
26              int numColumns, int numPlanes, 
27              const CProxy_MeshStreamerClient<dtype> &clientProxy,
28              int yieldFlag = 0, int progressPeriodInMs = -1);
29 \end{alltt}
30
31 The constructor takes as input a reference to a MeshStreamerClient
32 proxy. The user should pass in the proxy for the group which will
33 receive the data sent using MeshStreamer. To do so, this group should
34 inherit from the MeshStreamerClient group. Note that MeshStreamer and
35 MeshStreamerClient are templated. The templated parameter specifies
36 the type of data units which will be communicated. 
37
38 The totalBufferCapacity parameter for the MeshStreamer constructor
39 specifies the buffering limit of the library. When the collective
40 number of items buffered by the local instance of the group reaches
41 the specified limit, the library sends a message along each dimension
42 to the destination for which it has buffered the most messages.
43
44 MeshStreamer employs a virtual topology to route messages. The
45 topology is specified by the user. When a regular mesh partition is
46 avilable for execution, performance will be much better if the
47 dimensions of the virtual topology submitted by the user correspond to
48 the physical dimensions of the machine topology. The Charm++ Topology
49 Manager can be used to produce this information for the user at run
50 time. 
51
52 The insertData function, best used when called on the local instance
53 of the MeshStreamer group, hands over individual units of data for
54 transmission by the library. 
55
56 \begin{alltt}
57 void insertData(dtype &dataItem, const int destinationPe); 
58 \end{alltt}
59
60 To receive items, the user needs to define a process function, which
61 is a pure virtual function of MeshStreamerClient.
62
63 \begin{alltt}
64 virtual void process(dtype &data)=0; 
65 \end{alltt}
66
67 MeshStreamer aggregates items into messages which are sent out when
68 internal buffers fill up or periodic time limits are reached. The
69 message arriving at the destination index of the MeshStreamer group
70 may contain items from various group indices. The receiveCombinedData
71 function loops over the received items and calls the process function
72 for each item. The user may choose to redefine this function to
73 specify an alternate message processing behavior. 
74
75 \begin{alltt}
76 virtual void receiveCombinedData(MeshStreamerMessage<dtype> *msg);
77 \end{alltt}
78