ObjectSerialization

Usage

use ObjectSerialization;

or

import ObjectSerialization;

Warning

The ObjectSerialization module is unstable. The module’s name, its types, and serialization format are subject to change.

The ObjectSerialization module provides an objectSerializer and objectDeserializer that implement a simple binary IO format.

record objectSerializer

A binary Serializer that implements a simple binary format.

This Serializer supports an endian field which may be configured at execution time.

See the serializers technote for a general overview of Serializers and their usage.

const endian : endianness = endianness.native

‘endian’ represents the endianness of the binary output produced by this Serializer.

proc ref serializeValue(writer: fileWriter(serializerType = objectSerializer, locking = false, ?), const val: ?t) throws

Serialize val with writer.

Numeric values like integers, real numbers, and complex numbers are serialized directly to the associated fileWriter as binary data in the specified endianness.

Booleans are serialized as single byte unsigned values of either 0 or 1.

string values are serialized beginning with a length represented by a variable-length byte scheme (which is always the same no matter what endianness). In this scheme, the high bit of each encoded length byte records whether or not there are more length bytes (and the remaining bits encode the length in a big-endian manner). Then, the raw binary data of the string is written to the writer.

The nil value is serialized as a single unsigned byte of value 0.

Classes are serialized beginning with a single unsigned byte of either 0 or 1 indicating nil. Nilable classes that are nil will always serialize as 0, and non-nilable classes will always begin serializing as 1.

Classes and records will have their serialize method invoked, passing in writer and this Serializer as arguments. Please see the serializers technote for more on the serialize method.

Classes and records are expected to implement the writeSerializable interface. The serializable interface is also acceptable.

Note

Serializing and deserializing enums is not stable in this format.

Arguments:

• writer – The fileWriter used to write serialized output.

• val – The value to be serialized.

proc startClass(writer: fileWriter(?), name: string, size: int) throws

Start serializing a class and return a new AggregateSerializer.

Arguments:

• writer – The fileWriter to be used when serializing.

• name – The name of the class type.

• size – The number of fields in the class.

Returns:

A new AggregateSerializer

proc startRecord(writer: fileWriter(?), name: string, size: int) throws

Start serializing a record and return a new AggregateSerializer.

Arguments:

• writer – The fileWriter to be used when serializing.

• name – The name of the record type.

• size – The number of fields in the class.

Returns:

A new AggregateSerializer

record AggregateSerializer

Returned by startClass or startRecord to provide the API for serializing classes or records.

In this simple binary format, classes and records do not begin or end with any bytes indicating size, and instead serialize their field values in objectSerializer’s format.

For example, a record with two uint(8) fields with values 1 and 2 would be serialized as 0x01 followed by 0x02 (in raw binary).

proc writeField(name: string, const field: ?T) throws

Serialize field in objectSerializer’s format.

proc startClass(writer, name: string, size: int) throws

Start serializing a nested class inside the current class. In this binary format, this has no impact on the serialized output.

proc endClass() throws

End deserialization of this class.

proc endRecord() throws

End deserialization of this record.

proc startTuple(writer: fileWriter(?), size: int) throws

Start serializing a tuple and return a new TupleSerializer.

Arguments:

• writer – The fileWriter to be used when serializing.

• size – The number of elements in the tuple.

Returns:

A new TupleSerializer

record TupleSerializer

Returned by startTuple to provide the API for serializing tuples.

In this simple binary format, tuples do not begin or end with any bytes indicating size, and instead serialize their elements sequentially in objectSerializer’s format.

proc writeElement(const element: ?T) throws

Serialize element in objectSerializer’s format.

proc endTuple() throws

Ends serialization of the current tuple.

proc startList(writer: fileWriter(?), size: int) throws

Start serializing a list by serializing size.

Arguments:

• writer – The fileWriter to be used when serializing.

• size – The number of elements in the list.

Returns:

A new ListSerializer

record ListSerializer

Returned by startList to provide the API for serializing lists.

In this simple binary format, lists begin with the serialization of an int representing the size of the list. This data is then followed by the binary serialization of the specified number of elements.

