changes to sections 3.14,3.15 and 3.16 of Charm++ manual
authorPritish Jetley <pjetley2@illinois.edu>
Wed, 25 May 2011 19:03:33 +0000 (14:03 -0500)
committerPritish Jetley <pjetley2@illinois.edu>
Wed, 25 May 2011 19:03:33 +0000 (14:03 -0500)
doc/charm++/callbacks.tex
doc/charm++/quiesce.tex
doc/charm++/reductions.tex

index 4850fb2a05c6db33fa08ffc0e2f77035b571f15d..e31d68ae08334b6bcd8b6437b2f09ec1e9faab03 100644 (file)
@@ -3,7 +3,7 @@
 \label{callbacks}
 
 A callback is a generic way to transfer control back to a client
-after a library has finished.  For example, after finishing a reduction,
+after a \charmpp{} library has finished.  For example, after finishing a reduction,
 you might want the results passed to some chare's entry method.
 To do this, you create an object of type \kw{CkCallback} with
 the chare's \kw{CkChareID} and entry method index, then pass the
@@ -17,7 +17,7 @@ callback object to the reduction library.
 You can create a \kw{CkCallback} object in a number of ways,
 depending on what you want to have happen when the callback is
 finally invoked.  The callback will be invoked with a \charmpp{}
-message; but the message type will depend on the library that 
+message; but the message type will depend on the \charmpp{} library that 
 actually invokes the callback.  Check the library documentation
 to see what kind of message the library will send to your callback.
 In any case, you are required to free the message passed to you via
@@ -56,7 +56,7 @@ so \uw{param} is allowed to point to heap-allocated data.  Of course, you
 are required to free any storage referenced by \uw{param}.
 
 \item \kw{CkCallback(CkCallback::ignore)} When invoked, the callback
-will do nothing.  This can be useful if the library requires a callback,
+will do nothing.  This can be useful if the \charmpp{} library requires a callback,
 but you don't care when it finishes, or will find out some other way.
 
 \item \kw{CkCallback(CkCallback::ckExit)} When invoked, the callback
@@ -73,8 +73,7 @@ Chare.  Note that a chare proxy will also work in place of a chare id:
 \item \kw{CkCallback(int ep,const CkArrayID \&id)} 
 When invoked,
 the callback will broadcast its message to the given entry method
-of the given array.  As usual, an array proxy will work just as well
-as an array id.
+of the given array.  An array proxy will work in the place of an array id.
 
 \item \kw{CkCallback(int ep,const CkArrayIndex \&idx,const CkArrayID \&id)}
 When invoked,
@@ -103,12 +102,12 @@ in the library section.
 
 \label{libraryInterface}
 
-Here, a ``library'' is simply any code which can be called from several
+Here, a ``library'' is simply any \charmpp{} code which can be called from several
 different places.  From the point of view of a library, a \kw{CkCallback}
 is a destination for the library's result.  \kw{CkCallback} objects can
 be freely copied, marshalled, or even sent in messages.
 
-Postponing threads for a moment, the only thing you can do 
+Postponing the discussion on threads for a moment, the only thing you can do 
 with a CkCallback is to move it around or send a message to it:
 
 \begin{alltt}
@@ -131,17 +130,19 @@ message is immediately sent to the user's client function or entry point,
 so you {\em do} need to document the type of message you will send to the 
 callback so the user knows what to expect.
 
-In alternative to ``send'', the callback can be used in a {\em contribute}
+As an alternative to ``send'', the callback can be used in a {\em contribute}
 collective operation. This will internally invoke the ``send'' method on the
 callback when the contribute operation has finished.
 
-Thread clients are a bit more complicated as they need to suspend while waiting
-for the operation invoked finishes. They will resume when the ``send'' method is
-invoked on the callback.
-In these situations, the class {\em CkCallbackResumeThread} is more useful. This
-class is a subclass of {\em CkCallback} with specific functionality for threads.
-This class automatically suspends the thread when its destructor is called. It
-can be used in situations when the return value is not needed, and only the
+Threaded entry methods can be suspended and resumed through the 
+%are a bit more complicated as they must be suspended while waiting
+%for the invoked operation to finish. 
+{\em CkCallbackResumeThread} class. {\em CkCallbackResumeThread}
+is derived from {\em CkCallback} and has specific functionality for threads.
+This class automatically suspends the thread when the destructor of the callback is called. 
+A suspended threaded client will resume when the ``send'' method is
+invoked on the associated callback.
+It can be used in situations when the return value is not needed, and only the
 synchronization is important. For example:
 
 \begin{alltt}
