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