proc writeElement(const element: ?) throws

Serialize element in objectSerializer’s format.

proc endList() throws

Ends serialization of the current list.

proc startArray(writer: fileWriter(?), size: int) throws

Start serializing an array and return a new ArraySerializer.

Arguments:

• writer – The fileWriter to be used when serializing.

• size – The number of elements in the array.

Returns:

A new ArraySerializer

record ArraySerializer

Returned by startArray to provide the API for serializing arrays.

In this simple binary format, arrays are serialized element by element in the order indicated by the caller of writeElement. Dimensions and the start or end of the array are not represented.

proc startDim(size: int) throws

Start serializing a new dimension of the array.

proc endDim() throws

Ends serialization of this dimension.

proc writeElement(const element: ?) throws

Serialize element in objectSerializer’s format.

proc writeBulkElements(data: c_ptr(?eltType), numElements: int) throws  where isNumericType(eltType)

Serialize numElements number of elements in data, provided that the element type of data is a numeric type.

This performance-motivated implementation of the optional writeBulkElements will write the elements of data in the order in which they are represented in memory.

Note

This method is only optimized for the case where the objectSerializer has been configured for native endianness.

proc endArray() throws

Ends serialization of the current array.

proc startMap(writer: fileWriter(?), size: int) throws

Start serializing a map by serializing size.

Arguments:

• writer – The fileWriter to be used when serializing.

• size – The number of entries in the map.

Returns:

A new MapSerializer

record MapSerializer

Returned by startMap to provide the API for serializing maps.

In this simple binary format, maps begin with the serialization of an int representing the size of the map. This data is then followed by the binary serialization of the specified number of key-value pairs. The binary serialization of a key-value pair has no structure, and simply consists of the serialization of the key followed by the serialization of the value.

proc writeKey(const key: ?) throws

Serialize key in objectSerializer’s format.

proc writeValue(const val: ?) throws

Serialize val in objectSerializer’s format.

proc endMap() throws

Ends serialization of the current map.

record objectDeserializer

A binary Deserializer that implements a simple binary format.

This Deserializer supports an endian field which may be configured at execution time.

See the serializers technote for a general overview of Deserializers and their usage.

Otherwise, please refer to objectSerializer for a description of the binary format. Individual methods on this type may clarify relevant behavior specific to deserialization

const endian : IO.endianness = IO.endianness.native

‘endian’ represents the endianness that this Deserializer should use when deserializing input.

proc ref deserializeType(reader: fileReader(?), type readType) : readType throws

Deserialize type readType with reader.

Classes and records will be deserialized using an appropriate initializer, passing in reader and this Deserializer as arguments. If an initializer is unavailable, this method may invoke the class or record’s deserialize method. Please see the serializers technote for more.

Classes and records are expected to implement either the initDeserializable or readDeserializable interfaces (or both). The serializable interface is also acceptable.

Arguments:

• reader – The fileReader from which types are deserialized.

• readType – The type to be deserialized.

Returns:

A value of type readType.

proc ref deserializeValue(reader: fileReader(?), ref val: ?readType) : void throws

Deserialize from reader directly into val.

Like deserializeType, but reads into an initialized value rather than creating a new value. For classes and records, this method will first attempt to invoke a deserialize method. If the deserialize method is unavailable, this method may fall back on invoking a suitable initializer and assigning the resulting value into val.. Please see the serializers technote for more.

Classes and records are expected to implement either the readDeserializable or initDeserializable interfaces (or both). The serializable interface is also acceptable.

Arguments:

• reader – The fileReader from which values are deserialized.

• val – The value into which this Deserializer will deserialize.

proc startClass(reader: fileReader(?), name: string) throws

Start deserializing a class by returning an AggregateDeserializer.

Arguments:

• reader – The fileReader to use when deserializing.

• name – The name of the class type.

Returns:

A new AggregateDeserializer

proc startRecord(reader: fileReader(?), name: string) throws

Start deserializing a record by returning an AggregateDeserializer.

Arguments:

• reader – The fileReader to use when deserializing.

• name – The name of the record type.

Returns:

