Callbacks

Callbacks are used by the Charm++ Runtime System, frameworks, libraries, and so on to notify application code that some kind of event has occurred. For example, reductions use callbacks to notify the application code when the reduction has completed. The basic idea is that the application code can specify what action to take when the callback is triggered (i.e. the specific event occurs). The action taken can be a variety of things including calling function or having the application exit.

"Do Nothing" Callback

To create a callback object that does nothing, simply create it as follows: CkCallback cb(CkCallback::ignore). When triggered, the callback does nothing.

CkExit Callback

To create a callback object that will cause CkExit() to be called when the callback is triggered, simply create it as follows: CkCallback cb(CkCallback::ckExit).

C Function Callback

To create a callback object that will cause a C function to be executed, create it as follows: CkCallback cb(CkCallbackFunc cFunc, void* param). Here, the type of the CkCallbackFunc is void myCFunction(void* param, void* msg). The param pointer used when the callback object was created will be passed to the C function as the param parameter. The msg parameter will point to the message created by whatever entity (e.g. a library) triggers the callback.

Entry Method Callback

To create a callback object that will cause an entry method to be called on a chare object, create it as follows: CkCallback cb(int entryMethodIndex, CkChareID &id). Each entry method for a chare class has an associated entry method index. The entry method index is used here to identify which entry method on the chare object (specified by the id parameter) should be executed.

To get the entry method index for any given entry method, do the following: int entryMethodIndex = CkIndex_MyChareClass::myEntryMethod(...parameters for entry method...) where MyChareClass is the name of the chare class and myEntryMethod is the name of the entry method. The parameters passed to this function are not actually used when retrieving the entry method index; they are only used to identify which entry method is actually being called in cases where multiple entry methods share the same name (i.e. are overloaded). For example, to get the entry method index for an entry method with the following prototype: void MyChareClass::myEntryMethod(int* x) one could use int myEntryMethodIndex = CkIndex_MyChareClass::myEntryMethod((int*)NULL). (Remember, this is not actually calling myEntryMethod so it is alright for the pointer to have a NULL value. Only the type of the parameter is important so overloaded functions can be differentiated.)

Example Usage

For an example of how a callback would be created an used, please see the Reductions Section.

More Information

For more information on callbacks, please see Section 3.15: Callbacks of the The Charm++ Programming Language Manual