Data Marshalling

 

In C++ -with-Ease all data that is passed as parameters to processes, or passed through contexts must have appropriate marshalling functions. These functions convert the data to and from a binary stream.

xxx Further discuss the marshalling mechanism.

The C-with-Ease implementation uses the default marshalling functions, which simply do a binary copy of the data structure. This, however, does not allow for passing of variable sized objects (such as strings), or passing between machines with different architectures (although the current implementation does not support this directly).

Marshalling is acheived through the use of the classes mStream and umStream, which marshal and unmarshal data respectively.

The global functions:

mStream & operator<< (mStream & s, T const &v);
umStream& operator>> (umStream& s, T &v);

must be defined for each type T used in context operations and passed as parameters to functions.

xxx Discuss the problems with templates separately. These confuse things and are ugly. Remove it from around here.

To facilitate generation of these functions in simple cases (for types where a binary copy of the object will suffice), templated versions of these functions exist. However, due to problems with automatic template instatiation in the presence of specializations you must instantiate these templates yourself. A macro is provided to do this for you:

useDefaultMarshal(T);

Contexts require special marshalling operators, these must be generated using the macro:

useCtxMarshal(T);

Where T is a context type (which may be a typedef'd identifier).

Types which require custom marshalling functions should also use the macro:

useCustomMarshal(T);

This emits a function needsMarshal(T &) which informs the runtime system to use the marshalling functions.

The mStream class

The important public interface members of the mStream class are:

class mStream {
public:
   void add(const void *ptr, unsigned long size);
};

The add function adds some binary data to the stream.

The umStream class

The important public interface members of the umStream class are:

class umStream {
public:
   void remove(void *ptr, unsigned long size);
};

The remove function removes some binary data from the stream.