\subsection{Nodegroup Objects}

{\it Node groups}\experimental{} \index{node groups} \index{nodegroup} 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, \kw{Group}, node groups inherit
from \kw{Nodegroup}.  For example, in the interface file, we declare:

\begin{alltt}
 nodegroup NodegroupType \{
  // Interface specifications as for normal chares
 \};
\end{alltt}

In the {\tt .h} file, we define \uw{NodeGroupType} as follows:

\begin{alltt}
 class NodeGroupType : public Nodegroup [,other superclasses ] \{
  // Data and member functions as in \CC{}
  // Entry functions as for normal chares
 \};
\end{alltt}

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

Node groups may possess \index{exclusive}\kw{exclusive} entry methods.  These
are entry methods that will not run while other 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 \ref{attributes}.

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 $O$(\# 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 $O$(\# 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.


\subsubsection{Method Invocation on Nodegroups}

Methods can be invoked either on a particular \index{branch}branch of a
\index{nodegroup}nodegroup by specifying a {\em node number} as a method
parameter. In the absence of such a parameter, the call is treated as broadcast
on a \index{nodegroup}nodegroup, i.e. executed by all nodes. When a method is
invoked on a particular \index{branch}branch of a \index{nodegroup}nodegroup,
it may be executed by {\em ANY} processor in that node. Thus two invocations of
a specific method on a particular \index{branch}branch of a
\index{nodegroup}nodegroup may be carried out {\em 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
\index{exclusive}\kw{exclusive} in the interface file. If a method \uw{M} of a
nodegroup \uw{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 {\em exclusive} method of that
\index{nodegroup}nodegroup \index{branch}branch.  Other processors are free to
execute other {\em non-exclusive} methods of that nodegroup
\index{branch}branch, however.

The local \index{branch}branch of a \kw{nodegroup} can be accessed using
\kw{CkLocalNodeBranch()} function. Thus data members could be accessed/modified
or methods could be invoked on a \index{branch}branch of a \kw{nodegroup} using
this function. Note that such accesses are {\em not} thread-safe by default.
Concurrent invocation of a method on a \index{nodegroup}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.)

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