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