Docs: refer to illinois.edu, not uiuc.edu
[charm.git] / doc / charm++ / pup.tex
1 \label{sec:pup}
2
3 The \index{PUP} PUP framework is a generic way to describe the data in an object and to use that description for any task requiring serialization.
4 The \charmpp\ system can use this description to pack the object 
5 into a message, and unpack the message into a new object on another 
6 processor. 
7 The name thus is a contraction of the words Pack and UnPack (PUP). 
8
9 Like many \CC\ concepts, the PUP framework is easier to use than 
10 describe: 
11
12 \begin{alltt}
13 class foo : public mySuperclass \{
14  private:
15     double a;
16     int x;
17     char y;
18     unsigned long z;
19     float arr[3];
20  public:
21     ...other methods...
22
23     //pack/unpack method: describe my fields to charm++
24     void pup(PUP::er &p) \{
25       mySuperclass::pup(p);
26       p|a;
27       p|x; p|y; p|z;
28       PUParray(p,arr,3);
29     \}
30 \};
31 \end{alltt}
32
33 This class's \uw{pup} method describes the fields of a \uw{foo} to \charmpp{}.
34 This allows \charmpp\ to: marshall parameters of type \uw{foo} across processors,
35 translate \uw{foo}s across processor architectures, read and write \uw{foo}s
36 to disk files, inspect and modify \uw{foo} objects in the debugger, and 
37 checkpoint and restart calculations involving \uw{foo}s.
38
39
40
41 \section{PUP contract}
42
43 \label{sec:pupcontract}
44 Your object's \uw{pup} method must save and restore all your object's
45 data.  As shown, you save and restore a class's contents by writing a
46 method called ``pup'' which passes all the parts of the class to an
47 object of type \index{PUP::er} \kw{PUP::er}, which does the saving or
48 restoring.  This manual will often use ``pup'' as a verb, meaning ``to
49 save/restore the value of'' or equivalently, ``to call the pup method
50 of''.
51
52 Pup methods for complicated objects normally call the pup methods
53 for their simpler parts.  Since all objects depend on their immediate
54 superclass, the first line of every pup method is a call to the 
55 superclass's pup method---the only time you shouldn't call your superclass's
56 pup method is when you don't have a superclass.  If your superclass has
57 no pup method, you must pup the values in the superclass yourself.
58
59
60 \subsection{PUP operator}
61 \label{sec:pupoperator}
62
63 The recommended way to pup any object \verb.a. is to use \verb.p|a;..
64 This syntax is an operator \verb.|. applied to the \kw{PUP::er} \verb.p.
65 and the user variable \verb.a..
66
67 The \verb.p|a;. syntax works wherever \verb.a. is:
68
69 \begin{itemize}
70  \item A simple type, including char, short, int, long, float, or double.
71     In this case, \verb.p|a;. copies the data in-place.
72     This is equivalent to passing the type directly to the \kw{PUP::er}   
73        using \verb.p(a)..
74  \item Any object with a pup method.
75     In this case, \verb.p|a;. calls the object's pup method.
76     This is equivalent to the statement \kw{a.pup(p);}. 
77  \item A pointer to a PUP::able object, as described in Section~\ref{sec:pup::able}.
78     In this case, \verb.p|a;. allocates and copies the appropriate subclass.
79  \item An object with a \kw{PUPbytes}(\uw{myClass}) declaration in the header.
80     In this case, \verb.p|a;. copies the object as plain bytes, like memcpy.
81  \item An object with a custom \verb.operator |. defined.
82     In this case, \verb.p|a;. calls the custom \verb.operator |..
83 \end{itemize}
84
85 See \examplerefdir{PUP}
86
87 For container types, you must simply pup each element of the container.
88 For arrays, you can use the utility method \kw{PUParray}, which takes
89 the \kw{PUP::er}, the array base pointer, and the array length.
90 This utility method is defined for user-defined types T as:
91   \begin{alltt}
92     template<class T>
93     inline void PUParray(PUP::er &p,T *array,int length) \{
94        for (int i=0;i<length;i++) p|array[i];
95     \}
96   \end{alltt}
97
98
99 \subsection{PUP STL Container Objects}
100 \label{sec:pupstl}
101 If the variable is from the C++ Standard Template Library, you can include 
102 operator\verb.|.'s for STL vector, map, list, pair, and string, templated
103 on anything, by including the header ``pup\_stl.h''.
104
105 See \examplerefdir{PUP/STLPUP}
106
107 \subsection{PUP Dynamic Data}
108 As usual in \CC{}, pointers and allocatable objects usually require special handling. 
109 Typically this only requires a \kw{p.isUnpacking()} conditional block, 
110 where you perform the appropriate allocation.  See 
111 Section~\ref{sec:pupdynalloc} for more information and examples.  
112
113 If the object does not have a pup method, and you cannot add one or use 
114 PUPbytes, you can define an operator\verb.|. to pup the object.
115 For example, if \uw{myClass} contains two fields \uw{a} and \uw{b}, the 
116 operator\verb.|. might look like:
117
118 \begin{alltt}
119   inline void operator|(PUP::er &p,myClass &c) \{
120     p|c.a;
121     p|c.b;
122   \}
123 \end{alltt}
124
125 See \examplerefdir{PUP/HeapPUP}
126
127 \subsection{PUP as bytes}
128
129 \label{sec:pupbytes}
130
131 For classes and structs with many fields, it can be tedious and 
132 error-prone to list all the fields in the pup method.
133 You can avoid this listing in two ways, as long as the
134 object can be safely copied as raw bytes---this is normally 
135 the case for simple structs and classes without pointers.
136
137 \begin{itemize}
138 \item Use the \verb.PUPbytes(myClass). macro in your header file.
139       This lets you use the \verb.p|*myPtr;. syntax 
140       to pup the entire class as sizeof(myClass) raw bytes.
141
142 \item Use \verb.p((void *)myPtr,sizeof(myClass));. in the pup 
143       method.  This is a direct call to pup a set of bytes. 
144       
145 \item Use \verb.p((char *)myCharArray,arraySize);. in the pup 
146       method.  This is a direct call to pup a set of bytes. 
147           Other primitive types may also be used.
148       
149 \end{itemize}
150
151 Note that pupping as bytes is just like using `memcpy': 
152 it does nothing to the data other than copy it whole.
153 For example, if the class contains any pointers, you
154 must make sure to do any allocation needed, and
155 pup the referenced data yourself.
156
157 Pupping as bytes may prevent your pup method from ever being able to
158 work across different machine architectures.  This is currently
159 an uncommon scenario, but heterogenous architectures may become more
160 common, so pupping as bytes is discouraged.
161
162 \subsection{PUP overhead}
163
164 \label{sec:pupoverhead}
165
166 The \kw{PUP::er} overhead is very small---one virtual function call
167 for each item or array to be packed/unpacked.  The actual packing/unpacking is
168 normally a simple memory-to-memory binary copy. 
169
170 For arrays of builtin types like ``int" and ``double", or arrays of a type 
171 with the ``PUPbytes'' declaration, \kw{PUParray} uses an even faster block 
172 transfer, with one virtual function call per array.
173
174
175 \subsection{PUP structured dagger}
176
177 \label{sec:pupsdag}
178
179 Please note that if your object contains Structured Dagger code (see section~\ref{sec:sdag}) you must call the generated method \kw{\_\_sdag\_pup}, after any superclass pup methods, to correctly pup the Structured Dagger state:
180
181 \begin{alltt}
182 class bar : public barParent \{
183  public:
184     bar_SDAG_CODE 
185     ...other methods...
186
187     virtual void pup(PUP::er& p) \{
188       barParent::pup(p);
189       __sdag_pup(p);
190       ...pup other data here...
191     \}
192 \};
193 \end{alltt}
194
195
196
197 \subsection{PUP modes}
198
199 \label{sec:pupmodes}
200
201 \charmpp{} uses your pup method to both pack and unpack, 
202 by passing different types of \kw{PUP::er}s to it.  The method
203 \kw{p.isUnpacking()} returns true if your object is being unpacked---that 
204 is, your object's values are being restored.  Your pup method must
205 work properly in sizing, packing, and unpacking modes; and
206 to save and restore properly, the same fields must be passed 
207 to the \kw{PUP::er}, in the exact same order, in all modes.
208 This means most pup methods can ignore the pup mode.
209
210 Three modes are used, with three separate types of \kw{PUP::er}: 
211 sizing, which only computes the size of your data without modifying it;
212 packing, which reads/saves values out of your data; and unpacking,
213 which writes/restores values into your data.  You can determine
214 exactly which type of \kw{PUP::er} was passed to you using the
215 \kw{p.isSizing()}, \kw{p.isPacking()}, and \kw{p.isUnpacking()}
216 methods. However, sizing and packing should almost always be 
217 handled identically, so most programs should use \kw{p.isUnpacking()}
218 and \kw{!p.isUnpacking()}.  Any program that calls \kw{p.isPacking()} 
219 and does not also call \kw{p.isSizing()} is probably buggy, because
220 sizing and packing must see exactly the same data.
221
222
223 The \kw{p.isDeleting()} flag indicates the object will be deleted
224 after calling the pup method.  This is normally only needed for
225 pup methods called via the C or f90 interface, as provided by 
226 AMPI or the other frameworks.  Other \charmpp{} array elements, 
227 marshalled parameters, and other C++ interface objects 
228 have their destructor called when they are deleted, so the 
229 \kw{p.isDeleting()} call is not normally required---instead,
230 memory should be deallocated in the destructor as usual.
231
232 More specialized modes and PUP::ers are described in section~\ref{sec:PUP:CommonPUPers}. 
233
234
235 \section{PUP Usage Sequence}
236
237 \label{sec:lifecycle}
238
239 \begin{figure}[h]
240 \begin{center}
241 \includegraphics[width=6.0in]{fig/pup}
242 \end{center}
243 \caption{Method sequence of an object with a pup method.}
244 \label{fig:pup}
245 \end{figure}
246
247 Typical method invocation sequence of an object with a pup method is shown in 
248 Figure~\ref{fig:pup}.  As usual in \CC{}, objects are 
249 constructed, do some processing, and are then destroyed.
250
251 Objects can be created in one of two ways: they can
252 be created using a normal constructor as usual; or they
253 can be created using their pup constructor.  The pup constructor
254 for \charmpp{} array elements and \kw{PUP::able} objects
255 is a ``migration constructor'' that takes a single ``CkMigrateMessage *";
256 for other objects, such as parameter marshalled objects,
257 the pup constructor has no parameters.  The pup constructor
258 is always followed by a call to the object's pup method in
259 \verb.isUnpacking. mode.
260
261 Once objects are created, they respond to regular user methods
262 and remote entry methods as usual.  At any time, the object 
263 pup method can be called in \verb.isSizing. or \verb.isPacking.
264 mode.  User methods and sizing or packing pup methods can be called
265 repeatedly over the object lifetime.
266
267 Finally, objects are destroyed by calling their destructor
268 as usual.
269
270
271 \section{Migratable Array Elements using PUP}
272
273 \label{arraymigratable}
274 Array objects can \index{migrate}migrate from one PE to another.  For
275 example, the load balancer (see section~\ref{lbFramework}) might
276 migrate array elements to better balance the load between processors.
277 For an array element to be migratable, it must implement a \uw{pup}
278 method.  The standard PUP contract (see section \ref{sec:pupcontract})
279 and constraints wrt to serializing data, and use of Structured Dagger
280 apply. 
281
282
283 A simple example for an array follows:
284
285 \begin{alltt}
286 //In the .h file:
287 class A2 : public CBase\_A2 \{
288 private: //My data members:
289     int nt;
290     unsigned char chr;
291     float flt[7];
292     int numDbl;
293     double *dbl;
294 public: 
295     //...other declarations
296
297     virtual void pup(PUP::er \&p);
298 \};
299
300 //In the .C file:
301 void A2::pup(PUP::er \&p)
302 \{
303     CBase\_A2::pup(p); //<- MUST call superclass's pup method
304     p|nt;
305     p|chr;
306     p(flt,7);
307     p|numDbl;
308     if (p.isUnpacking()) dbl=new double[numDbl];
309     p(dbl,numDbl);
310 \}
311 \end{alltt}
312
313 The default assumption, as used in the example above, for the object
314 state at PUP time is that a chare, and its member objects, could be
315 migrated at any time while it is inactive, i.e. not executing an entry
316 method.  Actual migration time can be controlled (see
317 section~\ref{lbFramework}) to be less frequent.  If migration timing
318 is fully user controlled, e.g., at the end of a synchronized load
319 balancing step, then PUP implementation can be simplified to only
320 transport ``live'' ephemeral data matching the object state which
321 coincides with migration.  More intricate state based PUPing, for
322 objects whose memory footprint varies substantially with computation
323 phase, can be handled by explicitly maintaining the object's phase in
324 a member variable and implementing phase conditional logic in the PUP
325 method (see section~\ref{sec:pupdynalloc}).
326
327 \section{Marshalling User Defined Data Types via PUP}
328
329 Parameter marshalling requires serialization and is therefore
330 implemented using the PUP framework.  User defined data types passed
331 as parameters must abide by the standard PUP contract (see section
332 \ref{sec:pupcontract}).
333
334 For efficiency, arrays are always copied as blocks of bytes and passed
335 via pointers.  This means classes that need their pup routines to be
336 called, such as those with dynamically allocated data or virtual
337 methods cannot be passed as arrays--use CkVec or STL vectors to pass
338 lists of complicated user-defined classes.  For historical reasons,
339 pointer-accessible structures cannot appear alone in the parameter
340 list (because they are confused with messages).
341
342 The order of marshalling operations on the send side is:
343 \begin{itemize}
344 \item Call ``p\verb.|.a'' on each marshalled parameter with a sizing PUP::er.
345 \item Compute the lengths of each array.
346 \item Call ``p\verb.|.a'' on each marshalled parameter with a packing PUP::er.
347 \item \kw{memcpy} each arrays' data.
348 \end{itemize}
349
350 The order of marshalling operations on the receive side is:
351 \begin{itemize}
352 \item Create an instance of each marshalled parameter using its default constructor.
353 \item Call ``p\verb.|.a'' on each marshalled parameter using an unpacking PUP::er.
354 \item Compute pointers into the message for each array.
355 \end{itemize}
356
357 Finally, very large structures are most efficiently passed via messages,
358 because messages are an efficient, low-level construct that minimizes copying
359 and overhead; but very complicated structures are often most easily passed via 
360 marshalling, because marshalling uses the high-level pup framework.
361
362 See \examplerefdir{PUP/HeapPUP}
363