doc: more content hierarchy fixing
[charm.git] / doc / charm++ / nodegroups.tex
1 \section{NodeGroup Objects}
2
3 The {\em node group} construct \index{node groups} \index{nodegroup} \index{Nodegroup} is 
4 similar to the group construct discussed above. 
5 That is, a node group is a collection of chares that can be addressed via globally unique
6 identifier. 
7 %already discussed in that node groups are
8 %collections of chares as well.  
9 However, a node group has one chare per {\em process}, or {\em logical node}, rather than one chare per PE.
10 %rather than one chare per processor.  
11 Therefore, each logical node hosts a single branch of the
12 node group.  When an entry method of a
13 node group is executed on one of its branches, it executes on {\em some} PE within the node.
14
15 \subsection{NodeGroup Declaration} 
16
17 Node groups are defined in a similar way to groups.  \footnote{As with groups,
18 older syntax allows node groups to inherit from \kw{NodeGroup} instead of a
19 specific, generated ``\uw{CBase\_}'' class.} For example, in the interface file, we declare:
20
21 \begin{alltt}
22  nodegroup NodeGroupType \{
23   // Interface specifications as for normal chares
24  \};
25 \end{alltt}
26
27 In the {\tt .h} file, we define \uw{NodeGroupType} as follows:
28
29 \begin{alltt}
30  class NodeGroupType : public CBase_NodeGroupType \{
31   // Data and member functions as in \CC{}
32   // Entry functions as for normal chares
33  \};
34 \end{alltt}
35
36 Like groups, NodeGroups are identified by a globally unique identifier of type
37 \index{CkGroupID}\kw{CkGroupID}.  Just as with groups, this identifier is
38 common to all branches of the NodeGroup, and can be obtained from the inherited
39 data member \index{thisgroup}\kw{thisgroup}.
40 There can be many instances corresponding to a single NodeGroup
41 type, and each instance has a different identifier, and its own set of
42 branches.
43
44
45 %, and once again, \index{thishandle}
46 %\kw{thishandle} is the handle of the particular branch in which the function is
47 %executing.
48
49
50 \subsection{Method Invocation on NodeGroups}
51
52 As with chares, chare arrays and groups, entry methods are invoked on
53 NodeGroup branches via proxy objects. 
54 An entry method may be invoked on a {\em particular} \index{branch}branch of a
55 \index{nodegroup}nodegroup by specifying a {\em logical node number} argument
56 to the square bracket operator of the proxy object. A broadcast is expressed
57 by omitting the square bracket notation. For completeness, example syntax for these
58 two cases is shown below:
59
60 \begin{alltt}
61  // Invoke `someEntryMethod' on the i-th logical node of
62  // a NodeGroup whose proxy is `myNodeGroupProxy':
63  myNodeGroupProxy[i].someEntryMethod(\uw{parameters});
64
65  // Invoke `someEntryMethod' on all logical nodes of
66  // a NodeGroup whose proxy is `myNodeGroupProxy':
67  myNodeGroupProxy.someEntryMethod(\uw{parameters});
68 \end{alltt}
69
70 %In the absence of such a parameter, the call is treated as a broadcast
71 %to all branches of the NodeGroup of the a \index{nodegroup}nodegroup, i.e. executed by all nodes. 
72 It is worth restating that when an entry method is
73 invoked on a particular \index{branch}branch of a \index{nodegroup}nodegroup,
74 it may be executed by {\em any} PE in that logical node. Thus two invocations of
75 a single entry method on a particular \index{branch}branch of a
76 \index{nodegroup}NodeGroup may be executed {\em concurrently} by two
77 different PEs in the logical node. If this may cause data races in your
78 program, please consult \S~\ref{sec:nodegroups/exclusive} (below).
79
80 %If that method contains code that should be
81 %executed by only one processor at a time, the method should be flagged
82 %\index{exclusive}\kw{exclusive} in the interface file. 
83
84 \subsection{NodeGroups and \kw{exclusive} Entry Methods}
85 \ref{sec:nodegroups/exclusive}
86
87 Node groups may have \index{exclusive}\kw{exclusive} entry methods.  The execution of an \kw{exclusive}
88 entry method invocation is mutually exclusive with those of all other \kw{exclusive} entry methods invocations.
89 That is, an \kw{exclusive}
90 entry method invocation is not executed on a logical node as long as another \kw{exclusive} entry 
91 method is executing on it.
92 More explicitly, if a method \uw{M} of a
93 nodegroup \uw{NG} is marked exclusive, it means that while an instance of that method is being
94 executed by a PE within a logical node, no other PE within that
95 logical node will execute any other {\em exclusive} methods.
96 %of that
97 %\index{nodegroup}nodegroup \index{branch}branch.  
98 However, PEs in the logical node may still 
99 execute {\em non-exclusive} entry method invocations.
100 %on that l
101 %\index{branch}branch, however.
102 %of that node group are running on the same node.  
103 An entry method can be marked exclusive by tagging it with the \kw{exclusive} attribute,
104 as explained in \S~\ref{attributes}.
105
106
107 \subsection{Accessing the Local Branch of a NodeGroup}
108
109 The local \index{branch}branch of a \kw{NodeGroup} \uw{NG}, and hence its
110 member fields and methods, can be accessed through the method \kw{NG*
111 CProxy\_NG::ckLocalBranch()} of its proxy. Note that accessing data members of
112 a NodeGroup branch in this manner is {\em not} thread-safe by default, although
113 you may implement your own mutual exclusion schemes to ensure safety.
114 %accesses are {\em not} thread-safe by default.  Concurrent invocation of a
115 %method on a \index{nodegroup}nodegroup by different processors within a node
116 %may result in unpredictable runtime behavior.  
117 One way to ensure safety is to use node-level locks, which are described in the
118 Converse manual.
119
120 %For certain applications, node groups can be used in the place of regular
121 %groups to mitigate messaging overhead when sharing of address spaces between 
122 %PEs is possible.
123 %For example, consider a parallel program that does one calculation that can be
124 %decomposed into several mutually exclusive subcalculations.  The program
125 %distributes the work amongst all of the processors, the subresults are all
126 %stored in the local branch of a group, and when the local branch has recieved
127 %all of its results, it relays everything to one particular processor where the
128 %subresults are put together into the final result.  When normal groups are
129 %used, the number of messages sent is $O$(\# of processors).  However, if node
130 %groups are used, a number of message sends will be replaced by local memory
131 %accesses if there is more than one processor per node.  Instead, the number of
132 %messages sent is $O$(\# of nodes).
133 NodeGroups can be used in a similar way to groups so as to implement lower-level
134 optimizations such as data sharing and message reduction.
135
136