doc: more content hierarchy fixing
[charm.git] / doc / charm++ / groups.tex
1 \section{Group Objects}
2 \label{sec:group}
3
4 So far, we have discussed chares separately from the underlying hardware resources 
5 to which they are mapped. However, while writing lower-level libraries it is sometimes
6 useful to be able to refer to the PE on which a chare's entry method is being executed.
7 The \kw{group} \footnote{Originally called {\em Branch Office Chare} or 
8 {\em Branched Chare}}construct provides this facility by creating a 
9 %A \kw{group}
10 % \index{group}is a 
11 collection of chares, such that 
12 there exists \index{chare}a single chare (or {\sl branch} of the group) on each
13 PE.   Each branch has its own data members.  Groups have
14 a definition syntax similar to normal chares,
15 and they have to inherit from the system-defined class \kw{CBase}\_\uw{ClassName}, 
16 where \uw{ClassName} is the name of group's \CC{} class
17 \footnote{Older, deprecated syntax allows groups to inherit directly from the
18 system-defined class \kw{Group}}.
19
20 \subsection{Group Definition}
21
22 In the interface ({\tt .ci}) file, we declare
23
24 \begin{alltt}
25 group Foo \{
26   // Interface specifications as for normal chares
27
28   // For instance, the constructor ...
29   entry Foo(\uw{parameters1});
30
31   // ... and an entry method
32   entry void someEntryMethod(\uw{parameters2});
33 \};
34 \end{alltt}
35
36 The definition of the {\tt Foo} class is given in the \texttt{.h} file, as follows:
37
38 \begin{alltt}
39 class Foo : public CBase\_Foo \{
40   // Data and member functions as in C++
41   // Entry functions as for normal chares
42
43   public:
44     Foo(\uw{parameters1});
45     void someEntryMethod(\uw{parameters2});
46 \};
47 \end{alltt}
48
49 \subsection{Group Creation}
50
51 Groups are created in a manner similar to chares and chare arrays, i.e. 
52 through \kw{ckNew}. Given the declarations and definitions of group {\tt Foo}
53 from above, we can create a group in the following manner:
54
55 \begin{alltt}
56 CkGroupID fooGroupID = CProxy_Foo::ckNew(\uw{parameters1});
57 \end{alltt}
58
59
60 In the above, \kw{ckNew} returns an object of type \kw{CkGroupID}, which is
61 the globally unique identifier of the corresponding instance of the group.
62 This identifier is common to all of the group's branches and
63 can be obtained in the group's methods from the variable \kw{thisgroup}, which is a public data
64 member of the \kw{Group} superclass.
65
66 A group can also be identified through its proxy, which can be obtained in one of three ways:
67 (a) as the inherited {\tt thisProxy} data member of the class; (b) from a call to \kw{ckNew} 
68 as shown below:
69
70 \begin{alltt}
71 CkGroupID fooGroupID = CProxy_Foo::ckNew(\uw{parameters1});
72 \end{alltt}
73
74 or (c) by using a group identifier to create a proxy, as shown below:
75
76 \begin{alltt}
77   // We have `fooGroupID' from the above `ckNew' invocation
78
79   // Obtain a proxy to the group from its group ID
80   CProxy_Foo anotherFooProxy = CProxy_Foo(fooGroupID);
81 \end{alltt}
82
83 It is possible to specify the dependence of group creations using
84 \uw{CkEntryOptions}. For example, in the following code, the creation of group
85 {\tt GroupB} on each PE depends on the creation of {\tt GroupA} on that PE.
86
87 \begin{alltt}
88 // Create GroupA
89 CkGroupID groupAID = CProxy_GroupA::ckNew(\uw{parameters1});
90
91 // Create GroupB. However, for each PE, do this only 
92 // after GroupA has been created on it
93
94 // Specify the dependency through a `CkEntryOptions' object
95 CkEntryOptions opts;
96 opts.setGroupDepID(groupAId);
97
98 // The last argument to `ckNew' is the `CkEntryOptions' object from above
99 CkGroupID groupBID = CProxy_GroupB::ckNew(\uw{parameters2}, opts);
100 \end{alltt}
101
102 %For groups, \kw{thishandle} is the
103 %handle of the particular branch in which the function is executing: it is a
104 %normal chare handle.
105
106 %Groups can be used to implement data-parallel operations easily.  In addition
107 %to sending messages to a particular branch of a group, one can broadcast
108 %messages to all branches of a group.  
109 Note that there can be several instances of each group type.
110 In such a case, each instance has a unique group identifier, and its own set
111 of branches.
112
113 \subsection{Method Invocation on Groups}
114
115 An asynchronous entry method can be invoked on a particular branch of a
116 group through a proxy of that group. If we have a group with a proxy
117 {\tt fooProxy} and we wish to invoke entry method {\tt someEntryMethod} on
118 that branch of the group which resides on PE {\tt somePE}, we would accomplish
119 this with the following syntax:
120
121 \begin{alltt}
122  fooProxy[somePE].someEntryMethod(\uw{parameters});
123 \end{alltt}
124
125 %This sends the given parameters to the \index{branch}branch of
126 %the group referred to by \uw{groupProxy} which is on processor number
127 %\uw{Processor} at the entry method \uw{EntryMethod}, which must be a valid
128 %entry method of that group type. 
129 This call is asynchronous and non-blocking; it returns immediately after sending the message.
130 A message may be broadcast \index{broadcast} to all branches of a group
131 (i.e., to all PEs) using the notation :
132
133 \begin{alltt}
134  fooProxy.anotherEntryMethod(\uw{parameters});
135 \end{alltt}
136
137 This invokes entry method \uw{anotherEntryMethod} with the given \uw{parameters} on 
138 all branches of the group. This call is asynchronous and non-blocking; it returns immediately
139 after sending the message.
140
141 Recall that each PE hosts a branch of every instantiated group. 
142 Sequential objects, chares and other groups can gain access to this {\em PE-local}
143 branch using \kw{ckLocalBranch()}:
144
145 \begin{alltt}
146 GroupType *g=fooProxy.ckLocalBranch();
147 \end{alltt}
148
149 This call returns a regular \CC\ pointer to the actual object (not a proxy)
150 referred to by the proxy \uw{groupProxy}.  Once a proxy to the
151 local branch of a group is obtained, that branch can be accessed as a regular
152 \CC\ object.  Its public methods can return values, and its public data is 
153 readily accessible.
154
155 Thus a dynamically created \index{chare}chare can invoke a public method of a
156 group without knowining the PE on which it actually resides. 
157 %the method
158 %executes in the local \index{branch}branch of the group.
159
160 Let us end with an example use-case for groups.
161 %One very nice use of Groups is to reduce the number of messages sent between
162 %processors by collecting the data from all the chares on a single processor
163 Suppose that we have a task-parallel program in which we dynamically spawn
164 new chares. Furthermore, assume that each one of these chares has some data
165 to send to the mainchare.  Instead of creating a separate message for each 
166 chare's data, we create a group. When a particular chare
167 finishes its work, it reports its findings to the local branch of the group.
168 When all the chares on a PE have finished their work, the local branch
169 can send single a message to the main chare.  This reduces the number of messages
170 sent to the mainchare from the number of chares created, to the number of processors. 
171