Crate diny[−][src]
Expand description
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::{AsyncRead + 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);
}
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
Types and traits implemented by backend formatters
Helper modules for implementing buffered serialization primitives
Re-export of io related structures
Helper modules that may be externally useful
Macros
Starts decoding by calling the $dec
expression, and converts the
result to a PollDecodeStatus
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
Finalizes decoding by polling the $dec
expression, converts
the final data by calling the $fini
closure, and finally converts
the result to a PollDecodeStatus
Starts encoding by calling the $enc
expression, and converts the
result to a PollEncodeStatus
Continues encoding by first polling the $enc
expression, and then
calling the $chain
expression, and finally converts the
result to a PollEncodeStatus
Finalizes encoding by polling the $enc
expression, and converts
the result to a PollEncodeStatus
Traits
Deserialize a data structure asynchronously.
Marker trait to denote that both AsyncSerialize and AsyncDeserialize are implemented for the type.
Serialize a data structure asynchronously.
Derive Macros
Generate only async deserialization code
Generate both async serialization and deserialization code
Generate only async serialization code