a786816ebce441c5686017fd30550e9fa5bc2ddf
[charm.git] / doc / charm++ / pup.tex
1 \subsection{PUP}
2
3 \label{sec:pup}
4
5 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.
6 The \charmpp\ system can use this description to pack the object 
7 into a message, and unpack the message into a new object on another 
8 processor. 
9 The name thus is a contraction of the words Pack and UnPack (PUP). 
10
11 Like many \CC\ concepts, the PUP framework is easier to use than 
12 describe: 
13
14 \begin{alltt}
15 class foo : public mySuperclass \{
16  private:
17     double a;
18     int x;
19     char y;
20     unsigned long z;
21     float arr[3];
22  public:
23     ...other methods...
24
25     //pack/unpack routine: describe my fields to charm++
26     void pup(PUP::er &p) \{
27       p|a;
28       p|x; p|y; p|z;
29       PUParray(p,arr,3);
30     \}
31 \};
32 \end{alltt}
33
34 This class's pup routine describes the fields of a \uw{foo} to \charmpp{}.
35 This allows \charmpp\ to: marshall parameters of type \uw{foo} across processors,
36 translate \uw{foo}s across processor architectures, read and write \uw{foo}s
37 to disk files, inspect and modify \uw{foo} objects in the debugger, and 
38 checkpoint and restart calculations involving \uw{foo}s.
39
40
41
42 \subsubsection{PUP contract}
43
44 Your object's pup routine must save and restore all your object's data.
45 As shown, you save and restore a class's contents by writing a routine c
46 alled ``pup'' which passes all the parts of the class to an object of type 
47 \index{PUP::er} \kw{PUP::er}, which does the saving or restoring.  
48 We often use ``pup'' as a verb, meaning ``to save/restore the value of''
49 or equivalently, ``to call the pup routine of''.
50
51 Pup routines for complicated objects normally call the pup routines
52 for their simpler parts. If your class's declaration in the ci file
53 includes a parent class, the generated code in CBase will call that
54 class's pup routine automatically\footnote{In versions of \charmpp
55   prior to 6.4, this was not automatic. Older code called
56   \kw{CBase\_ClassName::pup(p)} at the beginning of each pup
57   routine. This has been made a no-op so as not to break the API.}. If
58 your class has a parent class that is not declared in the ci file, you
59 are responsible for packing it appropriately, either by calling its
60 pup routine explicitly from your own, or by packing its fields
61 individually.
62
63
64 \paragraph{PUP operator}
65
66 \label{sec:pupstl}
67
68 The recommended way to pup any object \verb.a. is to use \verb.p|a;..
69 This syntax is an operator \verb.|. applied to the \kw{PUP::er} \verb.p.
70 and the user variable \verb.a..
71
72 The \verb.p|a;. syntax works wherever a is:
73
74 \begin{itemize}
75  \item A simple type, including char, short, int, long, float, or double.
76     In this case, \verb.p|a;. copies the data in-place.
77     This is equivalent to passing the type directly to the \kw{PUP::er}   
78        using \verb.p(a)..
79  \item Any object with a pup routine.
80     In this case, \verb.p|a;. calls the object's pup routine.
81     This is equivalent to the statement \kw{a.pup(p);}. 
82  \item A pointer to a PUP::able object, as described in Section~\ref{sec:pup::able}.
83     In this case, \verb.p|a;. allocates and copies the appropriate subclass.
84  \item An object with a \kw{PUPbytes}(\uw{myClass}) declaration in the header.
85     In this case, \verb.p|a;. copies the object as plain bytes, like memcpy.
86  \item An object with a custom \verb.operator |. defined.
87     In this case, \verb.p|a;. calls the custom \verb.operator |..
88 \end{itemize}
89
90 For container types, you must simply pup each element of the container.
91 For arrays, you can use the utility routine \kw{PUParray}, which takes
92 the \kw{PUP::er}, the array base pointer, and the array length.
93 This utility routine is defined for user-defined types T as:
94   \begin{alltt}
95     template<class T>
96     inline void PUParray(PUP::er &p,T *array,int length) \{
97        for (int i=0;i<length;i++) p|array[i];
98     \}
99   \end{alltt}
100
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 As usual in \CC{}, pointers and allocatable objects usually require special handling. 
106 Typically this only requires a \kw{p.isUnpacking()} conditional block, 
107 where you perform the appropriate allocation.  See 
108 Section~\ref{sec:pupdynalloc} for more information and examples.  
109
110 If the object does not have a pup routine, and you cannot add one or use 
111 PUPbytes, you can define an operator\verb.|. to pup the object.
112 For example, if \uw{myClass} contains two fields \uw{a} and \uw{b}, the 
113 operator\verb.|. might look like:
114
115 \begin{alltt}
116   inline void operator|(PUP::er &p,myClass &c) \{
117     p|c.a;
118     p|c.b;
119   \}
120 \end{alltt}
121
122
123 \paragraph{PUP as bytes}
124
125 \label{sec:pupbytes}
126
127 For classes and structs with many fields, it can be tedious and 
128 error-prone to list all the fields in the pup routine.
129 You can avoid this listing in two ways, as long as the
130 object can be safely copied as raw bytes---this is normally 
131 the case for simple structs and classes without pointers.
132
133 \begin{itemize}
134 \item Use the \verb.PUPbytes(myClass). macro in your header file.
135       This lets you use the \verb.p|*myPtr;. syntax 
136       to pup the entire class as sizeof(myClass) raw bytes.
137
138 \item Use \verb.p((void *)myPtr,sizeof(myClass));. in the pup 
139       routine.  This is a direct call to pup a set of bytes. 
140       
141 \item Use \verb.p((char *)myCharArray,arraySize);. in the pup 
142       routine.  This is a direct call to pup a set of bytes. 
143           Other primitive types may also be used.
144       
145 \end{itemize}
146
147 Note that pupping as bytes is just like using `memcpy': 
148 it does nothing to the data but copy it whole.
149 For example, if the class contains any pointers, you
150 must make sure to do any allocation needed, and
151 pup the referenced data yourself.
152
153 Pupping as bytes will prevent your pup routine from 
154 ever being able to work across different machine 
155 architectures.  We don't do this very often yet, but 
156 eventually may, so pupping as bytes is currently discouraged.
157
158
159
160 \paragraph{PUP overhead}
161
162 \label{sec:pupoverhead}
163
164 The \kw{PUP::er} overhead is very small---one virtual function call
165 for each item or array to be packed/unpacked.  The actual packing/unpacking is
166 normally a simple memory-to-memory binary copy. 
167
168 For arrays of builtin types like ``int" and ``double", or arrays of a type 
169 with the ``PUPbytes'' declaration, \kw{PUParray} uses an even faster block 
170 transfer, with one virtual function call per array.
171
172
173 \paragraph{PUP structured dagger}
174
175 \label{sec:pupsdag}
176
177 Please note that if your object contains Structured Dagger code (see section~\ref{sec:sdag}) you must call the generated routine \kw{\_\_sdag\_pup} to correctly pup the Structured Dagger state:
178
179 \begin{alltt}
180 class bar : public barParent \{
181  public:
182     bar_SDAG_CODE 
183     ...other methods...
184
185     virtual void pup(PUP::er& p) \{
186       __sdag_pup(p);
187       ...pup other data here...
188     \}
189 \};
190 \end{alltt}
191
192
193
194 \paragraph{PUP modes}
195
196 \label{sec:pupmodes}
197
198 \charmpp{} uses your pup routine to both pack and unpack, 
199 by passing different types of \kw{PUP::er}s to it.  The routine
200 \kw{p.isUnpacking()} returns true if your object is being unpacked---that 
201 is, your object's values are being restored.  Your pup routine must
202 work properly in sizing, packing, and unpacking modes; and
203 to save and restore properly, the same fields must be passed 
204 to the \kw{PUP::er}, in the exact same order, in all modes.
205 This means most pup routines can ignore the pup mode.
206
207 Three modes are used, with three separate types of \kw{PUP::er}: 
208 sizing, which only computes the size of your data without modifying it;
209 packing, which reads/saves values out of your data; and unpacking,
210 which writes/restores values into your data.  You can determine
211 exactly which type of \kw{PUP::er} was passed to you using the
212 \kw{p.isSizing()}, \kw{p.isPacking()}, and \kw{p.isUnpacking()}
213 routines. However, sizing and packing should almost always be 
214 handled identically, so most programs should use \kw{p.isUnpacking()}
215 and \kw{!p.isUnpacking()}.  Any program that calls \kw{p.isPacking()} 
216 and does not also call \kw{p.isSizing()} is probably buggy, because
217 sizing and packing must see exactly the same data.
218
219
220 The \kw{p.isDeleting()} flag indicates the object will be deleted
221 after calling the pup routine.  This is normally only needed for
222 pup routines called via the C or f90 interface, as provided by 
223 AMPI or the FEM framework.  Other \charmpp{} array elements, 
224 marshalled parameters, and other C++ interface objects 
225 have their destructor called when they are deleted, so the 
226 \kw{p.isDeleting()} call is not normally required---instead,
227 memory should be deallocated in the destructor as usual.
228
229
230 \subsubsection{Life Cycle}
231
232 \label{sec:lifecycle}
233
234 \begin{figure}[h]
235 \begin{center}
236 \includegraphics[width=6.0in]{fig/pup}
237 \end{center}
238 \caption{Life cycle of an object with a pup routine.}
239 \label{fig:pup}
240 \end{figure}
241
242 The life cycle of an object with a pup routine is shown in 
243 Figure~\ref{fig:pup}.  As usual in \CC{}, objects are 
244 constructed, do some processing, and are then destroyed.
245
246 Objects can be created in one of two ways: they can
247 be created using a normal constructor as usual; or they
248 can be created using their pup constructor.  The pup constructor
249 for \charmpp{} array elements and \kw{PUP::able} objects
250 is a ``migration constructor'' that takes a single ``CkMigrateMessage *";
251 for other objects, such as parameter marshalled objects,
252 the pup constructor has no parameters.  The pup constructor
253 is always followed by a call to the object's pup routine in
254 \verb.isUnpacking. mode.
255
256 Once objects are created, they respond to regular user methods
257 and remote entry methods as usual.  At any time, the object 
258 pup routine can be called in \verb.isSizing. or \verb.isPacking.
259 mode.  User methods and sizing or packing pup routines can be called
260 repeatedly over the object lifetime.
261
262 Finally, objects are destroyed by calling their destructor
263 as usual.
264
265
266
267 \subsubsection{Dynamic Allocation}
268
269 \label{sec:pupdynalloc}
270
271 If your class has fields that are dynamically allocated, when unpacking
272 these need to be allocated (in the usual way) before you pup them.
273 Deallocation should be left to the class destructor as usual.
274
275 \paragraph{No allocation}
276
277 The simplest case is when there is no dynamic allocation.
278 \begin{alltt}
279 class keepsFoo : public mySuperclass \{
280 private:
281     foo f; /* simple foo object*/
282 public:
283     keepsFoo(void) \{ \}
284     void pup(PUP::er &p) \{
285       p|f; // pup f's fields (calls f.pup(p);) 
286     \}
287     ~keepsFoo() \{ \}
288 \};
289 \end{alltt}
290
291 \paragraph{Allocation outside pup}
292
293 The next simplest case is when we contain a class 
294 that is always allocated during our constructor,
295 and deallocated during our destructor.  Then no allocation
296 is needed within the pup routine.
297 \begin{alltt}
298 class keepsHeapFoo : public mySuperclass \{
299 private:
300     foo *f; /*Heap-allocated foo object*/
301 public:
302     keepsHeapFoo(void) \{
303       f=new foo;
304     \}
305     void pup(PUP::er &p) \{
306       p|*f; // pup f's fields (calls f->pup(p))
307     \}
308     ~keepsHeapFoo() \{delete f;\}
309 \};
310 \end{alltt}
311
312 \paragraph{Allocation during pup}
313
314 If we need values obtained during the pup routine
315 before we can allocate the class, we must 
316 allocate the class inside the pup routine.
317 Be sure to protect the allocation with ``if (p.isUnpacking())''.
318 \begin{alltt}
319 class keepsOneFoo : public mySuperclass \{
320 private:
321     foo *f; /*Heap-allocated foo object*/
322 public:
323     keepsOneFoo(...) \{f=new foo(...);\}
324     keepsOneFoo() \{f=NULL;\} /* pup constructor */
325     void pup(PUP::er &p) \{
326       ...
327       if (p.isUnpacking()) /* must allocate foo now */
328          f=new foo(...);
329       p|*f;//pup f's fields
330     \}
331     ~keepsOneFoo() \{delete f;\}
332 \};
333 \end{alltt}
334
335 \paragraph{Allocatable array}
336
337 For example, if we keep an array of doubles,
338 we need to know how many doubles there are 
339 before we can allocate the array.  Hence we must
340 first pup the array length, do our allocation,
341 and then pup the array data.  We could allocate memory using 
342 malloc/free or other allocators in exactly the same way.
343 \begin{alltt}
344 class keepsDoubles : public mySuperclass \{
345 private:
346     int n;
347     double *arr;/*new'd array of n doubles*/
348 public:
349     keepsDoubles(int n_) \{
350       n=n_;
351       arr=new double[n];
352     \}
353     keepsDoubles() \{ \} 
354     
355     void pup(PUP::er &p) \{
356       p|n;//pup the array length n
357       if (p.isUnpacking())  arr=new double[n];
358       PUParray(p,arr,n); //pup data in the array
359     \}
360     
361     ~keepsDoubles() \{delete[] arr;\}
362 \};
363 \end{alltt}
364
365 \paragraph{NULL object pointer}
366
367 If our allocated object may be NULL, our allocation
368 becomes much more complicated.  We must first check
369 and pup a flag to indicate whether the object exists, 
370 then depending on the flag, pup the object.
371 \begin{alltt}
372 class keepsNullFoo : public mySuperclass \{
373 private:
374     foo *f; /*Heap-allocated foo object, or NULL*/
375 public:
376     keepsNullFoo(...) \{ if (...) f=new foo(...);\}
377     keepsNullFoo() \{f=NULL;\}
378     void pup(PUP::er &p) \{
379       int has_f=(f!=NULL);
380       p|has_f;
381       if (has_f) {
382         if (p.isUnpacking()) f=new foo;
383         p|*f;
384       } else {
385         f=NULL;
386       }
387     \}
388     ~keepsNullFoo() \{delete f;\}
389 \};
390 \end{alltt}
391
392 This sort of code is normally much longer and more
393 error-prone if split into the various packing/unpacking cases.
394
395 \paragraph{Array of classes}
396
397 An array of actual classes can be treated exactly the same way
398 as an array of basic types.  PUParray will pup each 
399 element of the array properly, calling the appropriate \verb.operator|..
400 \begin{alltt}
401 class keepsFoos : public mySuperclass \{
402 private:
403     int n;
404     foo *arr;/*new'd array of n foos*/
405 public:
406     keepsFoos(int n_) \{
407       n=n_;
408       arr=new foo[n];
409     \}
410     keepsFoos() \{ arr=NULL; \} 
411     
412     void pup(PUP::er &p) \{
413       p|n;//pup the array length n
414       if (p.isUnpacking())  arr=new foo[n];
415       PUParray(p,arr,n); //pup each foo in the array
416     \}
417     
418     ~keepsFoos() \{delete[] arr;\}
419 \};
420 \end{alltt}
421
422
423 \paragraph{Array of pointers to classes}
424
425 An array of pointers to classes must handle each element
426 separately, since the PUParray routine does not work with 
427 pointers.  An ``allocate'' routine to set up the array
428 could simplify this code.  More ambitious is to construct
429 a ``smart pointer'' class that includes a pup routine.
430 \begin{alltt}
431 class keepsFooPtrs : public mySuperclass \{
432 private:
433     int n;
434     foo **arr;/*new'd array of n pointer-to-foos*/
435 public:
436     keepsFooPtrs(int n_) \{
437       n=n_;
438       arr=new foo*[n]; // allocate array
439       for (int i=0;i<n;i++) arr[i]=new foo(...); // allocate i'th foo
440     \}
441     keepsFooPtrs() \{ arr=NULL; \} 
442     
443     void pup(PUP::er &p) \{
444       p|n;//pup the array length n
445       if (p.isUnpacking()) arr=new foo*[n]; // allocate array
446       for (int i=0;i<n;i++) \{
447         if (p.isUnpacking()) arr[i]=new foo(...); // allocate i'th foo
448         p|*arr[i];  //pup the i'th foo
449       \}
450     \}
451     
452     ~keepsFooPtrs() \{
453        for (int i=0;i<n;i++) delete arr[i];
454        delete[] arr;
455      \}
456 \};
457 \end{alltt}
458
459 Note that this will not properly handle the case where
460 some elements of the array are actually subclasses of foo,
461 with virtual methods.  The PUP::able framework described
462 in the next section can be helpful in this case.
463
464
465 \subsubsection{Subclass allocation via PUP::able}
466
467 \label{sec:pup::able}
468 If the class \uw{foo} above might have been a subclass, instead of
469 simply using \uw{new foo} above we would have had to allocate 
470 an object of the appropriate subclass.  Since determining the
471 proper subclass and calling the appropriate constructor yourself can be 
472 difficult, the PUP framework provides a scheme for automatically
473 determining and dynamically allocating subobjects of the appropriate type.
474
475 Your superclass must inherit from \kw{PUP::able}, which provides 
476 the basic machinery used to move the class.  
477 A concrete superclass and all its concrete subclasses require these
478 four features:
479
480 \begin{itemize}
481 \item A line declaring \kw{PUPable \uw{className};} in the .ci file.
482 This registers the class's constructor.
483
484 \item A call to the macro \kw{PUPable\_decl(\uw{className})} in the
485 class's declaration, in the header file.  This adds a virtual 
486 method to your class to allow \kw{PUP::able} to determine your class's type.
487
488 \item A migration constructor---a constructor that takes \kw{CkMigrateMessage *}.
489 This is used to create the new object on the receive side, immediately
490 before calling the new object's \kw{pup} routine.
491
492 \item A working, virtual \kw{pup} method.  You can omit this if your
493 class has no data that needs to be packed.
494 \end{itemize}
495
496 An abstract superclass---a superclass that will never actually be 
497 packed---only needs to inherit from \kw{PUP::able} and include a 
498 \kw{PUPable\_abstract(\uw{className})} macro in their body.  For
499 these abstract classes, the 
500 .ci file, \kw{PUPable\_decl} macro, and constructor are not needed.
501
502 For example, if \uw{parent} is a concrete superclass and \uw{child} its
503 subclass,
504
505 \begin{alltt}
506 //In the .ci file:
507    PUPable parent;
508    PUPable child; //Could also have said ``PUPable parent, child;''
509
510 //In the .h file:
511 class parent : public PUP::able \{
512     ... data members ...
513 public:
514     ... other methods ...
515     parent() \{...\}
516     
517     //PUP::able support: decl, migration constructor, and pup
518     PUPable\_decl(parent);  
519     parent(CkMigrateMessage *m) : PUP::able(m) \{\}
520     virtual void pup(PUP::er &p) \{
521         PUP::able::pup(p);//Call base class
522         ... pup data members as usual ...
523     \}  
524 \};
525 class child : public parent \{
526     ... more data members ...
527 public:    ... more methods, possibly virtual ...
528     child() \{...\}
529     
530     //PUP::able support: decl, migration constructor, and pup
531     PUPable\_decl(child);  
532     child(CkMigrateMessage *m) : parent(m) \{\}
533     virtual void pup(PUP::er &p) \{
534         parent::pup(p);//Call base class
535         ... pup child's data members as usual ...
536     \}  
537 \};
538
539 \end{alltt}
540
541 With these declarations, then, we can automatically 
542 allocate and pup a pointer to a parent or child
543 using the vertical bar \kw{PUP::er} syntax, which on the receive
544 side will create a new object of the appropriate type:
545
546 \begin{alltt}
547 class keepsParent \{
548     parent *obj; //May actually point to a child class (or be NULL)
549 public:
550     ...
551     ~keepsParent() \{
552         delete obj;
553     \}
554     void pup(PUP::er &p) 
555     \{
556         p|obj;
557     \}
558 \};
559 PUPmarshall(keepsParent);
560 \end{alltt}
561
562 This will properly pack, allocate, and unpack obj whether
563 it is actually a parent or child object.  The child class 
564 can use all the usual \CC\ features, such as virtual functions
565 and extra private data.
566
567 If obj is NULL when packed, it will be restored to NULL when unpacked.
568 For example, if the nodes of a binary tree are \kw{PUP::able},
569 one may write a recursive pup routine for the tree quite easily:
570
571 \begin{alltt}
572 // In the .ci file:
573     PUPable treeNode;
574
575 // In the .h file
576 class treeNode : public PUP::able \{
577     treeNode *left;//Left subtree
578     treeNode *right;//Right subtree
579     ... other fields ...
580 public:
581     treeNode(treeNode *l=NULL, treeNode *r=NULL);
582     ~treeNode() \{delete left; delete right;\}
583     
584     // The usual PUP::able support:
585     PUPable\_decl(treeNode);
586     treeNode(CkMigrateMessage *m) : PUP::able(m) \{ left=right=NULL; \}
587     void pup(PUP::er &p) \{
588         PUP::able::pup(p);//Call base class
589         p|left;
590         p|right;
591         ... pup other fields as usual ...
592     \}
593 \};
594 \end{alltt}
595
596 This same implementation will also work properly even if the tree's
597 internal nodes are actually subclasses of treeNode.
598
599 You may prefer to use the macros \kw{PUPable\_def(\uw{className})}
600 and \kw{PUPable\_reg(\uw{className})} rather than using \kw{PUPable}
601 in the .ci file.  \kw{PUPable\_def} provides routine definitions used
602 by the \kw{PUP::able} machinery, and should be included in exactly one
603 source file at file scope.  \kw{PUPable\_reg} registers this class
604 with the runtime system, and should be executed exactly once per node 
605 during program startup.
606
607 Finally, a \kw{PUP::able} superclass like \uw{parent} above 
608 must normally be passed around via a pointer or reference, because the object
609 might actually be some subclass like \uw{child}.  Because
610 pointers and references cannot be passed across processors,
611 for parameter marshalling you must use the special templated 
612 smart pointer classes \kw{CkPointer} and \kw{CkReference},
613 which only need to be listed in the .ci file.
614
615 A \kw{CkReference} is a read-only reference to a \kw{PUP::able} object---it
616 is only valid for the duration of the method call.  A \kw{CkPointer}
617 transfers ownership of the unmarshalled \kw{PUP::able} to the method, so the 
618 pointer can be kept and the object used indefinitely.  
619
620 For example, if the entry method \uw{bar} needs a \kw{PUP::able} \uw{parent}
621 object for in-call processing, you would use a \kw{CkReference} like this:
622
623 \begin{alltt}
624 // In the .ci file:
625     entry void barRef(int x,CkReference<parent> p);
626
627 // In the .h file:
628     void barRef(int x,parent &p) \{
629       // can use p here, but only during this method invocation
630     \}
631 \end{alltt}
632
633 If the entry method needs to keep its parameter, use a \kw{CkPointer} like this:
634 \begin{alltt}
635 // In the .ci file:
636     entry void barPtr(int x,CkPointer<parent> p);
637
638 // In the .h file:
639     void barPtr(int x,parent *p) \{
640       // can keep this pointer indefinitely, but must eventually delete it
641     \}
642 \end{alltt}
643
644 Both \kw{CkReference} and \kw{CkPointer} are read-only from the send 
645 side---unlike messages, which are consumed when sent, the same object 
646 can be passed to several parameter marshalled entry methods.
647 In the example above, we could do:
648
649 \begin{alltt}
650    parent *p=new child;
651    someProxy.barRef(x,*p);
652    someProxy.barPtr(x,p); // Makes a copy of p
653    delete p; // We allocated p, so we destroy it.
654 \end{alltt}
655
656
657 \subsubsection{C and Fortran bindings}
658
659 C and Fortran programmers can use a limited subset of the
660 \kw{PUP::er} capability.  The routines all take a 
661 handle named \kw{pup\_er}.  The routines 
662 have the prototype:
663 \begin{alltt}
664 void pup\_\kw{type}(pup\_er p,\kw{type} *val);
665 void pup\_\kw{type}s(pup\_er p,\kw{type} *vals,int nVals);
666 \end{alltt}
667 The first call is for use with a single element;
668 the second call is for use with an array.
669 The supported types are char, short, int, long,
670 uchar, ushort, uint, ulong, float, and double,
671 which all have the usual C meanings.
672
673 A byte-packing routine
674 \begin{alltt}
675 void pup\_bytes(pup\_er p,void *data,int nBytes);
676 \end{alltt}
677 is also provided, but its use is discouraged
678 for cross-platform puping.
679
680 \kw{pup\_isSizing}, \kw{pup\_isPacking}, \kw{pup\_isUnpacking},
681 and \kw{pup\_isDeleting} calls are also available.
682 Since C and Fortran have no destructors, you should 
683 actually deallocate all data when passed a deleting \kw{pup\_er}.
684
685 C and Fortran users cannot use \kw{PUP::able} objects, 
686 seeking, or write custom \kw{PUP::er}s. Using the \CC\
687 interface is recommended.
688
689
690
691 \subsubsection{Common PUP::ers}
692
693 The most common \kw{PUP::er}s used are \kw{PUP::sizer},
694 \kw{PUP::toMem}, and \kw{PUP::fromMem}.  These are sizing,
695 packing, and unpacking \kw{PUP::er}s, respectively.
696
697 \kw{PUP::sizer} simply sums up the sizes of the native
698 binary representation of the objects it is passed.
699 \kw{PUP::toMem} copies the binary representation of the
700 objects passed into a preallocated contiguous memory buffer.
701 \kw{PUP::fromMem} copies binary data from a contiguous memory
702 buffer into the objects passed.  All three support the
703 \kw{size} method, which returns the number of bytes used
704 by the objects seen so far.
705
706 Other common \kw{PUP::er}s are \kw{PUP::toDisk}, 
707 \kw{PUP::fromDisk}, and \kw{PUP::xlater}.  The first
708 two are simple filesystem variants of the \kw{PUP::toMem} 
709 and \kw{PUP::fromMem} classes; \kw{PUP::xlater} translates
710 binary data from an unpacking PUP::er into the machine's
711 native binary format, based on a \kw{machineInfo} structure
712 that describes the format used by the source machine.
713
714
715 \subsubsection{PUP::seekBlock}
716
717 It may rarely occur that you require items to be unpacked
718 in a different order than they are packed.  That is, you
719 want a seek capability.  \kw{PUP::er}s support a limited 
720 form of seeking.
721
722 To begin a seek block, create a \kw{PUP::seekBlock} object
723 with your current PUP::er and the number of ``sections'' to 
724 create.  Seek to a (0-based) section number
725 with the seek method, and end the seeking with the endBlock method.
726 For example, if we have two objects A and B, where A's pup
727 depends on and affects some object B, we can pup the two with:
728
729 \begin{alltt}
730 void pupAB(PUP::er &p)
731 \{
732   ... other fields ...
733   PUP::seekBlock s(p,2); //2 seek sections
734   if (p.isUnpacking()) 
735   \{//In this case, pup B first
736     s.seek(1);
737     B.pup(p);
738   \}
739   s.seek(0);
740   A.pup(p,B);
741   
742   if (!p.isUnpacking()) 
743   \{//In this case, pup B last
744     s.seek(1);
745     B.pup(p);
746   \}
747   s.endBlock(); //End of seeking block
748   ... other fields ...
749 \};
750 \end{alltt}
751
752 Note that without the seek block, A's fields would be unpacked
753 over B's memory, with disasterous consequences.
754 The packing or sizing path must traverse the seek sections
755 in numerical order; the unpack path may traverse them in any
756 order.  There is currently a small fixed limit of 3 on the 
757 maximum number of seek sections.
758
759
760 \subsubsection{Writing a PUP::er}
761
762 System-level programmers may occasionally find it useful to define
763 their own \kw{PUP::er} objects.  The system \kw{PUP::er} class is 
764 an abstract base class that funnels all incoming pup requests
765 to a single subroutine:
766
767 \begin{alltt}
768     virtual void bytes(void *p,int n,size\_t itemSize,dataType t);
769 \end{alltt}
770
771 The parameters are, in order, the field address, the number of items,
772 the size of each item, and the type of the items. The \kw{PUP::er}
773 is allowed to use these fields in any way.  However, an isSizing
774 or isPacking PUP::er may not modify the referenced user data; 
775 while an isUnpacking PUP::er may not read the original values of 
776 the user data.  If your PUP::er is not clearly packing (saving values
777 to some format) or unpacking (restoring values), declare it as 
778 sizing \kw{PUP::er}.
779
780
781