Serializables

Serializable is a wrapper class used for serializing and deserializing C++ objects that will be used in conjunction with the C++ DDict client or the C++ Queue. Additionally, several more specific classes may be used for both Queues and DDicts. The Serializable class definitions are provided here along with a few typedefs/using definitions for common instances of Serializables.

The DerivedSerializable documentation provides an example to be used when writing your own subclasses of SerializableBase or any of the other classes.

template<class Type>
class DerivedSerializable : public dragon::SerializableBase

This class provides the outline of what a subclass of Serializable should look like.

Use this documentation as an outline for writing your own subclasses of Serializable. DO NOT instantiate this class and expect it to do anything.

Public Functions

inline DerivedSerializable(Type obj)

Constructor for DerivedSerializable.

Write your own subclass of Serializable and a constructor for it. You may pass multiple arguments. The constructor is for your own program’s use and is not used by Dragon.

Parameters:

x – A Type of object to wrap.

inline virtual void serialize(dragonFLISendHandleDescr_t *sendh, uint64_t arg, const bool buffer, const timespec_t *timeout) const

Serialize a C++ object.

This method should be overridden in the implementing derived subclass. It should write the bytes of the serialized object to the FLI send handle using the FLI send_bytes interface defined in fli.h. The arg argument should simply be passed through from the serialize function call to the FLI API call for sending bytes. The buffer argument should typically just be passed through to FLI send_byte operations. It will be determined by the context in which serialize is called. For DDict keys, the writes are buffered. For DDict values, the writes are not. But in some cases you may wish to buffer serialized objects and specify true to cause the writes to be consilidated into one network communication.

Parameters:

• sendh – is an FLI send handle used for writing

• arg – is a provided hint. You may override this in some circumstances to create your own hint.

• buffer – is provided or you can override. A value of true on FLI sends will cause written data to be consolidated into one network transfer. The arg is written through to the receiver only when buffer is false.

• timeout – A value of nullptr will wait forever to serialize/transfer data. If value of {0,0} will try once. Otherwise, the timeout specifies how long to wait for the serialization/transfer to be completed.

inline Type getVal() const

Get the wrapped value for the object.

This method may be named whatever you like. It is not part of the SerializableBase class. And you may define more than one accessor method like this to retrieve parts of your object. You will need something like this to access your deserialized object in your program. The wrapped value (i.e. Type) may also be more than one value which would then be passed to the constructor and you would then have multiple accessor methods to get the various pieces out after deserialization.

Returns:

A value.

inline virtual int type_id() const

Return a unique type id for this type.

This method should return a unique integer to be used to identify this type. The SerializableType enum can provide these values. The return type is left as int to facilitate subclassing and returning your own type values.

Returns:

A unique type id.

Public Static Functions

static inline DerivedSerializable<Type> deserialize(dragonFLIRecvHandleDescr_t *recvh, uint64_t *arg, const timespec_t *timeout)

Deserialize a serialized C++ object.

This method should be written in the implementing derived subclass and should return the derived subtype of SerializableBase. It may throw a DragonError exception when a byte stream is not deserializable. It should throw a EmptyError when EOT is received while reading bytes as it deserializes a value. Assuming that the deserialization succeeds, the deserialize method should return a deserialized value of the derived type after it has read the serialized object’s bytes. The arg argument should be passed through to the FLI API calls for reading bytes or pool memory and will be set according to what was sent when it was serialized. This function relies on NRVO in C++17 and above. This optimization means that the object is initialized in the caller’s space so when the value is returned, it is already in-place. This means we can return a value without making an extra copy.

Parameters:

• recvh – An FLI receive handle. The receive handle is used to read the data of the object. You can read the data using any FLI recvh methods.

• arg – A pointer to a variable to hold the received arg value.

• timeout – A value of nullptr will wait forever. A value of {0,0} will try once. Otherwise, wait for the specified time to receive the object.

Returns:

A DerivedSerializable instance.

class Serializable : public dragon::SerializableBase

The Serializable class can be used to encompass any of the pre-defined Serializable types, providing a means to communicate any Serializable over a Dragon FLI, in particular Queues and DDicts.

The Serializable class wraps objects of other types allowing for them to be safely shared over and FLI connection and understood at the other end by the receiver when they are deserialized. All the pre-defined types are safely wrapped and unwrapped into/from the Serializable class as needed.

class SerializableString : public dragon::SerializableBase

A Serializable string class.

The class provides the Serializable interface for strings.

Public Functions

SerializableString(std::string x)

Constructor for Serializable Strings.

This provides a wrapper class for string values that need to be serialized/deserialized in a Dragon program.

Parameters:

