c74d0ab718737323f2f44063a835d83a7abde2b9
[charm.git] / doc / charm++ / advancedpup.tex
1 \subsection{Advanced PUP}
2
3 \subsubsection{Dynamic Allocation}
4
5 \label{sec:pupdynalloc}
6
7 If your class has fields that are dynamically allocated, when unpacking
8 these need to be allocated (in the usual way) before you pup them.
9 Deallocation should be left to the class destructor as usual.
10
11 \paragraph{No allocation}
12
13 The simplest case is when there is no dynamic allocation.
14 \begin{alltt}
15 class keepsFoo : public mySuperclass \{
16 private:
17     foo f; /* simple foo object*/
18 public:
19     keepsFoo(void) \{ \}
20     void pup(PUP::er &p) \{
21       mySuperclass::pup(p);
22       p|f; // pup f's fields (calls f.pup(p);) 
23     \}
24     ~keepsFoo() \{ \}
25 \};
26 \end{alltt}
27
28 \paragraph{Allocation outside pup}
29
30 The next simplest case is when we contain a class 
31 that is always allocated during our constructor,
32 and deallocated during our destructor.  Then no allocation
33 is needed within the pup routine.
34 \begin{alltt}
35 class keepsHeapFoo : public mySuperclass \{
36 private:
37     foo *f; /*Heap-allocated foo object*/
38 public:
39     keepsHeapFoo(void) \{
40       f=new foo;
41     \}
42     void pup(PUP::er &p) \{
43       mySuperclass::pup(p);
44       p|*f; // pup f's fields (calls f->pup(p))
45     \}
46     ~keepsHeapFoo() \{delete f;\}
47 \};
48 \end{alltt}
49
50 \paragraph{Allocation during pup}
51
52 If we need values obtained during the pup routine
53 before we can allocate the class, we must 
54 allocate the class inside the pup routine.
55 Be sure to protect the allocation with ``if (p.isUnpacking())''.
56 \begin{alltt}
57 class keepsOneFoo : public mySuperclass \{
58 private:
59     foo *f; /*Heap-allocated foo object*/
60 public:
61     keepsOneFoo(...) \{f=new foo(...);\}
62     keepsOneFoo() \{f=NULL;\} /* pup constructor */
63     void pup(PUP::er &p) \{
64       mySuperclass::pup(p);
65       ...
66       if (p.isUnpacking()) /* must allocate foo now */
67          f=new foo(...);
68       p|*f;//pup f's fields
69     \}
70     ~keepsOneFoo() \{delete f;\}
71 \};
72 \end{alltt}
73
74 \paragraph{Allocatable array}
75
76 For example, if we keep an array of doubles,
77 we need to know how many doubles there are 
78 before we can allocate the array.  Hence we must
79 first pup the array length, do our allocation,
80 and then pup the array data.  We could allocate memory using 
81 malloc/free or other allocators in exactly the same way.
82 \begin{alltt}
83 class keepsDoubles : public mySuperclass \{
84 private:
85     int n;
86     double *arr;/*new'd array of n doubles*/
87 public:
88     keepsDoubles(int n_) \{
89       n=n_;
90       arr=new double[n];
91     \}
92     keepsDoubles() \{ \} 
93     
94     void pup(PUP::er &p) \{
95       mySuperclass::pup(p);
96       p|n;//pup the array length n
97       if (p.isUnpacking())  arr=new double[n];
98       PUParray(p,arr,n); //pup data in the array
99     \}
100     
101     ~keepsDoubles() \{delete[] arr;\}
102 \};
103 \end{alltt}
104
105 \paragraph{NULL object pointer}
106
107 If our allocated object may be NULL, our allocation
108 becomes much more complicated.  We must first check
109 and pup a flag to indicate whether the object exists, 
110 then depending on the flag, pup the object.
111 \begin{alltt}
112 class keepsNullFoo : public mySuperclass \{
113 private:
114     foo *f; /*Heap-allocated foo object, or NULL*/
115 public:
116     keepsNullFoo(...) \{ if (...) f=new foo(...);\}
117     keepsNullFoo() \{f=NULL;\}
118     void pup(PUP::er &p) \{
119       mySuperclass::pup(p);
120       int has_f=(f!=NULL);
121       p|has_f;
122       if (has_f) \{
123         if (p.isUnpacking()) f=new foo;
124         p|*f;
125       \} else \{
126         f=NULL;
127       \}
128     \}
129     ~keepsNullFoo() \{delete f;\}
130 \};
131 \end{alltt}
132
133 This sort of code is normally much longer and more
134 error-prone if split into the various packing/unpacking cases.
135
136 \paragraph{Array of classes}
137
138 An array of actual classes can be treated exactly the same way
139 as an array of basic types.  PUParray will pup each 
140 element of the array properly, calling the appropriate \verb.operator|..
141 \begin{alltt}
142 class keepsFoos : public mySuperclass \{
143 private:
144     int n;
145     foo *arr;/*new'd array of n foos*/
146 public:
147     keepsFoos(int n_) \{
148       n=n_;
149       arr=new foo[n];
150     \}
151     keepsFoos() \{ arr=NULL; \} 
152     
153     void pup(PUP::er &p) \{
154       mySuperclass::pup(p);
155       p|n;//pup the array length n
156       if (p.isUnpacking())  arr=new foo[n];
157       PUParray(p,arr,n); //pup each foo in the array
158     \}
159     
160     ~keepsFoos() \{delete[] arr;\}
161 \};
162 \end{alltt}
163
164
165 \paragraph{Array of pointers to classes}
166
167 An array of pointers to classes must handle each element
168 separately, since the PUParray routine does not work with 
169 pointers.  An ``allocate'' routine to set up the array
170 could simplify this code.  More ambitious is to construct
171 a ``smart pointer'' class that includes a pup routine.
172 \begin{alltt}
173 class keepsFooPtrs : public mySuperclass \{
174 private:
175     int n;
176     foo **arr;/*new'd array of n pointer-to-foos*/
177 public:
178     keepsFooPtrs(int n_) \{
179       n=n_;
180       arr=new foo*[n]; // allocate array
181       for (int i=0;i<n;i++) arr[i]=new foo(...); // allocate i'th foo
182     \}
183     keepsFooPtrs() \{ arr=NULL; \} 
184     
185     void pup(PUP::er &p) \{
186       mySuperclass::pup(p);
187       p|n;//pup the array length n
188       if (p.isUnpacking()) arr=new foo*[n]; // allocate array
189       for (int i=0;i<n;i++) \{
190         if (p.isUnpacking()) arr[i]=new foo(...); // allocate i'th foo
191         p|*arr[i];  //pup the i'th foo
192       \}
193     \}
194     
195     ~keepsFooPtrs() \{
196        for (int i=0;i<n;i++) delete arr[i];
197        delete[] arr;
198      \}
199 \};
200 \end{alltt}
201
202 Note that this will not properly handle the case where
203 some elements of the array are actually subclasses of foo,
204 with virtual methods.  The PUP::able framework described
205 in the next section can be helpful in this case.
206
207
208 \subsubsection{Subclass allocation via PUP::able}
209
210 \label{sec:pup::able}
211 If the class \uw{foo} above might have been a subclass, instead of
212 simply using \uw{new foo} above we would have had to allocate 
213 an object of the appropriate subclass.  Since determining the
214 proper subclass and calling the appropriate constructor yourself can be 
215 difficult, the PUP framework provides a scheme for automatically
216 determining and dynamically allocating subobjects of the appropriate type.
217
218 Your superclass must inherit from \kw{PUP::able}, which provides 
219 the basic machinery used to move the class.  
220 A concrete superclass and all its concrete subclasses require these
221 four features:
222
223 \begin{itemize}
224 \item A line declaring \kw{PUPable \uw{className};} in the .ci file.
225 This registers the class's constructor.
226
227 \item A call to the macro \kw{PUPable\_decl(\uw{className})} in the
228 class's declaration, in the header file.  This adds a virtual 
229 method to your class to allow \kw{PUP::able} to determine your class's type.
230
231 \item A migration constructor---a constructor that takes \kw{CkMigrateMessage *}.
232 This is used to create the new object on the receive side, immediately
233 before calling the new object's \kw{pup} routine.
234
235 \item A working, virtual \kw{pup} method.  You can omit this if your
236 class has no data that needs to be packed.
237 \end{itemize}
238
239 An abstract superclass---a superclass that will never actually be 
240 packed---only needs to inherit from \kw{PUP::able} and include a 
241 \kw{PUPable\_abstract(\uw{className})} macro in their body.  For
242 these abstract classes, the 
243 .ci file, \kw{PUPable\_decl} macro, and constructor are not needed.
244
245 For example, if \uw{parent} is a concrete superclass and \uw{child} its
246 subclass,
247
248 \begin{alltt}
249 //In the .ci file:
250    PUPable parent;
251    PUPable child; //Could also have said ``PUPable parent, child;''
252
253 //In the .h file:
254 class parent : public PUP::able \{
255     ... data members ...
256 public:
257     ... other methods ...
258     parent() \{...\}
259     
260     //PUP::able support: decl, migration constructor, and pup
261     PUPable\_decl(parent);  
262     parent(CkMigrateMessage *m) : PUP::able(m) \{\}
263     virtual void pup(PUP::er &p) \{
264         PUP::able::pup(p);//Call base class
265         ... pup data members as usual ...
266     \}  
267 \};
268 class child : public parent \{
269     ... more data members ...
270 public:    ... more methods, possibly virtual ...
271     child() \{...\}
272     
273     //PUP::able support: decl, migration constructor, and pup
274     PUPable\_decl(child);  
275     child(CkMigrateMessage *m) : parent(m) \{\}
276     virtual void pup(PUP::er &p) \{
277         parent::pup(p);//Call base class
278         ... pup child's data members as usual ...
279     \}  
280 \};
281
282 \end{alltt}
283
284 With these declarations, then, we can automatically 
285 allocate and pup a pointer to a parent or child
286 using the vertical bar \kw{PUP::er} syntax, which on the receive
287 side will create a new object of the appropriate type:
288
289 \begin{alltt}
290 class keepsParent \{
291     parent *obj; //May actually point to a child class (or be NULL)
292 public:
293     ...
294     ~keepsParent() \{
295         delete obj;
296     \}
297     void pup(PUP::er &p) 
298     \{
299         p|obj;
300     \}
301 \};
302 PUPmarshall(keepsParent);
303 \end{alltt}
304
305 This will properly pack, allocate, and unpack obj whether
306 it is actually a parent or child object.  The child class 
307 can use all the usual \CC\ features, such as virtual functions
308 and extra private data.
309
310 If obj is NULL when packed, it will be restored to NULL when unpacked.
311 For example, if the nodes of a binary tree are \kw{PUP::able},
312 one may write a recursive pup routine for the tree quite easily:
313
314 \begin{alltt}
315 // In the .ci file:
316     PUPable treeNode;
317
318 // In the .h file
319 class treeNode : public PUP::able \{
320     treeNode *left;//Left subtree
321     treeNode *right;//Right subtree
322     ... other fields ...
323 public:
324     treeNode(treeNode *l=NULL, treeNode *r=NULL);
325     ~treeNode() \{delete left; delete right;\}
326     
327     // The usual PUP::able support:
328     PUPable\_decl(treeNode);
329     treeNode(CkMigrateMessage *m) : PUP::able(m) \{ left=right=NULL; \}
330     void pup(PUP::er &p) \{
331         PUP::able::pup(p);//Call base class
332         p|left;
333         p|right;
334         ... pup other fields as usual ...
335     \}
336 \};
337 \end{alltt}
338
339 This same implementation will also work properly even if the tree's
340 internal nodes are actually subclasses of treeNode.
341
342 You may prefer to use the macros \kw{PUPable\_def(\uw{className})}
343 and \kw{PUPable\_reg(\uw{className})} rather than using \kw{PUPable}
344 in the .ci file.  \kw{PUPable\_def} provides routine definitions used
345 by the \kw{PUP::able} machinery, and should be included in exactly one
346 source file at file scope.  \kw{PUPable\_reg} registers this class
347 with the runtime system, and should be executed exactly once per node 
348 during program startup.
349
350 Finally, a \kw{PUP::able} superclass like \uw{parent} above 
351 must normally be passed around via a pointer or reference, because the object
352 might actually be some subclass like \uw{child}.  Because
353 pointers and references cannot be passed across processors,
354 for parameter marshalling you must use the special templated 
355 smart pointer classes \kw{CkPointer} and \kw{CkReference},
356 which only need to be listed in the .ci file.
357
358 A \kw{CkReference} is a read-only reference to a \kw{PUP::able} object---it
359 is only valid for the duration of the method call.  A \kw{CkPointer}
360 transfers ownership of the unmarshalled \kw{PUP::able} to the method, so the 
361 pointer can be kept and the object used indefinitely.  
362
363 For example, if the entry method \uw{bar} needs a \kw{PUP::able} \uw{parent}
364 object for in-call processing, you would use a \kw{CkReference} like this:
365
366 \begin{alltt}
367 // In the .ci file:
368     entry void barRef(int x,CkReference<parent> p);
369
370 // In the .h file:
371     void barRef(int x,parent &p) \{
372       // can use p here, but only during this method invocation
373     \}
374 \end{alltt}
375
376 If the entry method needs to keep its parameter, use a \kw{CkPointer} like this:
377 \begin{alltt}
378 // In the .ci file:
379     entry void barPtr(int x,CkPointer<parent> p);
380
381 // In the .h file:
382     void barPtr(int x,parent *p) \{
383       // can keep this pointer indefinitely, but must eventually delete it
384     \}
385 \end{alltt}
386
387 Both \kw{CkReference} and \kw{CkPointer} are read-only from the send 
388 side---unlike messages, which are consumed when sent, the same object 
389 can be passed to several parameter marshalled entry methods.
390 In the example above, we could do:
391
392 \begin{alltt}
393    parent *p=new child;
394    someProxy.barRef(x,*p);
395    someProxy.barPtr(x,p); // Makes a copy of p
396    delete p; // We allocated p, so we destroy it.
397 \end{alltt}
398
399
400 \subsubsection{C and Fortran bindings}
401
402 C and Fortran programmers can use a limited subset of the
403 \kw{PUP::er} capability.  The routines all take a 
404 handle named \kw{pup\_er}.  The routines 
405 have the prototype:
406 \begin{alltt}
407 void pup\_\kw{type}(pup\_er p,\kw{type} *val);
408 void pup\_\kw{type}s(pup\_er p,\kw{type} *vals,int nVals);
409 \end{alltt}
410 The first call is for use with a single element;
411 the second call is for use with an array.
412 The supported types are char, short, int, long,
413 uchar, ushort, uint, ulong, float, and double,
414 which all have the usual C meanings.
415
416 A byte-packing routine
417 \begin{alltt}
418 void pup\_bytes(pup\_er p,void *data,int nBytes);
419 \end{alltt}
420 is also provided, but its use is discouraged
421 for cross-platform puping.
422
423 \kw{pup\_isSizing}, \kw{pup\_isPacking}, \kw{pup\_isUnpacking},
424 and \kw{pup\_isDeleting} calls are also available.
425 Since C and Fortran have no destructors, you should 
426 actually deallocate all data when passed a deleting \kw{pup\_er}.
427
428 C and Fortran users cannot use \kw{PUP::able} objects, 
429 seeking, or write custom \kw{PUP::er}s. Using the \CC\
430 interface is recommended.
431
432
433
434 \subsubsection{Common PUP::ers}
435 \label{sec:PUP:CommonPUPers}
436 The most common \kw{PUP::er}s used are \kw{PUP::sizer},
437 \kw{PUP::toMem}, and \kw{PUP::fromMem}.  These are sizing,
438 packing, and unpacking \kw{PUP::er}s, respectively.
439
440 \kw{PUP::sizer} simply sums up the sizes of the native
441 binary representation of the objects it is passed.
442 \kw{PUP::toMem} copies the binary representation of the
443 objects passed into a preallocated contiguous memory buffer.
444 \kw{PUP::fromMem} copies binary data from a contiguous memory
445 buffer into the objects passed.  All three support the
446 \kw{size} method, which returns the number of bytes used
447 by the objects seen so far.
448
449 Other common \kw{PUP::er}s are \kw{PUP::toDisk}, 
450 \kw{PUP::fromDisk}, and \kw{PUP::xlater}.  The first
451 two are simple filesystem variants of the \kw{PUP::toMem} 
452 and \kw{PUP::fromMem} classes; \kw{PUP::xlater} translates
453 binary data from an unpacking PUP::er into the machine's
454 native binary format, based on a \kw{machineInfo} structure
455 that describes the format used by the source machine.
456
457
458 \subsubsection{PUP::seekBlock}
459
460 It may rarely occur that you require items to be unpacked
461 in a different order than they are packed.  That is, you
462 want a seek capability.  \kw{PUP::er}s support a limited 
463 form of seeking.
464
465 To begin a seek block, create a \kw{PUP::seekBlock} object
466 with your current PUP::er and the number of ``sections'' to 
467 create.  Seek to a (0-based) section number
468 with the seek method, and end the seeking with the endBlock method.
469 For example, if we have two objects A and B, where A's pup
470 depends on and affects some object B, we can pup the two with:
471
472 \begin{alltt}
473 void pupAB(PUP::er &p)
474 \{
475   ... other fields ...
476   PUP::seekBlock s(p,2); //2 seek sections
477   if (p.isUnpacking()) 
478   \{//In this case, pup B first
479     s.seek(1);
480     B.pup(p);
481   \}
482   s.seek(0);
483   A.pup(p,B);
484   
485   if (!p.isUnpacking()) 
486   \{//In this case, pup B last
487     s.seek(1);
488     B.pup(p);
489   \}
490   s.endBlock(); //End of seeking block
491   ... other fields ...
492 \};
493 \end{alltt}
494
495 Note that without the seek block, A's fields would be unpacked
496 over B's memory, with disasterous consequences.
497 The packing or sizing path must traverse the seek sections
498 in numerical order; the unpack path may traverse them in any
499 order.  There is currently a small fixed limit of 3 on the 
500 maximum number of seek sections.
501
502
503 \subsubsection{Writing a PUP::er}
504
505 System-level programmers may occasionally find it useful to define
506 their own \kw{PUP::er} objects.  The system \kw{PUP::er} class is 
507 an abstract base class that funnels all incoming pup requests
508 to a single subroutine:
509
510 \begin{alltt}
511     virtual void bytes(void *p,int n,size\_t itemSize,dataType t);
512 \end{alltt}
513
514 The parameters are, in order, the field address, the number of items,
515 the size of each item, and the type of the items. The \kw{PUP::er}
516 is allowed to use these fields in any way.  However, an isSizing
517 or isPacking PUP::er may not modify the referenced user data; 
518 while an isUnpacking PUP::er may not read the original values of 
519 the user data.  If your PUP::er is not clearly packing (saving values
520 to some format) or unpacking (restoring values), declare it as 
521 sizing \kw{PUP::er}.
522
523
524
525