Crate diny

An asynchronous, alloc-free, serialization framework written in 100% safe™ Rust.

EXPERIMENTAL

• diny currently requires the nightly Rust toolchain >= 1.56.0 for GAT support.
• diny is still in active design–the API is incomplete and prone to change without notice and without backward compatibility.
• no_std support is largely ceremonial at this point as the futures-io traits currently require std.

That being said, it is ready for experimentation and design feedback.

Usage

Add a dependency on diny and a serializer format in Cargo.toml:

[dependencies]
diny = { version = "0.2", features = ["derive"] }
diny_test = "0.2"

Add GAT support to your project’s main file (e.g. main.rs, lib.rs):

#![feature(generic_associated_types)]

Profit!

use futures::executor::block_on;
use diny::{AsyncSerialize, AsyncDeserialize};

#[derive(Debug, PartialEq, AsyncSerialize, AsyncDeserialize)]
pub struct Point {
    x: i32,
    y: i32,
}
 
fn main() {
    let point = Point { x: 1, y: 2 };
 
    // A format can be any implementation of
    // diny::backend::{FormatSerialize + FormatDeserialize}.
    let format = diny_test::format();

    // A writer can be any implementation of futures::io::AsyncWrite.
    let mut writer = vec!();
    let write = point.serialize(&format, &mut writer);
    let _ = block_on(write);
 
    // A reader can be any implementation of futures::io::AsyncBufRead.
    // In this case, we're using a utility module to convert the bytes written
    // to the vec into an appropriate reader.
    let mut reader = diny::util::AsyncSliceReader::from(&writer[..]);
    let read = <Point as AsyncDeserialize>::deserialize(&format, &mut reader);
    let deserialized = block_on(read).unwrap();
    assert_eq!(point, deserialized);
}

A streaming interface is also available

use futures::{executor::block_on, SinkExt, StreamExt};

#[derive(diny::AsyncSerialization)]
pub struct Point {
    x: i32,
    y: i32,
}
 
fn main() {
    let point = Point { x: 1, y: 2 };

    // A sink is constructible for any implementor of diny::AsyncSerialize
    let mut sink = diny::serializer(diny_test::format(), vec!()).into_sink();
    block_on(sink.send(point));
 
    // If the sink is finished sending, it can be destructed into the inner Serializer
    assert!(sink.is_ready());
    let diny::Serializer { format, writer } = sink.try_into_inner().unwrap();
    let mut reader = diny::util::AsyncSliceReader::from(&writer[..]);
 
    // A stream is constructible for any implementor of diny::AsyncDeserialize
    let mut stream = diny::deserializer(format, &mut reader).into_stream();
    let deserialized: Point = block_on(stream.next()).unwrap();
}

Features

By default, diny builds with (and currently requires) Rust’s standard library. Importantly, the derive proc macros are not built by default, and need to be enabled to become available.

Feature	Description	Default
derive	Support for deriving AsyncSerialize and AsyncDeserialize traits	☐
unsafe_speed	Permit using unsafe code to improve performance	☐
std	Support for Rust’s standard library	☑
alloc	Support for memory allocation without full std support	☐
test	Build the diny_test formatter and re-export it to diny::test	☐

Modules

backend

Types and traits implemented by backend formatters

buffer

Helper modules for implementing buffered serialization primitives

deserializer

Types used to support deserialization streams

io

Re-export of io related structures

serializer

Types used to suport serialization sinks

util

Helper modules that may be externally useful

Macros

decode_chain

Starts decoding by calling the $dec expression, and converts the result to a PollDecodeStatus

decode_poll_chain

Continues decoding by first polling the $dec expression, and then calling the $chain closure with any resulting data, and finally converts the result to a PollDecodeStatus

decode_poll_fini

Finalizes decoding by polling the $dec expression, converts the final data by calling the $fini closure, and finally converts the result to a PollDecodeStatus

encode_chain

Starts encoding by calling the $enc expression, and converts the result to a PollEncodeStatus

encode_poll_chain

Continues encoding by first polling the $enc expression, and then calling the $chain expression, and finally converts the result to a PollEncodeStatus

encode_poll_fini

Finalizes encoding by polling the $enc expression, and converts the result to a PollEncodeStatus

Structs

Deserialize

Implements the Stream trait

Deserializer

A wrapper type around a specific (format)backend::FormatDecode and (reader)io::AsyncBufRead

Serialize

Implements the Sink trait

Serializer

A wrapper type around a specific (format)backend::FormatEncode and (writer)io::AsyncWrite

Traits

AsyncDeserialize

Deserialize a data structure asynchronously.

AsyncSerialization

Marker trait to denote that both AsyncSerialize and AsyncDeserialize are implemented for the type.

AsyncSerialize

Serialize a data structure asynchronously.

Functions

deserializer

Creates a new (Deserializer) from the specified (format)backend::FormatDecode and (reader)io::AsyncBufRead

serializer

Creates a new (Serializer) from the specified (format)backend::FormatEncode and (writer)io::AsyncWrite

Derive Macros

AsyncDeserialize

Generate only async deserialization code

AsyncSerialization

Generate both async serialization and deserialization code

AsyncSerialize

Generate only async serialization code