Crate ab_io_type 

Infrastructure for zero-cost zero-copy serialization/deserialization.

This crate only supports little-endian platforms by design.

This crate primarily offers the following:

• TrivialType trait
• IoType trait
• metadata describing types implementing the above traits (see IoTypeMetadataKind)

TrivialType

This trait is implemented for a bunch of built-in types and can be derived for custom types that contain them (structs and enums). It represents trivial types, which do not contain uninitialized bytes and are fully represented by their byte representation.

What this means is that serialization to bytes can be done by simply casting a pointer to a data structure to an array of bytes. Similarly, deserialization parses bytes, checking that they are a valid value of the type, which for types that accept every bit pattern compiles to a length check, and then casts the pointer. The trait provides a few helper methods for dealing with serialization/deserialization.

IoType

This trait is implemented for all types that implement TrivialType and for a few additional custom types that have special properties and are useful for FFI purposes.

IoType data structures can contain optional values or lists of values of a dynamic size. They are not as composable as TrivialType and are usually used as wrappers of the highest level. This is in contrast to TrivialType that is always fixed size and can’t have optional data.

Metadata

The data structures implementing TrivialType and IoType traits have the METADATA associated constant (see IoTypeMetadataKind). This field contains a compact binary representation of the recursive layout of the type, which can then be decoded by the machine for FFI purposes or converted into human-readable format for presentation to the user in a somewhat readable way.

The metadata contains both the memory layout and the names of data structures and fields. Metadata can also be compressed into an equivalent layout without names and with newtypes replaced by the types they wrap to shrink the size of the metadata further when human readability is not necessary. Compressed metadata can also be hashed to get a “fingerprint” of the data structure, which may be used to distinguish a compatible FFI interface from an incompatible one based on the data layout, not just the number of bytes.

Overall

These traits are designed for zero-cost zero-copy serialization/deserialization. Correctly aligned memory (both normal and memory-mapped files with mmap) is used in place as ready-to-use data structures after parsing, which for types that accept every bit pattern is a length check that doesn’t read the memory.

Does not require a standard library (no_std) or an allocator.

Modules

alignment

Alignment of a type or value, in its own module so that only its constructors can create it

fixed_capacity_bytes

fixed_capacity_elements

fixed_capacity_string

maybe_data

metadata

trivial_type

unaligned

variable_bytes

variable_elements

Traits

IoType

Trait that is used for types that are crossing the host/guest boundary in contracts.

IoTypeMut

Exclusive access to an IoType value.

IoTypeOptional

Marker trait, companion to IoType that indicates the ability to store optional contents.