diff --git a/Cargo.toml b/Cargo.toml index 529fb40..5fcc054 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -25,3 +25,7 @@ smol = { version = "2", optional = true } tempdir = "0.3" tokio = { version = "1", features = ["net", "rt", "macros", "io-util"] } async-send-fd = { path = ".", features = ["tokio", "smol"] } + +[doc-dependencies] +tokio = { version = "1", features = ["net", "io-util"] } +smol = { version = "2" } diff --git a/README.md b/README.md index 1cd582e..b779ef3 100644 --- a/README.md +++ b/README.md @@ -14,17 +14,21 @@ A library for sending and receiving Unix file descriptors over async UnixStream [actions-url]: https://github.com/alexander-smoktal/async-send-fd/actions/workflows/rust.yml ## Overview -The crate is a library for sending and receiving Unix file descriptors over `tokio` or `smol` UnixStream connections. +The crate is a library for sending and receiving Unix file descriptors over [Tokio](https://crates.io/crates/tokio) or [Smol](https://crates.io/crates/smol) UnixStream connections. You can send **RawFd** or **UnixStream** using provided interfaces. See [test_raw_fd.rs](./tests/test_raw_fd.rs), [test_smol_stream.rs](./tests/test_smol_stream.rs), or [test_tokio_stream.rs](./tests/test_tokio_stream.rs) for examples. ## Creating **tokio::net::UnixStream** from **RawFd** -If you make a tokio [UnixStream](https://docs.rs/tokio/latest/tokio/net/struct.UnixStream.html) from a raw file descriptor made by an OS call (e.g. [UnixStream::pair](https://doc.rust-lang.org/std/os/unix/net/struct.UnixStream.html)), you must make it [set_nonblocking(true)](https://doc.rust-lang.org/stable/std/os/unix/net/struct.UnixStream.html#method.set_nonblocking), otherwise receiver schedulers will block writing into the socket ⚠️ +If you make a Tokio [UnixStream](https://docs.rs/tokio/latest/tokio/net/struct.UnixStream.html) from a raw file descriptor made by an OS call (e.g. [UnixStream::pair](https://doc.rust-lang.org/std/os/unix/net/struct.UnixStream.html)), you must make it [set_nonblocking(true)](https://doc.rust-lang.org/stable/std/os/unix/net/struct.UnixStream.html#method.set_nonblocking), otherwise receivers scheduler will block writing into the socket ⚠️ Smol [UnixStream](https://docs.rs/smol/2.0.0/smol/net/unix/struct.UnixStream.html) does it automatically if created using `UnixStream::from(Async::new(stream))` ## Transfering socket pair ownership Sending a descriptor doesn't close the local copy, which leads to having the socket being opened by the sender until it shuts down. If you want socket pair receivers to detect peer shutdown, you have to close local sockets after sending them. -Use [close](https://docs.rs/nix/latest/nix/unistd/fn.close.html) Posix call for tokio streams, or [UnixStream::shutdown()](https://docs.rs/smol/2.0.0/smol/net/unix/struct.UnixStream.html#method.shutdown) for `smol`. +Use [close](https://docs.rs/nix/latest/nix/unistd/fn.close.html) Posix call for Tokio streams, or [UnixStream::shutdown()](https://docs.rs/smol/2.0.0/smol/net/unix/struct.UnixStream.html#method.shutdown) for Smol. + +## Features +- `tokio` - for Tokio support +- `smol` - for Smol support \ No newline at end of file diff --git a/src/lib.rs b/src/lib.rs index eeb3353..dd3b299 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,18 +1,18 @@ //! **async-send-fd** is a library for sending and receiving Unix file descriptors over async UnixStream connections. //! You can either transfer //! - [RawFd]; -//! - tokio [UnixStream](tokio::net::UnixStream) if `tokio` feature enabled; -//! - or smol [UnixStream](smol::net::unix::UnixStream) if `smol` feature enabled; +//! - Tokio [UnixStream](tokio::net::UnixStream) if `tokio` feature enabled; +//! - or Smol [UnixStream](smol::net::unix::UnixStream) if `smol` feature enabled; //! //! ## Examles //! See [test_raw_fd.rs](https://github.com/alexander-smoktal/async-send-fd/blob/main/tests/test_raw_fd.rs), //! [test_smol_stream.rs](https://github.com/alexander-smoktal/async-send-fd/blob/main/tests/test_smol_fd.rs) or //! [test_tokio_stream.rs](https://github.com/alexander-smoktal/async-send-fd/blob/main/tests/test_tokio_stream.rs) for examples. //! -//! ## Creating a tokio [UnixStream](tokio::net::UnixStream) from [RawFd] -//! If you make a tokio [UnixStream](tokio::net::UnixStream) from a raw file descriptor made by an +//! ## Creating a Tokio [UnixStream](tokio::net::UnixStream) from [RawFd] +//! If you make a Tokio [UnixStream](tokio::net::UnixStream) from a raw file descriptor made by an //! OS call (e.g. [UnixStream::pair](std::os::unix::net::UnixStream::pair())), you must make it -//! [set_nonblocking(true)](std::os::unix::net::UnixStream::set_nonblocking()), otherwise receiver schedulers will block +//! [set_nonblocking(true)](std::os::unix::net::UnixStream::set_nonblocking()), otherwise receivers scheduler will block //! writing into the socket ⚠️ //! Smol [UnixStream](smol::net::unix::UnixStream) makes it automatically if created using `UnixStream::from(Async::new(stream))` //! @@ -20,7 +20,11 @@ //! Sending a descriptor doesn't close the local copy, which leads to having the socket being //! opened by the sender until it shuts down. //! If you want socket pair receivers to detect peer shutdown, you have to close local sockets after sending them. -//! Use [close](https://docs.rs/nix/latest/nix/unistd/fn.close.html) Posix call for tokio streams, or [UnixStream::shutdown()](smol::net::unix::UnixStream::shutdown) for `smol`. +//! Use [close](https://docs.rs/nix/latest/nix/unistd/fn.close.html) Posix call for Tokio streams, or [UnixStream::shutdown()](smol::net::unix::UnixStream::shutdown) for Smol. +//! +//! ## Features +//! - `tokio` - for Tokio support +//! - `smol` - for Smol support use std::{io::Error, os::unix::io::RawFd}; #[cfg(feature = "tokio")]