@@ -152,15 +153,16 @@ void mainControlFlow() \{
   doWork(...,CkCallbackResumeThread());
   // or send a broadcast to a chare collection
   myProxy.doWork(...,CkCallbackResumeThread());
-  // The thread is suspended until doWork calls send on the callback
+  // The thread is suspended until doWork calls 'send' on the callback
+  
   ...some more work...
 \}
 \end{alltt}
 
 Alternatively, if doWork returns a value of interest, this can be retrieved by
 passing a pointer to {\em CkCallbackResumeThread}. This pointer will be modified
-by {\em CkCallbackResume} thread to point to the incoming message. Notice that
-the input pointer has to be cast to {\em (void*\&)}.
+by {\em CkCallbackResumeThread} to point to the incoming message. Notice that
+the input pointer has to be cast to {\em (void*\&)}:
 
 \begin{alltt}
 // Call the "doWork" method and wait until it has completed
@@ -169,20 +171,21 @@ void mainControlFlow() \{
   MyMessage *mymsg;
   myProxy.doWork(...,CkCallbackResumeThread((void*\&)mymsg));
   // The thread is suspended until doWork calls send on the callback
+
   ...some more work using "mymsg"...
 \}
 \end{alltt}
 
 Notice that the instance of {\em CkCallbackResumeThread} is constructed
-on-the-fly as a parameter to the ``doWork'' call. This insures that the callback
-is destroyed as soon as the function returns, therefore suspending the thread.
+as an anonymous parameter to the ``doWork'' call. This insures that the callback
+is destroyed as soon as the function returns, thereby suspending the thread.
 
 It is also possible to allocate a {\em CkCallbackResumeThread} on the heap or on
-the stack. We suggest to avoid such usage, and favor the on-the-fly construction
-shown above. For completeness, we still report code for heap and stack
-allocation of CkCallbackResumeThread callbacks.
+the stack. We suggest that programmers avoid such usage, and favor the anonymous instance construction
+shown above. For completeness, we still present the code for heap and stack
+allocation of CkCallbackResumeThread callbacks below.
 
-For heap allocation, the user will have to explicitely call ``delete'' to
+For heap allocation, the user must explicitly ``delete'' the callback in order to
 suspend the thread.
 
 \begin{alltt}
@@ -194,14 +197,15 @@ void mainControlFlow() \{
   ...do not suspend yet, continue some more work...
   delete cb;
   // The thread suspends now
-  ...some more work using "mymsg"...
+
+  ...some more work after the thread resumes...
 \}
 \end{alltt}
 
-For callbacks allocated on the stack, its destructor will be called only at the
-end of the function, when the current stack goes out of scope. In this
-situation, the function ``thread\_delay'' can be called on the callback to
-force the thread to suspend. This works also for heap allocated callbacks.
+For a callback that is allocated on the stack, its destructor will be called only
+when the callback variable goes out of scope. In this
+situation, the function ``thread\_delay'' can be invoked on the callback to
+force the thread to suspend. This also works for heap allocated callbacks.
 
 \begin{alltt}
 // Call the "doWork" method and wait until it has completed
@@ -212,17 +216,18 @@ void mainControlFlow() \{
   ...do not suspend yet, continue some more work...
   cb.thread\_delay();
   // The thread suspends now
-  ...some more work using "mymsg"...
+
+  ...some more work after the thread is resumed...
 \}
 \end{alltt}
 
-{\em Notice}: a {\em CkCallbackResumeThread} can be used to suspend a thread
+{\em N.B.}: a {\em CkCallbackResumeThread} can be used to suspend a thread
 only once.
 
 {\em Deprecated usage}: in the past, ``thread\_delay'' was used to retrieve the
 incoming message from the callback. While that is still allowed for backward
 compatibility, its usage is deprecated. The old usage is subject to memory
-leaking and dangling pointers.
+leaks and dangling pointers.
 
 %Threaded clients are a bit more complicated-- you need to suspend the
 %calling thread using ``thread\_delay'' which, after the corresponding
index 629ba8c00b4c91eeb7d166b0f351f85adb0b883f..d10088554912cb424cc2c498758592b0eb8bad27 100644 (file)
@@ -26,10 +26,10 @@ corresponding to the \index{chare}chare containing that entry method.  The
 syntax of this call is as follows:
 
 \begin{alltt}
-\kw{myIdx}=CkIndex_\uw{ChareName}::\uw{EntryMethod}(\uw{parameters});
+\kw{myIdx}=CkIndex_\uw{ChareClass}::\uw{EntryMethod}(\uw{parameters});
 \end{alltt}
 
