3.9 Group Objects

A group¹⁴ is a collection of chares where there exists one chare (or branch) on each processor. Each branch has its own data members. Groups have a definition syntax similar to normal chares, and they have to inherit from the system defined class CBase_ClassName. As for chares, an older systax allow them to inherit directly from the system-defined class Group.

In the interface file, we declare

 group GroupType {
   // Interface specifications as for normal chares
 };

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

 class GroupType : public CBase_GroupType {
  // Data and member functions as in C++
  // Entry functions as for normal chares
 };

A group is identified by a globally unique group identifier, whose type is CkGroupID. This identifier is common to all of the group's branches and can be obtained from the variable thisgroup, which is a public local variable of the Group superclass. For groups, thishandle is the handle of the particular branch in which the function is executing: it is a normal chare handle.

Groups can be used to implement data-parallel operations easily. In addition to sending messages to a particular branch of a group, one can broadcast messages to all branches of a group. There can be many instances corresponding to a group type. Each instance has a different group handle, and its own set of branches.

3.9.1 Group Creation

Given a .ci file as follows:

group G {
  entry G(parameters1);
  entry void someEntry(parameters2);
};

and the following .h file:

class G : public CBase_G {
  public:
    G(parameters1);
    void someEntry(parameters2);
};

we can create a group in a manner similar to a regular chare.

CProxy_G groupProxy = CProxy_G::ckNew(parameters1);
or
CkGroupID groupId = CProxy_G::ckNew(parameters1);
CProxy_G groupProxy(groupId);

3.9.2 Method Invocation on Groups

Before sending a message to a group via an entry method, we need to get a proxy of that group.

A message may be sent to a particular branch of group using the notation:

 groupProxy[Processor].EntryMethod(parameters);

This sends the given parameters to the branch of the group referred to by groupProxy which is on processor number Processor at the entry method EntryMethod, which must be a valid entry method of that group type. This call is asynchronous and non-blocking; it returns immediately after sending the message.

A message may be broadcast to all branches of a group (i.e., to all processors) using the notation :

 groupProxy.EntryMethod(parameters);

This sends the given parameters to all branches of the group at the entry method EntryMethod, which must be a valid entry method of that group type. This call is asynchronous and non-blocking; it returns immediately after sending the message.

Sequential objects, chares and other groups can gain access to the local (i.e., on their processor) group object using:

GroupType *g=groupProxy.ckLocalBranch();

This call returns a regular C++ pointer to the actual object (not a proxy) referred to by the proxy groupProxy. Once a proxy to the local branch of a group is obtained, that branch can be accessed as a regular C++ object. Its public methods can return values, and its public data is readily accessible.

Thus a dynamically created chare can call a public method of a group without needing to know which processor it actually resides: the method executes in the local branch of the group.

One very nice use of Groups is to reduce the number of messages sent between processors by collecting the data from all the chares on a single processor before sending that data to the mainchare. To do this, create basic chares to break up the work of a problem. Also, create a group. When a particular chare finishes its work, it reports its findings to the local branch of the group. When all the chares on one processor are complete, the local branch of the group can then report to the main chare. This reduces the number of messages sent to main from the number of chares created to the number of processors.