.. default-domain:: chpl .. module:: ObjectSerialization :synopsis: The ObjectSerialization module provides an objectSerializer and ObjectSerialization =================== **Usage** .. code-block:: chapel use ObjectSerialization; or .. code-block:: chapel 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 :ref:`the serializers technote` for a general overview of Serializers and their usage. .. attribute:: const endian: endianness = endianness.native 'endian' represents the endianness of the binary output produced by this Serializer. .. method:: 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 :ref:`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. :arg writer: The ``fileWriter`` used to write serialized output. :arg val: The value to be serialized. .. method:: proc startClass(writer: fileWriter(?), name: string, size: int) throws Start serializing a class and return a new ``AggregateSerializer``. :arg writer: The ``fileWriter`` to be used when serializing. :arg name: The name of the class type. :arg size: The number of fields in the class. :returns: A new :type:`AggregateSerializer` .. method:: proc startRecord(writer: fileWriter(?), name: string, size: int) throws Start serializing a record and return a new ``AggregateSerializer``. :arg writer: The ``fileWriter`` to be used when serializing. :arg name: The name of the record type. :arg size: The number of fields in the class. :returns: A new :type:`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). .. method:: proc writeField(name: string, const field: ?T) throws Serialize ``field`` in ``objectSerializer``'s format. .. method:: 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. .. method:: proc endClass() throws End deserialization of this class. .. method:: proc endRecord() throws End deserialization of this record. .. method:: proc startTuple(writer: fileWriter(?), size: int) throws Start serializing a tuple and return a new ``TupleSerializer``. :arg writer: The ``fileWriter`` to be used when serializing. :arg 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. .. method:: proc writeElement(const element: ?T) throws Serialize ``element`` in ``objectSerializer``'s format. .. method:: proc endTuple() throws Ends serialization of the current tuple. .. method:: proc startList(writer: fileWriter(?), size: int) throws Start serializing a list by serializing ``size``. :arg writer: The ``fileWriter`` to be used when serializing. :arg 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. .. method:: proc writeElement(const element: ?) throws Serialize ``element`` in ``objectSerializer``'s format. .. method:: proc endList() throws Ends serialization of the current list. .. method:: proc startArray(writer: fileWriter(?), size: int) throws Start serializing an array and return a new ``ArraySerializer``. :arg writer: The ``fileWriter`` to be used when serializing. :arg 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. .. method:: proc startDim(size: int) throws Start serializing a new dimension of the array. .. method:: proc endDim() throws Ends serialization of this dimension. .. method:: proc writeElement(const element: ?) throws Serialize ``element`` in ``objectSerializer``'s format. .. method:: 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. .. method:: proc endArray() throws Ends serialization of the current array. .. method:: proc startMap(writer: fileWriter(?), size: int) throws Start serializing a map by serializing ``size``. :arg writer: The ``fileWriter`` to be used when serializing. :arg 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. .. method:: proc writeKey(const key: ?) throws Serialize ``key`` in ``objectSerializer``'s format. .. method:: proc writeValue(const val: ?) throws Serialize ``val`` in ``objectSerializer``'s format. .. method:: 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 :ref:`the serializers technote` for a general overview of Deserializers and their usage. Otherwise, please refer to :type:`objectSerializer` for a description of the binary format. Individual methods on this type may clarify relevant behavior specific to deserialization .. attribute:: const endian: IO.endianness = IO.endianness.native 'endian' represents the endianness that this Deserializer should use when deserializing input. .. method:: 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 :ref:`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. :arg reader: The ``fileReader`` from which types are deserialized. :arg readType: The type to be deserialized. :returns: A value of type ``readType``. .. method:: proc ref deserializeValue(reader: fileReader(?), ref val: ?readType): void throws Deserialize from ``reader`` directly into ``val``. Like :proc:`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 :ref:`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. :arg reader: The ``fileReader`` from which values are deserialized. :arg val: The value into which this Deserializer will deserialize. .. method:: proc startClass(reader: fileReader(?), name: string) throws Start deserializing a class by returning an ``AggregateDeserializer``. :arg reader: The ``fileReader`` to use when deserializing. :arg name: The name of the class type. :returns: A new :type:`AggregateDeserializer` .. method:: proc startRecord(reader: fileReader(?), name: string) throws Start deserializing a record by returning an ``AggregateDeserializer``. :arg reader: The ``fileReader`` to use when deserializing. :arg name: The name of the record type. :returns: A new :type:`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. .. method:: proc readField(name: string, type fieldType): fieldType throws Deserialize and return a value of type ``fieldType``. .. method:: proc readField(name: string, ref field) throws Deserialize ``field`` in-place. .. method:: 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 .. method:: proc endClass() throws End deserialization of the current class. .. method:: proc endRecord() throws End deserialization of the current record. .. method:: proc startTuple(reader: fileReader(?)) throws Start deserializing a tuple by returning a ``TupleDeserializer``. :arg reader: The ``fileReader`` to use when deserializing. :returns: A new :type:`TupleDeserializer` .. record:: TupleDeserializer Returned by ``startTuple`` to provide the API for deserializing tuples. See ``objectSerializer.TupleSerializer`` for details of the binary format for tuples. .. method:: proc readElement(type eltType): eltType throws Deserialize an element of the tuple. :returns: A deserialized value of type ``eltType``. .. method:: proc readElement(ref element) throws Deserialize ``element`` in-place as an element of the tuple. .. method:: proc endTuple() throws End deserialization of the current tuple. .. method:: proc startList(reader: fileReader(?)) throws Start deserializing a list by returning a ``ListDeserializer``. :arg reader: The ``fileReader`` to use when deserializing. :returns: A new :type:`ListDeserializer` .. record:: ListDeserializer Returned by ``startList`` to provide the API for deserializing lists. See ``objectSerializer.ListSerializer`` for details of the binary format for lists. .. method:: proc ref readElement(type eltType): eltType throws Deserialize an element of the list. :returns: A deserialized value of type ``eltType``. .. method:: proc ref readElement(ref element) throws Deserialize ``element`` in-place as an element of the list. .. method:: proc endList() throws End deserialization of the current list. :throws: A ``BadFormatError`` if there are remaining elements. .. method:: proc hasMore(): bool throws :returns: Returns ``true`` if there are more elements to read. .. method:: proc startArray(reader: fileReader(?)) throws Start deserializing an array by returning an ``ArrayDeserializer``. :arg reader: The ``fileReader`` to use when deserializing. :returns: A new :type:`ArrayDeserializer` .. record:: ArrayDeserializer Returned by ``startArray`` to provide the API for deserializing arrays. See ``objectSerializer.ArraySerializer`` for details of the binary format for arrays. .. method:: proc startDim() throws Inform the ``ArrayDeserializer`` to start deserializing a new dimension. .. method:: proc endDim() throws End deserialization of the current dimension. .. method:: proc readElement(type eltType): eltType throws Deserialize an element of the list. :returns: A deserialized value of type ``eltType``. .. method:: proc readElement(ref element) throws Deserialize ``element`` in-place as an element of the array. .. method:: 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. .. method:: proc endArray() throws End deserialization of the current array. .. method:: proc startMap(reader: fileReader(?)) throws Start deserializing a map by returning a ``MapDeserializer``. :arg reader: The ``fileReader`` to use when deserializing. :returns: A new :type:`MapDeserializer` .. record:: MapDeserializer Returned by ``startMap`` to provide the API for deserializing maps. See ``objectSerializer.MapSerializer`` for details of the binary format for map. .. method:: proc ref readKey(type keyType): keyType throws Deserialize and return a key of type ``keyType``. .. method:: proc ref readKey(ref key) throws Deserialize ``key`` in-place as a key of the map. .. method:: proc readValue(type valType): valType throws Deserialize and return a value of type ``valType``. .. method:: proc readValue(ref value) throws Deserialize ``value`` in-place as a value of the map. .. method:: proc endMap() throws End deserialization of the current map. :throws: A ``BadFormatError`` if there are entries remaining. .. method:: 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``.