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::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
Types and traits implemented by backend formatters
Helper modules for implementing buffered serialization primitives
Types used to support deserialization streams
Re-export of io related structures
Types used to suport serialization sinks
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
Structs
Implements the Stream trait
A wrapper type around a specific (format)backend::FormatDecode and (reader)io::AsyncBufRead
A wrapper type around a specific (format)backend::FormatEncode and (writer)io::AsyncWrite
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.
Functions
Creates a new (Deserializer) from the specified (format)backend::FormatDecode and (reader)io::AsyncBufRead
Creates a new (Serializer) from the specified (format)backend::FormatEncode and (writer)io::AsyncWrite
Derive Macros
Generate only async deserialization code
Generate both async serialization and deserialization code
Generate only async serialization code