abomonation 0.4.4

A high performance and very unsafe serialization library

Crate abomonation [] [src]

Abomonation (spelling intentional) is a fast serialization / deserialization crate.

Abomonation takes typed elements and simply writes their contents as binary. It then gives the element the opportunity to serialize more data, which is useful for types with owned memory such as String and Vec. The result is effectively a copy of reachable memory, where pointers are zero-ed out and vector capacities are set to the vector length. Deserialization results in a shared reference to the type, pointing at the binary data itself.

Abomonation does several unsafe things, and should ideally be used only through the methods encode and decode on types implementing the Abomonation trait. Implementing the Abomonation trait is highly discouraged, unless you use the unsafe_abomonate! macro, which is only mostly discouraged.

Very important: Abomonation reproduces the memory as laid out by the serializer, which can reveal architectural variations. Data encoded on a 32bit big-endian machine will not decode properly on a 64bit little-endian machine. Moreover, it could result in undefined behavior if the deserialization results in invalid typed data. Please do not do this.

Examples

use abomonation::{encode, decode};

// create some test data out of abomonation-approved types
let vector = (0..256u64).map(|i| (i, format!("{}", i)))
                        .collect::<Vec<_>>();

// encode a Vec<(u64, String)> into a Vec<u8>
let mut bytes = Vec::new();
unsafe { encode(&vector, &mut bytes); }

// decode a &Vec<(u64, String)> from &mut [u8] binary data
if let Some((result, remaining)) = unsafe { decode::<Vec<(u64, String)>>(&mut bytes) } {
    assert!(result == &vector);
    assert!(remaining.len() == 0);
}

Macros

unsafe_abomonate

The unsafe_abomonate! macro takes a type name with an optional list of fields, and implements Abomonation for the type, following the pattern of the tuple implementations: each method calls the equivalent method on each of its fields.

Traits

Abomonation

Abomonation provides methods to serialize any heap data the implementor owns.

Functions

decode

Decodes a mutable binary slice into an immutable typed reference.

encode

Encodes a typed reference into a binary buffer.