-where \uw{ChareName} is the name of the chare containing
+where \uw{ChareClass} is the C++ class of the chare containing
 the desired entry method, \uw{EntryMethod} is the name of that entry method,
 and \uw{parameters} are the parameters taken by the method.
 These parameters are only used to resolve the proper \uw{EntryMethod};
index 9f5490efefce6a9ece249dcbea687f269164cfb5..72c79080a6ec42b2b1755339efbe9eb1918597c3 100644 (file)
@@ -16,40 +16,49 @@ void contribute(int nBytes,const void *data,CkReduction::reducerType type);
 This call contributes \kw{nBytes} bytes starting at \kw{data} to the
 reduction \kw{type} (see reduction types, below).  Unlike sending a
 message, you may use \kw{data} after the call to \kw{contribute}.  All
-members must call \kw{contribute}, and all must use the same
+members of the chare array or group must call \kw{contribute}, and all of them must use the same
 reduction type.  
 
-When you create a new member, it is expected
+When you create a new chare array element, it is expected
 to contribute to the next reduction not already in progress on that
 processor.  The
-reduction will complete properly even if members are migrated
+reduction will complete properly even if elements are migrated
 or deleted during the reduction. 
 
-For example, if we want to sum each member's single integer myInt, 
+For example, if we want to sum each array/group member's single integer myInt, 
 we would use:
 
 \begin{alltt}
-    //Inside any member method
+    // Inside any member method
     int myInt=get_myInt();
     contribute(sizeof(int),\&myInt,CkReduction::sum_int);
 \end{alltt}
 
 The built-in reduction types (see below) can also handle arrays of
-numbers.  For example, if each element of an array has a pair of
-doubles \uw{forces}[2] which need to be summed up (separately) across
-every element, from each element call:
+numbers.  For example, if each element of a chare array has a pair of
+doubles \uw{forces}[2], the corresponding elements of which are to be added across
+all elements, from each element call:
 
 \begin{alltt}
     double forces[2]=get_my_forces();
     contribute(2*sizeof(double),forces,CkReduction::sum_double);
 \end{alltt}
 
+This will result in a {\tt double} array of 2 elements, the first of which
+contains the sum of all \uw{forces}[0] values, with the second element 
+holding the sum of all \uw{forces}[1] values of the chare array elements.
+
 Note that since C++ arrays (like \uw{forces}[2]) are already pointers, we 
 don't use \&\uw{forces}.
 
-Sometimes it is not important the data to be reduced, but only the fact that all
-elements have reached a synchronization point. In this case a simpler version of
-contribute can be used:
+Reductions do not have to specify commutative-associative operations on data;
+they can also be used to signal the fact that all array/group members
+have reached a certain synchronization point. In this case, a simpler version
+of contribute may be used:
+
+%Sometimes it is not important the data to be reduced, but only the fact that all
+%elements have reached a synchronization point. In this case a simpler version of
+%contribute can be used:
 
 \begin{alltt}
     contribute();
@@ -77,7 +86,7 @@ If different \kw{contribute} calls pass different callbacks, some (unspecified,
 unreliable) callback will be chosen for use.
 \begin{alltt}
     double forces[2]=get_my_forces();
-    //When done, broadcast the CkReductionMsg to ``myReductionEntry''
+    // When done, broadcast the CkReductionMsg to ``myReductionEntry''
     CkCallback cb(CkIndex_myArrayType::myReductionEntry(NULL), thisProxy);
     contribute(2*sizeof(double), forces,CkReduction::sum_double, cb);
 \end{alltt}
@@ -85,11 +94,12 @@ unreliable) callback will be chosen for use.
 In the case of the reduced version used for synchronization purposes, the
 callback parameter will be the only input parameter:
 \begin{alltt}
-    contribute( CkCallback(CkIndex_myArrayType::myReductionEntry(NULL), thisProxy) );
+    CkCallback cb(CkIndex_myArrayType::myReductionEntry(NULL), thisProxy);
+    contribute(cb);
 \end{alltt}
 
 If no member passes a callback to \kw{contribute}, the reduction will use
-the default callback. Programmers can set the default callback for an array or group
+the {\em default} callback. Programmers can set the default callback for an array or group
 using the \kw{ckSetReductionClient} proxy call on processor zero, or
 by passing the callback to {\tt CkArrayOptions::setReductionClient()}
 before creating the array, as described in section~\ref{CkArrayOptions}.
@@ -97,11 +107,11 @@ Again, a \kw{CkReductionMsg} message will be passed to this callback,
 which must delete the message when done.
 
 \begin{alltt}
-    //Somewhere on processor zero:
+    // Somewhere on processor zero:
     myProxy.ckSetReductionClient(new CkCallback(...));
 \end{alltt}
 
