Documentation Set for Swarm 2.2
Prev | Reference I. Defobj Library | Next

# Serialization

## Name

Serialization -- Object serialization protocol.

## Description

Object serialization protocol.

## Protocols adopted by Serialization

None

## Methods

### Phase: Creating

- - hdf5InCreate: (id <HDF5>)hdf5Obj
  Process HDF5 object to set create-time parameters.

- - lispInCreate: expr
  Process keyword parameters in expression in order to get create-time parameters.

### Phase: Setting

- - hdf5In: (id <HDF5>)hdf5Obj
  Load instance variables from an HDF5 object.

- - lispIn: expr
  Process an archived Lisp representation of object state from a list of instance variable name / value pairs.

### Phase: Using

- - (void)updateArchiver: (id <Archiver>)archiver

- - (void)hdf5OutDeep: (id <HDF5>)hdf5obj
  Output a deep HDF5 representation of object state to a stream.

- - (void)hdf5OutShallow: (id <HDF5>)hdf5obj
  Output a shallow HDF5 representation of object state to a stream.

- - (void)lispStoreDoubleArray: (double *)ptr Keyword: (const char *)keyword Rank: (unsigned)rank Dims: (unsigned *)dims Stream: stream
  Lisp save array of doubles, see lispStoreIntegerArray:Keyword:Rank:Dims.

- - (void)lispStoreFloatArray: (float *)ptr Keyword: (const char *)keyword Rank: (unsigned)rank Dims: (unsigned *)dims Stream: stream
  Lisp save array of floats, see lispStoreIntegerArray:Keyword:Rank:Dims.

- - (void)lispStoreUnsignedLongLongArray: (unsigned long long *)ptr Keyword: (const char *)keyword Rank: (unsigned)rank Dims: (unsigned *)dims Stream: stream
  Lisp save array of unsigned long long, see lispStoreIntegerArray:Keyword:Rank:Dims.

- - (void)lispStoreLongLongArray: (long long *)ptr Keyword: (const char *)keyword Rank: (unsigned)rank Dims: (unsigned *)dims Stream: stream
  Lisp save array of long long, see lispStoreIntegerArray:Keyword:Rank:Dims.

- - (void)lispStoreUnsignedLongArray: (unsigned long *)ptr Keyword: (const char *)keyword Rank: (unsigned)rank Dims: (unsigned *)dims Stream: stream
  Lisp save array of unsigned long, see lispStoreIntegerArray:Keyword:Rank:Dims.

- - (void)lispStoreLongArray: (long *)ptr Keyword: (const char *)keyword Rank: (unsigned)rank Dims: (unsigned *)dims Stream: stream
  Lisp save array of long, see lispStoreIntegerArray:Keyword:Rank:Dims.

- - (void)lispStoreUnsignedArray: (unsigned *)ptr Keyword: (const char *)keyword Rank: (unsigned)rank Dims: (unsigned *)dims Stream: stream
  Lisp save array of unsigned integers, see lispStoreIntegerArray:Keyword:Rank:Dims.

- - (void)lispStoreShortArray: (short int *)ptr Keyword: (const char *)keyword Rank: (unsigned)rank Dims: (unsigned *)dims Stream: stream
  Lisp save array of short integers, see lispStoreIntegerArray:Keyword:Rank:Dims.

- - (void)lispStoreCharArray: (char *)ptr Keyword: (const char *)keyword Rank: (unsigned)rank Dims: (unsigned *)dims Stream: stream
  Lisp save array of characters, see lispStoreIntegerArray:Keyword:Rank:Dims.

- - (void)lispStoreBooleanArray: (BOOL *)ptr Keyword: (const char *)keyword Rank: (unsigned)rank Dims: (unsigned *)dims Stream: stream
  Lisp save array of Booleans, see lispStoreIntegerArray:Keyword:Rank:Dims.

- - (void)lispStoreIntegerArray: (int *)ptr Keyword: (const char *)keyword Rank: (unsigned)rank Dims: (unsigned *)dims Stream: stream
  For customized archiving of dynamically allocated arrays within objects. To use this method, override the object's lispOutDeep: method as follows. The array is assumed allocated in one long piece of memory, but it can be treated in segments to make it two dimensional. The number of rows is "rank" and the length of the i'th row is dims[i], thus allowing for a ragged array. In this example, Attribute is a class, culture is a dynamically allocated array of numDims integers, so rank is 1 and a pointer to numDims is passed through for the length of that row.

  Example defobj/Serialization/-lispStoreIntegerArray:Keyword:Rank:Dims:Stream:/1.

       - (void)lispOutDeep: stream
       {
        [stream catStartMakeInstance: "Attribute"];
        [super lispOutVars: stream deep: NO]; //saves all ints, doubles, BOOLs, and static arrays. Saves the values of all other objects as nil
        // Note one can use the previous "lispSaveStream:..." methods to
        // customize the choice of variables to be saved.
        // Now save an array called "culture", which has 1 row
        // and "numDims" columns, onto the stream.
        [super lispStoreIntegerArray: culture Keyword: "culture" Rank: 1 Dims: &numDims Stream: stream];
        [stream catEndMakeInstance];
       }