x – An string value to wrap.

virtual void serialize(dragonFLISendHandleDescr_t *sendh, uint64_t arg, const bool buffer, const timespec_t *timeout) const

See the DerivedSerializable serialize description.

std::string getVal() const

Get the wrapped value for the object.

Returns:

The wrapped value.

virtual int type_id() const

See the DerivedSerializable type_id description.

Public Static Functions

static SerializableString deserialize(dragonFLIRecvHandleDescr_t *recvh, uint64_t *arg, const timespec_t *timeout)

See the DerivedSerializable deserialize description.

template<class Type, int TVal>
class SerializableScalar : public dragon::SerializableBase

A SerializableScalar class.

The class provides the Serializable interface for all Scalar types in C++. There are two pre-defined types provided as instances of this template: SerializableInt and SerializableDouble. Users can define additional SerializableScalars by creating additional instances of this template.

Public Functions

inline SerializableScalar(Type x)

Constructor for SerializableScalar.

This provides a wrapper class for Type values that need to be serialized/deserialized in a Dragon program.

Parameters:

x – An double value to wrap.

inline SerializableScalar()

Constructor for SerializableScalar.

Default constructor.

inline virtual void serialize(dragonFLISendHandleDescr_t *sendh, uint64_t arg, const bool buffer, const timespec_t *timeout) const

See the DerivedSerializable serialize description.

inline Type getVal() const

Get the wrapped value for the object.

Returns:

The wrapped value.

inline virtual int type_id() const

See the DerivedSerializable type_id description.

Public Static Functions

static inline SerializableScalar deserialize(dragonFLIRecvHandleDescr_t *recvh, uint64_t *arg, const timespec_t *timeout)

See the DerivedSerializable deserialize description.

template<class Type, int TVal>
class SerializableVector : public dragon::SerializableBase

A Serializable Vector of Type.

The class provides the Serializable interface for all vector types in Dragon C++ code. There are two pre-defined types provided as instances of this template: SerializableIntVector and SerializableDoubleVector. Users can define additional SerializableVectors by creating additional instances of this template.

Public Functions

inline SerializableVector(std::vector<Type> obj)

Constructor for Serializable Vector of Type.

This provides a wrapper class for a vector of Type values that need to be serialized/deserialized in a Dragon program.

Parameters:

vec – A Type vector value to wrap.

inline SerializableVector(size_t size)

Constructor for Serializable Vector of Type.

Contruct an empty serializable Type vector with size elements.

Parameters:

size – The number of elements for the empty vector.

inline virtual void serialize(dragonFLISendHandleDescr_t *sendh, uint64_t arg, const bool buffer, const timespec_t *timeout) const

See the DerivedSerializable serialize description.

inline std::vector<Type> getVal() const

Get the wrapped value for the object.

Returns:

The wrapped value.

inline virtual int type_id() const

See the DerivedSerializable type_id description.

Public Static Functions

static inline SerializableVector<Type, TVal> deserialize(dragonFLIRecvHandleDescr_t *recvh, uint64_t *arg, const timespec_t *timeout)

See the DerivedSerializable deserialize description.

template<class Type, int TVal>
class Serializable2DMatrix : public dragon::SerializableBase

A Serializable 2D Matrix of Type.

The class provides the Serializable interface for all Matrix types in Dragon C++ code. There are two pre-defined types provided as instances of this template: Serializable2DIntMatrix and Serializable2DDoubleMatrix. Users can define additional Serializable2DMatrices by creating additional instances of this template.

Public Functions

inline Serializable2DMatrix(std::vector<std::vector<Type>> obj)

Constructor for Serializable Vector of Type.

This provides a wrapper class for a vector of Type values that need to be serialized/deserialized in a Dragon program.

Parameters:

vec – A Type vector value to wrap.

inline Serializable2DMatrix(size_t rows, size_t cols)

Constructor for Serializable Vector of Type.

Contruct an empty serializable Type vector with size elements.

Parameters:

• rows – The number of rows for the empty matrix.

• cols – The number of columns for the empty matrix.

inline virtual void serialize(dragonFLISendHandleDescr_t *sendh, uint64_t arg, const bool buffer, const timespec_t *timeout) const

See the DerivedSerializable serialize description.

inline std::vector<std::vector<Type>> getVal() const

Get the wrapped value for the object.

Returns:

The wrapped value.

inline virtual int type_id() const

See the DerivedSerializable type_id description.

Public Static Functions

static inline Serializable2DMatrix<Type, TVal> deserialize(dragonFLIRecvHandleDescr_t *recvh, uint64_t *arg, const timespec_t *timeout)

See the DerivedSerializable deserialize description.