-So, for the previous reduction on chare array arr:
+So, for the previous reduction on chare array {\tt arr}:
 \begin{alltt}
     CkCallback *cb = new CkCallback(CkIndex_main::reportIn(NULL),  mainProxy);
     arr.ckSetReductionClient(cb);
@@ -116,7 +126,7 @@ void myReductionEntry(CkReductionMsg *msg)
   double *output=(double *) msg->getData();
   for(int i=0 ; i<reducedArrSize ; i++)
   \{
-   // do something with the reduction results in each output[i] array element
+   // Do something with the reduction results in each output[i] array element
    .
    .
    .
@@ -127,63 +137,73 @@ void myReductionEntry(CkReductionMsg *msg)
 
 (See \kw{pgms/charm++/RedExample} for a complete example).
 
-For backward compatability, rather than a general callback you can
-specify a peculiar kind of C function using \kw{ckSetReductionClient}
+For backward compatibility, in the place of a general callback, you can
+specify a particular kind of C function using \kw{ckSetReductionClient}
 or \kw{setReductionClient}.  This C function takes a user-defined
 parameter (passed to \kw{setReductionClient}) and the actual reduction data,
 which it must not deallocate.
 
 \begin{alltt}
-  //Somewhere on processor zero:
+  // Somewhere on processor zero (possibly in Main::Main, after creating 'myProxy'):
   myProxy.setReductionClient(myClient,(void *)NULL);
 
-void myClient(void *param,int dataSize,void *data)
-\{
-  double *forceSum=(double *)data;
-  cout<<``First force sum is ``<<forceSum[0]<<endl;
-  cout<<``Second force sum is ``<<forceSum[1]<<endl;
-\}
+  // Code for the C function that serves as reduction client:
+  void myClient(void *param,int dataSize,void *data)
+  \{
+    double *forceSum=(double *)data;
+    cout<<``First force sum is ``<<forceSum[0]<<endl;
+    cout<<``Second force sum is ``<<forceSum[1]<<endl;
+  \}
 \end{alltt}
 
 \subsubsection{Typed Reductions}
 
 \label{typed_reductions}
 
-Typically the entry method that is invoked when a reduction is completed
-takes a single argument of type CkReductionMsg. However, by giving an entry
-method the \kw{reductiontarget} attribute, you can instead use entry methods
-that take arguments of the same type that the reduction function yields.
-For example, for a reduction that yields an int, a typed reduction might look
-like this:
+Typically the client entry method of a reduction takes a single argument of
+type CkReductionMsg. However, by giving an entry method the
+\kw{reductiontarget} attribute in the {\tt .ci} file, you can instead use entry methods that take
+arguments of the same type as specified by the {\em contribute} call.  
+When creating a callback to the
+reduction target, the entry method index is generated by 
+{\tt CkReductionTarget(ChareClass, method\_name)} 
+instead of {\tt CkIndex\_ChareClass::method\_name(...)}.
+For example,
+the code for a typed reduction that yields an {\tt int}, would look like this:
 
 \begin{alltt}
-// in the .ci file...
+// In the .ci file...
 entry [reductiontarget] void done(int result);
 
-// in the .cc file...
-void Driver::done(int result) {
+  // Create a callback that invokes the typed reduction client
+  CkCallback cb(CkReductionTarget(Driver,done), driverProxy);
+
+  // Contribution to the reduction...
+  contribute(sizeof(int), &intData, CkReduction::sum_int, cb);
+
+// Definition of the reduction client in the .cc file...
+void Driver::done(int result) 
+\{
    CkPrintf("Reduction value: \%d", result);
-}
+\}
 \end{alltt}
 
-This will also work for arrays, and for any user-defined type with a PUP method
+This will also work for arrays of data elements, and for any user-defined type with a PUP method
 (see ~\ref{sec:pup}). If you know that the reduction will yield a particular
-number of elements, say 3 ints, you can also specify a reduction target which
-takes 3 ints and it will be invoked correctly. When creating a callback to the
-reduction target, the entry method index is generated by {\tt
-CkReductionTarget(chare\_name, method\_name)}.
+number of elements, say 3 {\tt int}s, you can also specify a reduction target which
+takes 3 {\tt int}s and it will be invoked correctly. 
 
 \subsubsection{Built-in Reduction Types}
 
 \label{builtin_reduction}
 
 \charmpp{} includes several built-in reduction types, used to combine 
-the separate contributions.  Any of them may be passed as an
-\kw{CkReduction::reducerType} type to \kw{contribute}.
+individual contributions.  Any of them may be passed as an argument of type
+\kw{CkReduction::reducerType} to \kw{contribute}.
 
-The first four reductions (sum, product, max, and min) work on int,
-float, or double data as indicated by the suffix.  The logical
-reductions (and, or) only work on integer data.  All the built-in
+The first four operations ({\tt sum}, {\tt product}, {\tt max}, and {\tt min}) work on {\tt int},
+{\tt float}, or {\tt double} data as indicated by the suffix.  The logical
+reductions ({\tt and}, {\tt or}) only work on integer data.  All the built-in
 reductions work on either single numbers (pass a pointer) or arrays-- just
 pass the correct number of bytes to \kw{contribute}.
 
@@ -220,14 +240,14 @@ or reductions.  To extract the data from each element, see the description
 below.
 
 \item \kw{CkReduction::concat}-- the result will be a byte-by-byte
-concatentation of all the contributed data.  There is no separation
-added between different contributions.
+concatentation of all the contributed data.  The contributed elements
+are not delimiter-separated. 
 
 \end{enumerate}
 
 
 \kw{CkReduction::set} returns a collection of \kw{CkReduction::setElement}
-objects, one per contribution.  This class has definition:
+objects, one per contribution.  This class has the definition:
 
 \begin{alltt}
 class CkReduction::setElement 
@@ -254,15 +274,19 @@ To extract the contribution of each array element from a reduction set, use the
   \}
 \end{alltt}
 
