5 releases (3 breaking)
0.4.1 | Apr 1, 2021 |
---|---|
0.4.0 |
|
0.3.0 | Feb 11, 2021 |
0.2.0 | Jan 13, 2021 |
0.1.1 | Dec 18, 2020 |
#766 in Asynchronous
69 downloads per month
Used in 7 crates
(6 directly)
150KB
1.5K
SLoC
Dialectic
dialectic (noun): The process of arriving at the truth by stating a thesis, developing a contradictory antithesis, and combining them into a coherent synthesis.
dialectic (crate): Transport-polymorphic session types for asynchronous Rust.
When two concurrent processes communicate, it's good to give their messages types, which ensure every message is of an expected form.
- Conventional types merely describe what is valid to communicate.
- Session types describe when it is valid to communicate, and in what manner.
This crate provides a generic wrapper around almost any type of asynchronous channel that adds compile-time guarantees that a specified session protocol will not be violated by any code using the channel. Such a wrapped channel:
- has almost no runtime cost in time or memory;
- is built on
async
/.await
to allow integration with Rust's powerfulasync
ecosystem; - gracefully handles runtime protocol violations, introducing no panics;
- allows for full duplex concurrent communication, if specified in its type, while preserving all the same session-type safety guarantees; and
- can even implement context free sessions, a more general form of session type than supported by most other session typing libraries.
Together, these make Dialectic ideal for writing networked services that need to ensure high levels of availability and complex protocol correctness properties in the real world, where protocols might be violated and connections might be dropped.
Dialectic supports a number of async runtimes and backends out-of-the-box, if you don't want to or don't need to write your own:
- The
dialectic-tokio-mpsc
crate supports using Dialectic to communicate between tasks using Tokio'smpsc
queues. - The
dialectic-tokio-serde
crate supports using Dialectic to communicate over anyAsyncRead
/AsyncWrite
transport layer encoded using any Tokiocodec
. A couple of Serde formats are already implemented, but it is easy to implement your own:dialectic-tokio-serde-bincode
backend usingbincode
for serializationdialectic-tokio-serde-json
backend usingserde_json
for serialization
These crates also serve as good references for writing your own backends.
What now?
- If you are new to session types you might consider starting with the tutorial-style tour of the crate.
- If you're familiar with session types, you might jump to the quick
reference, then read more about the
Session!
macro for specifying session types, and continue on to look at thetypes
module and the documentation forChan
. - You may also find helpful the full self-contained examples, which show how all the features of the crate come together to build session-typed network programs.
- If you want to integrate your own channel type with Dialectic, you need to implement the
Transmit
andReceive
traits from thebackend
module. - Or, you can dive into the reference documentation...
Dependencies
~4–10MB
~120K SLoC