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