5.4 Serializable C Struct Types
|property|| ||=|| ||#:alignment alignment-expr|
| || ||||| ||#:malloc-mode malloc-mode-expr|
| || ||||| ||#:serialize-inplace|
| || ||||| ||#:deserialize-inplace|
| || ||||| ||#:version vers|
| || ||||| |
|#:other-versions ([other-vers deserialize-chain-expr|
| || ||||| ||#:property prop-expr val-expr|
, but defines a serializable type, with
several changed additional bindings:
make-id — always uses
'atomic allocation, even if #:malloc-mode is
specified (for historical reasons).
make-id/mode — like behaves
like make-id but uses the mode
or allocator specified via malloc-mode-expr (for
deserialize:cstruct:id (for a
vers of 0) or
(for a vers of 1 or more) — deserialization information that is
automatically exported from a deserialize-info submodule.
(for a vers of 0) or
(for a vers of 1 or more) — deserialization
information for use via #:other-versions in other
deserialize:cstruct:id (for an
other-vers of 0) or
(for an other-vers of 1 or more) —
deserialization information that is automatically exported from
a deserialize-info submodule.
Instances of the new type fulfill the serializable? predicate and can
be used with serialize and deserialize. Serialization may
fail if one of the fields contains an arbitrary pointer, an embedded
non-serializable C struct, or a pointer to a non-serializable C struct.
Array-types are supported as long as they don’t contain one of these types.
The default vers is 0, and vers must be a
literal, exact, non-negative integer. An #:other-versions
clause provides deserializers for previous versions of the structure
with the name id, so that previously serialized data can be
deserialized after a change to the declaration of id. For
each other-vers, deserialize-chain-expr should be
the value of a
for some other "other-id" declared with
define-serializable-cstruct that has the same shape that the
previous version of id; the function produced by
convert-proc-expr should convert an instance of
other-id to an instance of id. The functions
produced by unconvert-proc-expr and
cycle-convert-proc-expr are used if a record is involved in a
cycle; the function from unconvert-proc-expr takes an
id instance produced by convert-proc-expr’s function
back to a other-id, while cycle-convert-proc-expr
returns two values: a shell instance of id and function to
accept a filled other-id whose content should be moved to
the shell instance of id.
arguments control the memory allocation
for this type during deserialization and
. It can be one of the mode
arguments to malloc
, or a procedure
that allocates memory of the given size. The default is
When #:serialize-inplace is specified, the serialized
representation shares memory with the C struct object. While being more
efficient, especially for large objects, changes to the object after
serialization may lead to changes in the serialized representation.
A #:deserialize-inplace option reuses the memory of the serialized
representation, if possible. This option is more efficient for large objects,
but it may fall back to allocation via malloc-mode-expr for cyclic
structures. As the allocation mode of the serialized representation
will be 'atomic by default or may be arbitrary if
#:serialize-inplace is specified, inplace deserialisation
should be used with caution whenever the object contains pointers.
When the C struct contains pointers, it is advisable to use a custom
allocator. It should be based on a non-moving-memory allocation like
'raw, potentially with manual freeing to avoid memory leaks
after garbage collection.
Changed in version 1.1 of package serialize-cstruct-lib: Added #:version and #:other-versions.