SerializationProtocol¶

• SerializationProtocol
  • Introduction
  • packed-size
  • pack
  • unpack
  • location
  • extract

Introduction¶

Serialization-related operations are based on a generic serialization protocol. The protocol consist of the following operations

• [packed-size]
• pack
• unpack
• [location]
• [extract]

In this conceptual description, all protocol operations expect a serialization mechanism as their first argument. Most concrete implementations of this protocol will solve disambiguation of mechanisms differently, for example by incorporating the mechanism name into function names (e.g. unpack_as_protobuf()), by using template specializations (e.g. unpack<protobuf_tag>()) or namespaces (e.g. protobuf::unpack()).

See source:code/cl-rosetta/trunk/src/serialization/protocol.lisp for an implementation of this protocol.

packed-size¶

packed-sized(mechanism, datum) => required
optional operation
Return the amount of storage required to hold the serialized representation of datum when serialized using mechanism.

Example:
Assuming a-notification is an instance of a data-holder class for the protocol buffer message rsb.protocol.Notification defined here.

packed-size(protobuf, a-notification) => 40

This would indicate that 40 bytes of storage are required to serialize a-notification when using the protocol buffer serialization mechanism.

pack¶

pack(mechanism, datum, destination) => produced, destination
mandatory operation
Store a serialized representation using mechanism of datum in destination. Return the amount of produced data and the, likely modified, destination.

unpack¶

unpack(mechanism, source, datum) => datum, consumed
mandatory operation
Restore datum from the serialized representation in source using mechanism. Return the restored datum and the amount of consumed data.

location¶

location(mechanism, source, schema, part) => maybe(location)
optional operation
Return the location in source at which part of schema is stored using mechanism. If part of schema is not stored in source, return nothing.

Example:
Assuming a-buffer is an array of bytes containing a serialized representation of the a-notification instance mentioned above.

location(protobuf, a-buffer, rsb.protocol.Notification, rsb.protocol.Notification.meta_data) => 18

This would indicate that the meta_data field of the rsb.protocol.Notification message is present in a-buffer and stored at offset 18.

extract¶

extract(mechanism, source, schema, part) => maybe(datum)
optional operation
Return part of schema restored from source using mechanism. If part of schema is not stored in source, return nothing.