Docs: refer to illinois.edu, not uiuc.edu
[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 \uw{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 callback constructor used when creating the callback. 
55 Possible constructors are: 
56
57 \begin{enumerate}
58 \item \kw{CkCallback(void (*CallbackFn)(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.  Hence, this 
69 constructor should be used only when it is known that the callback target (which by definition here
70 is just a C-like function) will be on the same processor as from where the constructor was called. 
71 Of course, you
72 are required to free any storage referenced by \uw{param}.
73
74 \item \kw{CkCallback(CkCallback::ignore)} - When invoked, the callback
75 will do nothing.  This can be useful if a \charmpp{} library requires
76 a callback, but you don't care when it finishes, or will find out some
77 other way.
78
79 \item \kw{CkCallback(CkCallback::ckExit)} - When invoked, the callback
80 will call CkExit(), ending the Charm++ program.
81
82 \item \kw{CkCallback(int ep, const CkChareID \&id)} - When invoked, the 
83 callback will send its message to the given entry method (specified by the 
84 entry point index - \kw{ep}) of the given
85 Chare (specified by the chare \kw{id}).  Note that a chare proxy will also work in place of a chare id:
86
87 \begin{alltt}
88         CkCallback myCB(CkIndex_myChare::myEntry(NULL), myChareProxy);
89 \end{alltt}
90
91 \item \kw{CkCallback(int ep, const CkArrayID \&id)} - 
92 When invoked,
93 the callback will broadcast its message to the given entry method
94 of the given array.  An array proxy will work in the place of an array id.
95
96 \item \kw{CkCallback(int ep, const CkArrayIndex \&idx, const CkArrayID \&id)} - 
97 When invoked,
98 the callback will send its message to the given entry method
99 of the given array element. 
100
101 \item \kw{CkCallback(int ep, const CkGroupID \&id)} - 
102 When invoked,
103 the callback will broadcast its message to the given entry method
104 of the given group.
105
106 \item \kw{CkCallback(int ep, int onPE, const CkGroupID \&id)} - 
107 When invoked, the callback will send its message to the given entry
108 method of the given group member.
109
110 \end{enumerate}
111
112 One final type of callback, \kw{CkCallbackResumeThread()}, can only be
113 used from within threaded entry methods.  This callback type is
114 discussed in section \ref{sec:ckcallbackresumethread}.
115
116 \section{CkCallback Invocation}
117
118 \label{libraryInterface}
119
120 A properly initialized \kw{CkCallback} object stores a global
121 destination identifier, and as such can be freely copied, marshalled,
122 and sent in messages. Invocation of a CkCallback is done by calling
123 the function \kw{send} on the callback with the result message as an
124 argument. As an example, a library which accepts a CkCallback object
125 from the user and then invokes it to return a result may have the
126 following interface:
127
128 \begin{alltt}
129 //Main library entry point, called by asynchronous users:
130 void myLibrary(...library parameters...,const CkCallback \&cb) 
131 \{
132   ..start some parallel computation, store cb to be passed to myLibraryDone later...
133 \}
134
135 //Internal library routine, called when computation is done
136 void myLibraryDone(...parameters...,const CkCallback \&cb)
137 \{
138   ...prepare a return message...
139   cb.send(msg);
140 \}
141 \end{alltt}
142
143 A \kw{CkCallback} will accept any message type, or even NULL.  The
144 message is immediately sent to the user's client function or entry
145 point.  A library which returns its result through a callback should
146 have a clearly documented return message type. The type of the message
147 returned by the library must be the same as the type accepted by the
148 entry method specified in the callback. 
149
150 As an alternative to ``send'', the callback can be used in a {\em
151   contribute} collective operation. This will internally invoke the
152 ``send'' method on the callback when the contribute operation has
153 finished.
154
155 For examples of how to use the various callback types, please
156 see \testreffile{megatest/callback.C}
157
158 \section{Synchronous Execution with CkCallbackResumeThread}
159
160 \label{sec:ckcallbackresumethread}
161
162 Threaded entry methods can be suspended and resumed through the {\em
163   CkCallbackResumeThread} class. {\em CkCallbackResumeThread} is
164 derived from {\em CkCallback} and has specific functionality for
165 threads.  This class automatically suspends the thread when the
166 destructor of the callback is called.  A suspended threaded client
167 will resume when the ``send'' method is invoked on the associated
168 callback.  It can be used in situations when the return value is not
169 needed, and only the synchronization is important. For example:
170
171 \begin{alltt}
172 // Call the "doWork" method and wait until it has completed
173 void mainControlFlow() \{
174   ...perform some work...
175   // call a library
176   doWork(...,CkCallbackResumeThread());
177   // or send a broadcast to a chare collection
178   myProxy.doWork(...,CkCallbackResumeThread());
179   // callback goes out of scope; the thread is suspended until doWork calls 'send' on the callback
180   
181   ...some more work...
182 \}
183 \end{alltt}
184
185 Alternatively, if doWork returns a value of interest, this can be retrieved by
186 passing a pointer to {\em CkCallbackResumeThread}. This pointer will be modified
187 by {\em CkCallbackResumeThread} to point to the incoming message. Notice that
188 the input pointer has to be cast to {\em (void*\&)}:
189
190 \begin{alltt}
191 // Call the "doWork" method and wait until it has completed
192 void mainControlFlow() \{
193   ...perform some work...
194   MyMessage *mymsg;
195   myProxy.doWork(...,CkCallbackResumeThread((void*\&)mymsg));
196   // The thread is suspended until doWork calls send on the callback
197
198   ...some more work using "mymsg"...
199 \}
200 \end{alltt}
201
202 Notice that the instance of {\em CkCallbackResumeThread} is constructed
203 as an anonymous parameter to the ``doWork'' call. This insures that the callback
204 is destroyed as soon as the function returns, thereby suspending the thread.
205
206 It is also possible to allocate a {\em CkCallbackResumeThread} on the heap or on
207 the stack. We suggest that programmers avoid such usage, and favor the anonymous instance construction
208 shown above. For completeness, we still present the code for heap and stack
209 allocation of CkCallbackResumeThread callbacks below.
210
211 For heap allocation, the user must explicitly ``delete'' the callback in order to
212 suspend the thread.
213
214 \begin{alltt}
215 // Call the "doWork" method and wait until it has completed
216 void mainControlFlow() \{
217   ...perform some work...
218   CkCallbackResumeThread cb = new CkCallbackResumeThread();
219   myProxy.doWork(...,cb);
220   ...do not suspend yet, continue some more work...
221   delete cb;
222   // The thread suspends now
223
224   ...some more work after the thread resumes...
225 \}
226 \end{alltt}
227
228 For a callback that is allocated on the stack, its destructor will be called only
229 when the callback variable goes out of scope. In this
230 situation, the function ``thread\_delay'' can be invoked on the callback to
231 force the thread to suspend. This also works for heap allocated callbacks.
232
233 \begin{alltt}
234 // Call the "doWork" method and wait until it has completed
235 void mainControlFlow() \{
236   ...perform some work...
237   CkCallbackResumeThread cb;
238   myProxy.doWork(...,cb);
239   ...do not suspend yet, continue some more work...
240   cb.thread\_delay();
241   // The thread suspends now
242
243   ...some more work after the thread is resumed...
244 \}
245 \end{alltt}
246
247 In all cases a {\em CkCallbackResumeThread} can be used to suspend a thread
248 only once.\\
249 (See \examplerefdir{barnes-charm} for a complete example).\\
250 {\em Deprecated usage}: in the past, ``thread\_delay'' was used to retrieve the
251 incoming message from the callback. While that is still allowed for backward
252 compatibility, its usage is deprecated. The old usage is subject to memory
253 leaks and dangling pointers.
254