Skip to content

Commit

Permalink
docs: include readme as crate docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@threadexio
threadexio committed Jun 29, 2024
1 parent 740fea2 commit 7a3a346
Show file tree
Hide file tree
Showing 2 changed files with 20 additions and 78 deletions.
22 changes: 16 additions & 6 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@
[license]: https://github.com/threadexio/channels-rs/blob/master/LICENSE
[art-license]: https://github.com/threadexio/channels-rs/blob/master/assets/LICENSE

<div class="rustdoc-hidden">

<div align="center">
<img src="https://raw.githubusercontent.com/threadexio/channels-rs/master/assets/logo.transparent.svg" width="640" alt="logo">

Expand All @@ -30,6 +32,8 @@

<br>

</div>

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. It is:

- **Fast**: The simple protocol allows low-overhead transporting of data.
Expand All @@ -44,7 +48,7 @@ Sender/Receiver types for communicating with a channel-like API across generic I

```toml
[dependencies.channels]
version = "0.12.0"
version = "0.12.3"
features = ["full"]
```

Expand Down Expand Up @@ -85,11 +89,11 @@ For more, see: [examples/][examples]

Channels implements a communication protocol that allows sending and receiving data across any medium. It works over _any_ stream synchronous or asynchronous. Currently it can work with any of the following IO traits:

- [`std::io::{Read, Write}`](https://doc.rust-lang.org/stable/std/io)
- [`tokio::io::{AsyncRead, AsyncWrite}`](https://docs.rs/tokio/latest/tokio/io)
- [`futures::io::{AsyncRead, AsyncWrite}`](https://docs.rs/futures/latest/futures/io)
- [`core2::io::{Read, Write}`](https://docs.rs/core2)
- [`smol::io::{AsyncRead, AsyncWrite}`](https://docs.rs/smol)
- [`std::io::{Read, Write}`][]
- [`tokio::io::{AsyncRead, AsyncWrite}`][]
- [`futures::io::{AsyncRead, AsyncWrite}`][]
- [`core2::io::{Read, Write}`][]
- [`smol::io::{AsyncRead, AsyncWrite}`][]

You can find out more about how the underlying communication protocol works [here][spec].

Expand All @@ -98,3 +102,9 @@ You can find out more about how the underlying communication protocol works [her
- All code in this repository is licensed under the MIT license, a copy of which can be found [here][license].

- All artwork in this repository is licensed under [Creative Commons Attribution-NonCommercial 4.0 International](https://creativecommons.org/licenses/by-nc/4.0/). A copy of the license can be found [here][art-license].

[`std::io::{Read, Write}`]: https://doc.rust-lang.org/stable/std/io
[`tokio::io::{AsyncRead, AsyncWrite}`]: https://docs.rs/tokio/latest/tokio/io
[`futures::io::{AsyncRead, AsyncWrite}`]: https://docs.rs/futures/latest/futures/io
[`core2::io::{Read, Write}`]: https://docs.rs/core2
[`smol::io::{AsyncRead, AsyncWrite}`]: https://docs.rs/smol
76 changes: 4 additions & 72 deletions channels/src/lib.rs
View file
Original file line number Diff line number Diff line change
@@ -1,75 +1,7 @@
//! Channel communication across generic data streams.
//!
//! ## Quick start
//!
//! ### Async
//!
//! ```no_run
//! use tokio::net::TcpStream;
//! use tokio::net::tcp::{OwnedReadHalf, OwnedWriteHalf};
//!
//!
//! # #[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::<i32, _, _>(r, w);
//!
//! let r = rx.recv().await.unwrap();
//! println!("{r}");
//! tx.send(r).await.unwrap();
//! # }
//! ```
//!
//! ### Sync
//!
//! ```no_run
//! use std::net::TcpStream;
//!
//! let stream = TcpStream::connect("127.0.0.1:8080").unwrap();
//! let (mut tx, mut rx) = channels::channel::<i32, _, _>(stream.try_clone().unwrap(), stream);
//!
//! let r = rx.recv_blocking().unwrap();
//! println!("{r}");
//! tx.send_blocking(r).unwrap();
//! ```
//!
//! ## Examples
//!
//! See: [examples/](https://github.com/threadexio/channels-rs/tree/master/examples)
//!
//! ## cargo features
//!
//! | Feature | Description |
//! | :-----------: | :---------------------------------------------------------------------------------------------- |
//! | `statistics` | Capture statistic data like: total bytes sent/received, number of send/receive operations, etc. |
//! | `aead` | Middleware that encrypts data for transport. |
//! | `bincode` | Support for serializing/deserializing types with [`bincode`]. |
//! | `borsh` | Support for serializing/deserializing types with [`borsh`]. |
//! | `cbor` | Support for serializing/deserializing types with [`ciborium`]. |
//! | `crc` | Middleware that verifies data with a CRC checksum. |
//! | `deflate` | Middleware that compresses data with DEFLATE. |
//! | `hmac` | Middleware that verifies data with HMAC. |
//! | `json` | Support for serializing/deserializing types with [`serde_json`]. |
//! | `full-serdes` | Features: `aead`, `bincode`, `borsh`, `cbor`, `crc`, `deflate`, `hmac`, `json` |
//! | `core2` | Adds support for sending/receiving types with [`core2`]. |
//! | `futures` | Adds support for sending/receiving types asynchronously with [`futures`]. |
//! | `smol` | Adds support for sending/receiving types asynchronously with [`smol`]. |
//! | `std` | Adds support for sending/receiving types over [`Read`] and [`Write`]. |
//! | `tokio` | Adds support for sending/receiving types asynchronously with [`tokio`]. |
//! | `full-io` | Features: `core2`, `futures`, `smol`, `std`, `tokio` |
//! | `full` | Every feature in this table. |
//!
//! [`core2`]: https://docs.rs/core2
//! [`bincode`]: https://docs.rs/bincode
//! [`ciborium`]: https://docs.rs/ciborium
//! [`serde_json`]: https://docs.rs/serde_json
//! [`borsh`]: https://docs.rs/borsh
//! [`tokio`]: https://docs.rs/tokio
//! [`futures`]: https://docs.rs/futures
//! [`Read`]: std::io::Read
//! [`Write`]: std::io::Write
//! [`smol`]: https://docs.rs/smol
//! <style>
//! .rustdoc-hidden { display: none; }
//! </style>
#![doc = include_str!("../README.md")]
#![cfg_attr(channels_nightly, feature(doc_auto_cfg))]
#![cfg_attr(not(feature = "std"), no_std)]
#![warn(clippy::print_stdout, clippy::print_stderr)]
Expand Down

0 comments on commit 7a3a346

Please sign in to comment.