-The reduction set order is undefined.  Add a source field to your
-contribution if you need to know which array element gave a particular
-contribution.  This will require you to do your own
-serialize/unserialize operation on your element structure if your
-reduction element data is complex.  Consider using the \kw{PUP}
+The reduction set order is undefined.  You should add a source field to the
+contributed elements if you need to know which array element gave a particular
+contribution.  Additionally, if the contributed elements are of a complex 
+data type, you will likely have to supply code for 
+%serialize/unserialize operation on your element structure if your
+%reduction element data is complex.  
+serializing/deserializing them.
+Consider using the \kw{PUP}
 interface see ~\ref{sec:pup} to simplify your object serialization
 needs.
 
-If your data is order dependant, or if your data is just too
+If the outcome of your reduction is dependent on the order in which 
+data elements are processed, or if your data is just too
 heterogenous to be handled elegantly by the predefined types and you
 don't want to undertake multiple reductions, it may be best to define
 your own reduction type.  See the next section
@@ -274,8 +298,9 @@ your own reduction type.  See the next section
 \label{new_type_reduction}
 
 It is possible to define a new type of reduction, performing a 
-user-defined operation on user-defined data.  A reduction function
-combines separate contributions (from this or other processors)
+user-defined operation on user-defined data.  This is done by 
+creating a {\em reduction function}, which 
+combines separate contributions 
 into a single combined value.
 
 The input to a reduction function is a list of \kw{CkReductionMsg}s.
@@ -291,7 +316,7 @@ CkReductionMsg *\uw{reductionFn}(int nMsg,CkReductionMsg **msgs);
 \end{alltt}
 
 For example, a reduction function to add up contributions 
-consisting of two machine short integers would be:
+consisting of two machine {\tt short int}s would be:
 
 \begin{alltt}
 CkReductionMsg *sumTwoShorts(int nMsg,CkReductionMsg **msgs)
@@ -310,14 +335,15 @@ CkReductionMsg *sumTwoShorts(int nMsg,CkReductionMsg **msgs)
 \}
 \end{alltt}
 
-You must register your reduction function with \charmpp{} 
+The reduction function must be registered with \charmpp{} 
 using \kw{CkReduction::addReducer} from
 an \kw{initcall} routine (see section~\ref{initcall} for details
 on the \kw{initcall} mechanism).   \kw{CkReduction::addReducer}
 returns a \kw{CkReduction::reducerType} which you can later 
 pass to \kw{contribute}.  Since \kw{initcall} routines are executed
 once on every node, you can safely store the \kw{CkReduction::reducerType}
-in a global or class-static variable.  For the example above:
+in a global or class-static variable.  For the example above, the reduction
+function is registered and used in the following manner:
 
 \begin{alltt}
 //In the .ci file:
@@ -330,12 +356,12 @@ in a global or class-static variable.  For the example above:
   sumTwoShortsType=CkReduction::addReducer(sumTwoShorts);
 \}
 
-//In some member:
+//In some member function, contribute data to the customized reduction:
   short data[2]=...;
   contribute(2*sizeof(short),data,sumTwoShortsType);
 \end{alltt}
 
 Note that you cannot call \kw{CkReduction::addReducer}
-from anywhere but in an \kw{initcall} routine.
+from anywhere but an \kw{initcall} routine.