28 releases

new 0.13.0 Oct 10, 2024
0.12.4 Jul 12, 2024
0.12.3 Jun 29, 2024
0.11.2 Feb 18, 2024
0.1.1 Jul 23, 2022

#329 in Network programming

Download history 140/week @ 2024-06-13 152/week @ 2024-06-20 157/week @ 2024-06-27 10/week @ 2024-07-04 101/week @ 2024-07-11 5/week @ 2024-07-18 70/week @ 2024-07-25 15/week @ 2024-08-01 43/week @ 2024-09-19 11/week @ 2024-09-26

54 downloads per month

MIT license

230KB
5.5K SLoC

logo

Easy and fast communication between processes, threads and systems.

license-badge tests-badge version-badge docs-badge downloads-badge


Sender/Receiver types for communicating with a channel-like API across generic IO streams. It takes the burden on serializing, deserializing and transporting data off your back and let's you focus on the important logic of your project.

Contents

Examples

[dependencies.channels]
version = "0.13"
features = ["full"]
use tokio::net::TcpStream;

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
enum Message {
    Ping,
    Pong
}

#[tokio::main]
async fn main() {
    let stream = TcpStream::connect("127.0.0.1:8080").await.unwrap();
    let (r, w) = stream.into_split();
    let (mut tx, mut rx) = channels::channel::<Message, _, _>(r, w);

    loop {
        match rx.recv().await.unwrap() {
            Message::Ping => {
                println!("pinged!");
                tx.send(Message::Pong).await.unwrap();
            }
            Message::Pong => {
                println!("ponged!");
            }
        }
    }
}

For more, see: examples/

Features

Flag Description
aead Encrypt and authenticate data with ring::aead.
bincode Serialize/Deserialize data with bincode. (Enabled by default)
borsh Serialize/Deserialize data with borsh.
cbor Serialize/Deserialize data with ciborium.
core2 Support for core2::io::{Read, Write}.
crc Validate data with a CRC checksum.
deflate Compress data with DEFLATE.
embedded-io Support for embedded_io::{Read, Write}.
full-io Enable support for all of the IO traits.
full-serdes Enable features: aead, bincode, borsh, cbor, crc, deflate, hmac, json.
futures Support for futures::io::{AsyncRead, AsyncWrite}.
hmac Authenticate data with a HMAC using ring::hmac.
json Serialize/Deserialize data with serde_json.
smol Support for smol::io::{AsyncRead, AsyncWrite}.
statistics Collect IO metrics such as total bytes sent/received. See: Statistics.
std Support for std::io::{Read, Write}. If disabled also makes the crate no_std. (Enabled by default)
tokio Support for tokio::io::{AsyncRead, AsyncWrite}.

No two features of the crate are mutually exclusive. Instead, everything is implemented in a way to be infinitely extensible. This means, that even if you have other IO traits or another way to serialize or deserialize data, you can either add support for them directly in your own project by using the rich type system.

How it works

Channels implements a communication protocol that allows sending and receiving data in frames. The main API of the crate is intended to work over IO traits. However, if desired, the logic of the underlying protocol is available standalone without coupling it to the usage of any IO traits. It works over any stream synchronous or asynchronous with first class support for following IO traits:

Support for each IO trait can be enabled via the corresponding feature flag. See: Features. You can read more about how the underlying communication protocol works here.

License

Dependencies

~0.3–11MB
~152K SLoC