src/util/pup_c.h

   1 #ifndef _PUP_C_H
   2 #define _PUP_C_H
   3
   4 /*
   5 Pack/UnPack Library for UIUC Parallel Programming Lab
   6 C Bindings version
   7 Orion Sky Lawlor, olawlor@uiuc.edu, 9/11/2000
   8
   9 This library allows you to easily pack an array, structure,
  10 or object into a memory buffer or disk file, and then read
  11 the object back later.  The library will also handle translating
  12 between different machine representations for integers and floats.
  13
  14 This is the C binding-- the main library is in C++.
  15 From C, you can write a pup routine (the client part of the
  16 library), but you can't make pup_er's (the system part).
  17
  18 Typically, the user has to write separate functions for buffer
  19 sizing, pack to memory, unpack from memory, pack to disk, and
  20 unpack from disk.  These functions all perform the exact same function--
  21 namely, they list the members of the array, struct, or object.
  22 Further, all the functions must agree, or the unpacked data will
  23 be garbage.  This library allows the user to write *one* function,
  24 which will perform all needed packing/unpacking.
  25
  26 A simple example is:
  27 typedef struct foo {
  28   int x;
  29   char y;
  30   unsigned long z;
  31   float q[3];
  32 } foo;
  33
  34 void pup_foo(pup_er p,foo *f)
  35 {
  36   pup_int(p,&f->x);
  37   pup_char(p,&f->y);
  38   pup_ulong(p,&f->z);
  39   pup_floats(p,f->q,3);
  40 }
  41
  42 A more complex example is:
  43 typedef struct bar {
  44   foo f;
  45   int nArr; <- Length of array below
  46   double *arr; <- Heap-allocated array
  47 } bar;
  48
  49 void pup_bar(pup_er p,bar *b)
  50 {
  51   pup_foo(p,&b->f);
  52   pup_int(p,&b->nArr);
  53   if (pup_isUnpacking(p))
  54     b->arr=(double *)malloc(b->nArr*sizeof(double));
  55   pup_doubles(p,b->arr,b->nArr);
  56 }
  57
  58 */
  59
  60 #include "conv-config.h"
  61 #include <stddef.h>
  62
  63 #ifdef __cplusplus
  64 extern "C" {
  65 #endif
  66
  67 /*This is actually a PUP::er *, cast to void *.
  68   From C++, you can pass "&p" as a pup_er.
  69 */
  70 typedef void *pup_er;
  71
  72
  73 #ifndef AMPI_INTERNAL_SKIP_FUNCTIONS
  74
  75 #define AMPI_CUSTOM_FUNC(return_type, function_name, ...) \
  76 extern return_type function_name(__VA_ARGS__);
  77
  78 #include "pup_c_functions.h"
  79
  80 #undef AMPI_CUSTOM_FUNC
  81
  82 #endif /* !defined AMPI_INTERNAL_SKIP_FUNCTIONS */
  83
  84
  85 /* These MUST match the sync declarations in pup.h */
  86 enum {
  87   pup_sync_builtin=0x70000000, /* Built-in, standard sync codes begin here */
  88   pup_sync_begin=pup_sync_builtin+0x01000000, /* Sync code at start of collection */
  89   pup_sync_end=pup_sync_builtin+0x02000000, /* Sync code at end of collection */
  90   pup_sync_last_system=pup_sync_builtin+0x09000000, /* Sync code at end of "system" portion of object */
  91   pup_sync_array_m=0x00100000, /* Linear-indexed (0..n) array-- use item to separate */
  92   pup_sync_list_m=0x00200000, /* Some other collection-- use index and item */
  93   pup_sync_object_m=0x00300000, /* Sync mask for general object */
  94
  95   pup_sync_begin_array=pup_sync_begin+pup_sync_array_m,
  96   pup_sync_begin_list=pup_sync_begin+pup_sync_list_m,
  97   pup_sync_begin_object=pup_sync_begin+pup_sync_object_m,
  98
  99   pup_sync_end_array=pup_sync_end+pup_sync_array_m,
 100   pup_sync_end_list=pup_sync_end+pup_sync_list_m,
 101   pup_sync_end_object=pup_sync_end+pup_sync_object_m,
 102
 103   pup_sync_item=pup_sync_builtin+0x00110000, /* Sync code for a list or array item */
 104   pup_sync_index=pup_sync_builtin+0x00120000, /* Sync code for index of item in a list */
 105
 106   pup_sync_last
 107 };
 108
 109 #ifdef __cplusplus
 110 }
 111 #endif
 112
 113 #endif