3.10 NodeGroup Objects

Node groups are very similar to the group objects already discussed in that node groups are collections of chares as well. Node groups, however, have one chare per node rather than one chare per processor. So, each node contains a branch of the node group, each containing one set of data members. When an entry method of a node group is executed, it runs on only one processor within each node.

Node groups have a definition syntax that is very similar to groups. Rather than inheriting from the system defined class, Group, node groups inherit from NodeGroup. For example, in the interface file, we declare:

 nodegroup NodeGroupType {
  // Interface specifications as for normal chares
 };

In the .h file, we define NodeGroupType as follows:

 class NodeGroupType : public NodeGroup [,other superclasses ] {
  // Data and member functions as in  C++
  // Entry functions as for normal chares
 };

Like groups, nodegroups are identified by a globally unique identifier of type CkGroupID. Just like with groups, this identifier is common to all branches of the nodegroup and can be obtained from the variable thisgroup, and once again, thishandle is the handle of the particular branch in which the function is executing.

Node groups may possess exclusive entry methods. These are entry methods that will not run while other exclusive entry methods of that node group are running on the same node. For instructions for making an entry method exclusive, refer to section 3.2.1.

For certain applications, node groups can be used in the place of regular groups to cut down on messaging overhead when shared memory access is possible. For example, consider a parallel program that does one calculation that can be decomposed into several mutually exclusive subcalculations. The program distributes the work amongst all of the processors, the subresults are all stored in the local branch of a group, and when the local branch has recieved all of its results, it relays everything to one particular processor where the subresults are put together into the final result. When normal groups are used, the number of messages sent is (# of processors). However, if node groups are used, a number of message sends will be replaced by local memory accesses if there is more than one processor per node. Instead, the number of messages sent is (# of nodes).

Just like groups, there can be many instances corresponding to a single node group type, and each instance has a different group handle, and its own set of branches.

3.10.1 Method Invocation on NodeGroups

Methods can be invoked either on a particular branch of a nodegroup by specifying a node number as a method parameter. In the absence of such a parameter, the call is treated as broadcast on a nodegroup, i.e. executed by all nodes. When a method is invoked on a particular branch of a nodegroup, it may be executed by ANY processor in that node. Thus two invocations of a specific method on a particular branch of a nodegroup may be carried out simultaneously by two different processors of the node. If that method contains code that should be executed by only one processor at a time, the method should be flagged exclusive in the interface file. If a method M of a nodegroup NG is marked exclusive, it means that while that method is being executed by any processor within a node, no other processor within the same node may execute any other exclusive method of that nodegroup branch. Other processors are free to execute other non-exclusive methods of that nodegroup branch, however.

The local branch of a nodegroup can be accessed using CkLocalNodeBranch() function. Thus data members could be accessed/modified or methods could be invoked on a branch of a nodegroup using this function. Note that such accesses are not thread-safe by default. Concurrent invocation of a method on a nodegroup by different processors within a node may result in unpredictable runtime behavior. One way to avoid this is to use node-level locks (described in Converse manual.)

CkLocalNodeBranch returns a generic (void *) pointer, similar to CkLocalBranch. Also, the static method ckLocalNodeBranch of the proxy class of appropriate nodegroup can be called to get the correct type of pointer.