minor updates to reductions
[charm.git] / doc / charm++ / callbacks.tex
1 \label{callbacks}
2
3 Callbacks provide a generic way to store the information required to
4 invoke a communication target, such as a chare's entry method, at a
5 future time. Callbacks are often encountered when writing library
6 code, where they provide a simple way to transfer control back to a
7 client after the library has finished. For example, after finishing a
8 reduction, you may want the results passed to some chare's entry
9 method.  To do this, you would create an object of type
10 \kw{CkCallback} with the chare's \kw{CkChareID} and entry method
11 index, and pass this callback object to the reduction library.
12
13 \section{Creating a CkCallback Object}
14
15 \index{CkCallback}
16
17 There are several different types of \kw{CkCallback} objects; the type
18 of the callback specifies the intended behavior upon invocation of the
19 callback. Callbacks must be invoked with the \charmpp{} message of the
20 type specified when creating the callback. If the callback is being
21 passed into a library which will return its result through the
22 callback, it is the user's responsibility to ensure that the type of
23 the message delivered by the library is the same as that specified in
24 the callback. Messages delivered through a callback are not
25 automatically freed by the Charm RTS. They should be freed or stored
26 for future use by the user.
27
28 Callbacks that target chares require an ``entry method index'', an
29 integer that identifies which entry method will be called.  An entry
30 method index is the \charmpp{} version of a function pointer.  The
31 entry method index can be obtained using the syntax:
32
33 \begin{alltt}
34 \kw{int myIdx}=CkIndex_\uw{ChareName}::\uw{EntryMethod}(\uw{parameters});
35 \end{alltt}
36
37 Here, \uw{ChareName} is the name of the chare (group, or array)
38 containing the desired entry method, \uw{EntryMethod} is the name of
39 that entry method, and \uw{parameters} are the parameters taken by the
40 method.  These parameters are only used to resolve the proper
41 \uw{EntryMethod}; they are otherwise ignored. 
42
43 Under most circumstances, entry methods to be invoked through a
44 CkCallback must take a single message pointer as argument. As such, if
45 the entry method specified in the callback is not overloaded, using
46 NULL in place of parameters will suffice in fully specifying the
47 intended target. If the entry method is overloaded, a message pointer
48 of the appropriate type should be defined and passed in as a parameter
49 when specifying the entry method. The pointer does not need to be
50 initialized as the argument is only used to resolve the target entry
51 method.
52
53 The intended behavior upon a callback's invocation is specified
54 through the choice of constructor used when creating the callback. 
55 Possible constructors are: 
56
57 \begin{enumerate}
58 \item \kw{CkCallback(void (*CkCallbackFn)(void *, void *),void *param)} 
59 When invoked, the callback will pass \uw{param} and the result message
60 to the given C function, which should have a prototype
61 like:
62
63 \begin{alltt}
64 void \uw{myCallbackFn}(void *param,void *message)
65 \end{alltt}
66
67 This function will be called on the processor where the callback was created,
68 so \uw{param} is allowed to point to heap-allocated data.  Of course, you
69 are required to free any storage referenced by \uw{param}.
70
71 \item \kw{CkCallback(CkCallback::ignore)} When invoked, the callback
72 will do nothing.  This can be useful if a \charmpp{} library requires
73 a callback, but you don't care when it finishes, or will find out some
74 other way.
75
76 \item \kw{CkCallback(CkCallback::ckExit)} When invoked, the callback
77 will call CkExit(), ending the Charm++ program.
78
79 \item \kw{CkCallback(int ep,const CkChareID \&id)} When invoked, the 
80 callback will send its message to the given entry method of the given
81 Chare.  Note that a chare proxy will also work in place of a chare id:
82
83 \begin{alltt}
84         CkCallback myCB(CkIndex_myChare::myEntry(NULL),myChareProxy);
85 \end{alltt}
86
87 \item \kw{CkCallback(int ep,const CkArrayID \&id)} 
88 When invoked,
89 the callback will broadcast its message to the given entry method
90 of the given array.  An array proxy will work in the place of an array id.
91
92 \item \kw{CkCallback(int ep,const CkArrayIndex \&idx,const CkArrayID \&id)}
93 When invoked,
94 the callback will send its message to the given entry method
95 of the given array element. 
96
97 \item \kw{CkCallback(int ep,const CkGroupID \&id)} 
98 When invoked,
99 the callback will broadcast its message to the given entry method
100 of the given group.
101
102 \item \kw{CkCallback(int ep,int onPE,const CkGroupID \&id)}
103 When invoked, the callback will send its message to the given entry
104 method of the given group member.
105
106 \end{enumerate}
107
108 One final type of callback, \kw{CkCallbackResumeThread()}, can only be
109 used from within threaded entry methods.  This callback type is
110 discussed in section \ref{sec:ckcallbackresumethread}.
111
112 \section{CkCallback Invocation}
113
114 \label{libraryInterface}
115
116 A properly initialized \kw{CkCallback} object stores a global
117 destination identifier, and as such can be freely copied, marshalled,
118 and sent in messages. Invocation of a CkCallback is done by calling
119 the function \kw{send} on the callback with the result message as an
120 argument. As an example, a library which accepts a CkCallback object
121 from the user and then invokes it to return a result may have the
122 following interface:
123
124 \begin{alltt}
125 //Main library entry point, called by asynchronous users:
126 void myLibrary(...library parameters...,const CkCallback \&cb) 
127 \{
128   ..start some parallel computation, store cb to be passed to myLibraryDone later...
129 \}
130
131 //Internal library routine, called when computation is done
132 void myLibraryDone(...parameters...,const CkCallback \&cb)
133 \{
134   ...prepare a return message...
135   cb.send(msg);
136 \}
137 \end{alltt}
138
139 A \kw{CkCallback} will accept any message type, or even NULL.  The
140 message is immediately sent to the user's client function or entry
141 point.  A library which returns its result through a callback should
142 have a clearly documented return message type. The type of the message
143 returned by the library must be the same as the type accepted by the
144 entry method specified in the callback. 
145
146 As an alternative to ``send'', the callback can be used in a {\em
147   contribute} collective operation. This will internally invoke the
148 ``send'' method on the callback when the contribute operation has
149 finished.
150
151 For examples of how to use the various callback types, please
152 see \testreffile{megatest/callback.C}
153
154 \section{Synchronous Execution with CkCallbackResumeThread}
155
156 \label{sec:ckcallbackresumethread}
157
158 Threaded entry methods can be suspended and resumed through the {\em
159   CkCallbackResumeThread} class. {\em CkCallbackResumeThread} is
160 derived from {\em CkCallback} and has specific functionality for
161 threads.  This class automatically suspends the thread when the
162 destructor of the callback is called.  A suspended threaded client
163 will resume when the ``send'' method is invoked on the associated
164 callback.  It can be used in situations when the return value is not
165 needed, and only the synchronization is important. For example:
166
167 \begin{alltt}
168 // Call the "doWork" method and wait until it has completed
169 void mainControlFlow() \{
170   ...perform some work...
171   // call a library
172   doWork(...,CkCallbackResumeThread());
173   // or send a broadcast to a chare collection
174   myProxy.doWork(...,CkCallbackResumeThread());
175   // callback goes out of scope; the thread is suspended until doWork calls 'send' on the callback
176   
177   ...some more work...
178 \}
179 \end{alltt}
180
181 Alternatively, if doWork returns a value of interest, this can be retrieved by
182 passing a pointer to {\em CkCallbackResumeThread}. This pointer will be modified
183 by {\em CkCallbackResumeThread} to point to the incoming message. Notice that
184 the input pointer has to be cast to {\em (void*\&)}:
185
186 \begin{alltt}
187 // Call the "doWork" method and wait until it has completed
188 void mainControlFlow() \{
189   ...perform some work...
190   MyMessage *mymsg;
191   myProxy.doWork(...,CkCallbackResumeThread((void*\&)mymsg));
192   // The thread is suspended until doWork calls send on the callback
193
194   ...some more work using "mymsg"...
195 \}
196 \end{alltt}
197
198 Notice that the instance of {\em CkCallbackResumeThread} is constructed
199 as an anonymous parameter to the ``doWork'' call. This insures that the callback
200 is destroyed as soon as the function returns, thereby suspending the thread.
201
202 It is also possible to allocate a {\em CkCallbackResumeThread} on the heap or on
203 the stack. We suggest that programmers avoid such usage, and favor the anonymous instance construction
204 shown above. For completeness, we still present the code for heap and stack
205 allocation of CkCallbackResumeThread callbacks below.
206
207 For heap allocation, the user must explicitly ``delete'' the callback in order to
208 suspend the thread.
209
210 \begin{alltt}
211 // Call the "doWork" method and wait until it has completed
212 void mainControlFlow() \{
213   ...perform some work...
214   CkCallbackResumeThread cb = new CkCallbackResumeThread();
215   myProxy.doWork(...,cb);
216   ...do not suspend yet, continue some more work...
217   delete cb;
218   // The thread suspends now
219
220   ...some more work after the thread resumes...
221 \}
222 \end{alltt}
223
224 For a callback that is allocated on the stack, its destructor will be called only
225 when the callback variable goes out of scope. In this
226 situation, the function ``thread\_delay'' can be invoked on the callback to
227 force the thread to suspend. This also works for heap allocated callbacks.
228
229 \begin{alltt}
230 // Call the "doWork" method and wait until it has completed
231 void mainControlFlow() \{
232   ...perform some work...
233   CkCallbackResumeThread cb;
234   myProxy.doWork(...,cb);
235   ...do not suspend yet, continue some more work...
236   cb.thread\_delay();
237   // The thread suspends now
238
239   ...some more work after the thread is resumed...
240 \}
241 \end{alltt}
242
243 In all cases a {\em CkCallbackResumeThread} can be used to suspend a thread
244 only once.
245
246 {\em Deprecated usage}: in the past, ``thread\_delay'' was used to retrieve the
247 incoming message from the callback. While that is still allowed for backward
248 compatibility, its usage is deprecated. The old usage is subject to memory
249 leaks and dangling pointers.
250