3.5 Chare Objects

Chares are concurrent objects with methods that can be invoked remotely. These methods are known as entry methods, and must be specified in the interface (.ci) file:

chare ChareType
{
    entry   ChareType             (parameters1);
    entry   void EntryMethodName2 (parameters2);
};

A corresponding chare definition in the .h file would have the form:

   class ChareType : public CBase_ChareType {
        // Data and member functions as in C++
        // One or more entry methods definitions of the form:
   public:
      ChareType(parameters2)
         { // C++ code block  }
      void EntryMethodName2(parameters2)
         { // C++ code block  }
   };

Chares are concurrent objects encapsulating medium-grained units of work. Chares can be dynamically created on any processor; there may be thousands of chares on a processor. The location of a chare is usually determined by the dynamic load balancing strategy; however, once a chare commences execution on a processor, it does not migrate to other processors¹¹. Chares do not have a default ``thread of control'': the entry methods in a chare execute in a message driven fashion upon the arrival of a message¹².

The entry method definition specifies a function that is executed without interruption when a message is received and scheduled for processing. Only one message per chare is processed at a time. Entry methods are defined exactly as normal C++ function members, except that they must have the return value void (except for the constructor entry method which may not have a return value, and for a synchronous entry method, which is invoked by a threaded method in a remote chare) and they must have exactly one argument which is a pointer to a message.

Each chare instance is identified by a handle which is essentially a global pointer, and is unique across all processors. The handle of a chare has type CkChareID. The variable thishandle holds the handle of the chare whose entry function or public function is currently executing. thishandle is a public instance variable of the chare object which is inherited from the system-defined superclass CBase_ClassType. Following the older syntax, chares are also allowed to inherit directly for the superclass Chare instead of CBase_ClassType, although this form is not suggested. thishandle can be used to set fields in a message. This mechanism allows chares to send their handles to other chares.

3.5.1 Chare Creation

First, a chare needs to be declared, both in .ci file and in .h file, as stated earlier. The following is an example of declaration for a chare of user-defined type C, where M1 and M2 are user-defined message types, and someEntry is an entry method.

In the mod.ci file we have:

module mod {
  chare C {
    entry C(parameters);
    entry void someEntry(parameters);
  };
}

and in the mod.h file:

#include "mod.decl.h"
class C : public CBase_C {
  public:
    C(parameters);
    void someEntry(parameters);
};

Now one can use the class CProxy_chareType to create a new instance of a chare. Here chareType gets replaced with whatever chare type we want. For the above example, proxies would be of type CProxy_C. A number of chare creation calls exist as static or instance methods of class CProxy_chareType:

   CProxy_chareType::ckNew(parameters, CkChareID *vHdl, int destPE);

Each item above is optional, and:

• chareType is the name of the type of chare to be created.

• parameters must correspond to the parameters for the constructor entry method. If the constructor takes void, pass nothing here.

• vHdl is a pointer to a chare handle of type CkChareID, which is filled by the ckNew method. This optional argument can be used if the user desires to have a virtual handle to the instance of the chare that will be created. This handle is useful for sending messages to the chare, even though it has not yet been created on any processor. Messages sent to this virtual handle are either queued up to be sent to the chare after it has been created, or simply redirected if the chare has already been created. For performance reasons, therefore, virtual handles should be used only when absolutely necessary. Virtual handles are otherwise like normal handles, and may be sent to other processors in messages.

• destPE: when a chare is to be created at a specific processor, the destPE is used to specify that processor. Note that, in general, for good load balancing, the user should let CHARM++ determine the processor on which to create a chare. Under unusual circumstances, however, the user may want to choose the destination processor. If a process replicated on every processor is desired, then a chare group should be used. If no particular processor is required, the parameter can be omitted, or CK_PE_ANY.

The chare creation method deposits the seed for a chare in a pool of seeds and returns immediately. The chare will be created later on some processor, as determined by the dynamic load balancing strategy. When a chare is created, it is initialized by calling its constructor entry method with the message parameter specified to the chare creation method. The method operator does not return any value but fills in the virtual handle to the newly created chare if specified.

The following are some examples on how to use the chare creation method to create chares.

1. This will create a new chare of type C on any processor:
      CProxy_C chareProxy = CProxy_C::ckNew(parameters);
   

2. This will create a new chare of type C on processor destPE:
      CProxy_C chareProxy = CProxy_C::ckNew(parameters, destPE);
   

3. The following first creates a CkChareID cid, then creates a new chare of type C on processor destPE:
      CkChareID cid;
      CProxy_C::ckNew(parameters, &cid, destPE);
      CProxy_C chareProxy(cid);
   

3.5.2 Method Invocation on Chares

A message may be sent to a chare using the notation:

chareProxy.EntryMethod(parameters)

This invokes the entry method EntryMethod on the chare referred to by the proxy chareProxy. This call is asynchronous and non-blocking; it returns immediately after sending the message.

3.5.3 Local Access

You can get direct access to a local chare using the proxy's ckLocal method, which returns an ordinary C++ pointer to the chare if it exists on the local processor; and NULL if the chare does not exist or is on another processor.

C *c=chareProxy.ckLocal();
if (c==NULL) //...is remote- send message
else //...is local- directly use members and methods of c