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.
Provides serialization for Chapel data types in a binary format.
Intended for use with IO support for serializers and deserializers.
- 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
withwriter
.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
or1
.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 thewriter
.The
nil
value is serialized as a single unsigned byte of value0
.Classes are serialized beginning with a single unsigned byte of either
0
or1
indicatingnil
. Nilable classes that arenil
will always serialize as0
, and non-nilable classes will always begin serializing as1
.Classes and records will have their
serialize
method invoked, passing inwriter
and this Serializer as arguments. Please see the serializers technote for more on theserialize
method.Classes and records are expected to implement the
writeSerializable
interface. Theserializable
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
orstartRecord
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 values1
and2
would be serialized as0x01
followed by0x02
(in raw binary).- proc writeField(name: string, const field: ?T) throws¶
Serialize
field
inobjectSerializer
’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
inobjectSerializer
’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
inobjectSerializer
’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
inobjectSerializer
’s format.- proc writeBulkElements(data: c_ptr(?eltType), numElements: int) throws where isNumericType(eltType)¶
Serialize
numElements
number of elements indata
, provided that the element type ofdata
is a numeric type.This performance-motivated implementation of the optional
writeBulkElements
will write the elements ofdata
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 fornative
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
inobjectSerializer
’s format.- proc writeValue(const val: ?) throws¶
Serialize
val
inobjectSerializer
’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
withreader
.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’sdeserialize
method. Please see the serializers technote for more.Classes and records are expected to implement either the
initDeserializable
orreadDeserializable
interfaces (or both). Theserializable
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 intoval
.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 adeserialize
method. If thedeserialize
method is unavailable, this method may fall back on invoking a suitable initializer and assigning the resulting value intoval
.. Please see the serializers technote for more.Classes and records are expected to implement either the
readDeserializable
orinitDeserializable
interfaces (or both). Theserializable
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
orstartRecord
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 intodata
, provided that the element type ofdata
is a numeric type.This performance-motivated implementation of the optional
readBulkElements
will read the elements ofdata
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 fornative
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
andreadValue
.