A new AggregateDeserializer

record AggregateDeserializer

Returned by startClass or startRecord to provide the API for deserializing classes or records.

See objectSerializer.AggregateSerializer for details of the binary format for classes and records.

proc readField(name: string, type fieldType) : fieldType throws

Deserialize and return a value of type fieldType.

proc readField(name: string, ref field) throws

Deserialize field in-place.

proc startClass(reader, name: string) throws

Start deserializing a nested class inside the current class.

See objectSerializer.AggregateSerializer.startClass for details on inheritance on the binary format.

Returns:

A new AggregateDeserializer

proc endClass() throws

End deserialization of the current class.

proc endRecord() throws

End deserialization of the current record.

proc startTuple(reader: fileReader(?)) throws

Start deserializing a tuple by returning a TupleDeserializer.

Arguments:

reader – The fileReader to use when deserializing.

Returns:

A new TupleDeserializer

record TupleDeserializer

Returned by startTuple to provide the API for deserializing tuples.

See objectSerializer.TupleSerializer for details of the binary format for tuples.

proc readElement(type eltType) : eltType throws

Deserialize an element of the tuple.

Returns:

A deserialized value of type eltType.

proc readElement(ref element) throws

Deserialize element in-place as an element of the tuple.

proc endTuple() throws

End deserialization of the current tuple.

proc startList(reader: fileReader(?)) throws

Start deserializing a list by returning a ListDeserializer.

Arguments:

reader – The fileReader to use when deserializing.

Returns:

A new ListDeserializer

record ListDeserializer

Returned by startList to provide the API for deserializing lists.

See objectSerializer.ListSerializer for details of the binary format for lists.

proc ref readElement(type eltType) : eltType throws

Deserialize an element of the list.

Returns:

A deserialized value of type eltType.

proc ref readElement(ref element) throws

Deserialize element in-place as an element of the list.

proc endList() throws

End deserialization of the current list.

Throws:

A BadFormatError if there are remaining elements.

proc hasMore() : bool throws

Returns:

Returns true if there are more elements to read.

proc startArray(reader: fileReader(?)) throws

Start deserializing an array by returning an ArrayDeserializer.

Arguments:

reader – The fileReader to use when deserializing.

Returns:

A new ArrayDeserializer

record ArrayDeserializer

Returned by startArray to provide the API for deserializing arrays.

See objectSerializer.ArraySerializer for details of the binary format for arrays.

proc startDim() throws

Inform the ArrayDeserializer to start deserializing a new dimension.

proc endDim() throws

End deserialization of the current dimension.

proc readElement(type eltType) : eltType throws

Deserialize an element of the list.

Returns:

A deserialized value of type eltType.

proc readElement(ref element) throws

Deserialize element in-place as an element of the array.

proc readBulkElements(data: c_ptr(?eltType), numElements: int) throws  where isNumericType(eltType)

Deserialize numElements number of elements into data, provided that the element type of data is a numeric type.

This performance-motivated implementation of the optional readBulkElements will read the elements of data in the order in which they are represented in memory.

Note

This method is only optimized for the case where the objectDeserializer has been configured for native endianness.

proc endArray() throws

End deserialization of the current array.

proc startMap(reader: fileReader(?)) throws

Start deserializing a map by returning a MapDeserializer.

Arguments:

reader – The fileReader to use when deserializing.

Returns:

A new MapDeserializer

record MapDeserializer

Returned by startMap to provide the API for deserializing maps.

See objectSerializer.MapSerializer for details of the binary format for map.

proc ref readKey(type keyType) : keyType throws

Deserialize and return a key of type keyType.

proc ref readKey(ref key) throws

Deserialize key in-place as a key of the map.

proc readValue(type valType) : valType throws

Deserialize and return a value of type valType.

proc readValue(ref value) throws

Deserialize value in-place as a value of the map.

proc endMap() throws

End deserialization of the current map.

Throws:

A BadFormatError if there are entries remaining.

proc hasMore() : bool throws

Returns:

Returns true if there are more elements to read.

Warning

Behavior of ‘hasMore’ is undefined when called between readKey and readValue.