- - (void)lispSaveStream: stream Double: (const char *)aName Value: (double)val
  On the given stream, save a double valued variable called "aName" which has value "val".

- - (void)lispSaveStream: stream Float: (const char *)aName Value: (double)val
  On the given stream, save a float valued variable called "aName" which has value "val".

- - (void)lispSaveStream: stream UnsignedLongLong: (const char *)aName Value: (unsigned long long)val
  On the given stream, save an unsigned long long variable called "aName" which has value "val".

- - (void)lispSaveStream: stream LongLong: (const char *)aName Value: (long long)val
  On the given stream, save a long long variable called "aName" which has value "val".

- - (void)lispSaveStream: stream UnsignedLong: (const char *)aName Value: (unsigned long)val
  On the given stream, save an unsigned long variable called "aName" which has value "val".

- - (void)lispSaveStream: stream Long: (const char *)aName Value: (long)val
  On the given stream, save a long variables called "aName" which has value "val".

- - (void)lispSaveStream: stream Unsigned: (const char *)aName Value: (unsigned)val
  On the given stream, save an unsigned integer variable called "aName" which has value "val".

- - (void)lispSaveStream: stream Integer: (const char *)aName Value: (int)val
  On the given stream, save an integer variable called "aName" which has value "val".

- - (void)lispSaveStream: stream UnsignedShort: (const char *)aName Value: (unsigned short)val
  On the given stream, save an unsigned short integer variable called "aName" which has value "val".

- - (void)lispSaveStream: stream Short: (const char *)aName Value: (short)val
  On the given stream, save a short integer variable called "aName" which has value "val".

- - (void)lispSaveStream: stream Char: (const char *)aName Value: (char)val
  On the given stream, save a character variable called "aName" which has value "val".

- - (void)lispSaveStream: stream Boolean: (const char *)aName Value: (int)val
  On the given stream, save a Boolean variable called "aName" which has value "val". Explanation: The Swarm lisp serialization approach assumes that objects have lispOutDeep: and lispOutShallow: methods which indicate which variables are supposed to be saved. If an object is subclassed from SwarmObject, there are default lispOutDeep: and lispOutShallow: methods. Those methods employ on the method, lispOutVars:deep:, which is the "default" approach to try to save all variables, either deep or shallow. Sometimes one needs to selectively list particular instance variables to be saved.
  This is necessary, for example, if one wants to save a Swarm itself, because the usage of lispOutVars: will result in a variable "activity" being saved as nil, and so when the saved values are read back in, the "activity" variable will be erased and nil will appear in its place.
  Here is an example of how a subclass called "BFagent" might override lispOutDeep: to customize the selection of variables to be saved. Note that the same could be used to override lispOutShallow:.
  The key thing to remember is that when one tries to do a deep save on a high level object, such as a Swarm, then the Swarm libraries will try to track from top to bottom, finding all collections and objects, and all objects and collections inside them, and so forth, and each will be told to execute its lispOutDeep: method. So all objects you want to save need a lispOutDeep: method, or else the default will try to save all variables. If you omit some objects or variables from your lispOutDeep: method, then they will not appear in the saved file, which is what you want if you want to be sure that pre-existing interited values of variables are not obliterated by bogus saved values.

  Example defobj/Serialization/-lispSaveStream:Boolean:Value:/1.

       - (void)lispOutDeep: stream
       {
        [stream catStartMakeInstance: "BFagent"];
        [self lispSaveStream: stream Double: "demand" Value: demand];
        [self lispSaveStream: stream Double: "profit" Value: profit];
        [self lispSaveStream: stream Double: "wealth" Value: wealth];
        [self lispSaveStream: stream Double: "position" Value: position];
        [self lispSaveStream: stream Double: "cash" Value: cash];
        [self lispSaveStream: stream Double: "price" Value: price];
        [self lispSaveStream: stream Double: "dividend" Value: dividend];
        [self lispSaveStream: stream Integer: "myID" Value: myID];
        [stream catEndMakeInstance];

       }
       An example of such a usage can be found in version 2.4 of the
       Artificial Stock Market (http://ArtStkMkt.sourceforge.net).

- - (void)lispOutVars: stream deep: (BOOL)deepFlag
  Output just key/variable pairs, where variables are serialized deep or shallow per deepFlag.

- - (void)lispOutDeep: stream
  Output a deep Lisp representation of object state to a stream.

- - (void)lispOutShallow: stream
  Output a shallow Lisp representation of object state to a stream.

Prev | Home | Next
RETURNABLE | Up | SetInitialValue