tokio_seqpacket/lib.rs
1//! Unix seqpacket sockets for [tokio](https://docs.rs/tokio).
2//!
3//! Seqpacket sockets combine a number of useful properties:
4//! * They are connection oriented.
5//! * They guarantee in-order message delivery.
6//! * They provide datagrams with well-defined semantics for passing along file descriptors.
7//!
8//! These properties make seqpacket sockets very well suited for local servers that need to pass file-descriptors around with their clients.
9//!
10//! You can create a [`UnixSeqpacketListener`] to start accepting connections,
11//! or create a [`UnixSeqpacket`] to connect to a listening socket.
12//! You can also create a pair of connected sockets with [`UnixSeqpacket::pair()`].
13//!
14//! # Passing file descriptors and other ancillary data.
15//!
16//! You can use [`send_vectored_with_ancillary`][UnixSeqpacket::send_vectored_with_ancillary] and [`recv_vectored_with_ancillary`][UnixSeqpacket::recv_vectored_with_ancillary]
17//! to send and receive ancillary data.
18//! This can be used to pass file descriptors and unix credentials over sockets.
19//!
20//! # `&self` versus `&mut self`
21//!
22//! Seqpacket sockets have well-defined semantics when sending or receiving on the same socket from different threads.
23//! Although the order is not guaranteed in that scenario, each datagram will be delivered intact.
24//! Since tokio 0.3, it is also possible for multiple tasks to await the same file descriptor.
25//! As such, all I/O functions now take `&self` instead of `&mut self`,
26//! and the `split()` API has been deprecated.
27//!
28//! # Example
29//! ```no_run
30//! # async fn foo() -> Result<(), Box<dyn std::error::Error>> {
31//! use tokio_seqpacket::UnixSeqpacket;
32//!
33//! let mut socket = UnixSeqpacket::connect("/run/foo.sock").await?;
34//! socket.send(b"Hello!").await?;
35//!
36//! let mut buffer = [0u8; 128];
37//! let len = socket.recv(&mut buffer).await?;
38//! println!("{}", String::from_utf8_lossy(&buffer[..len]));
39//! # Ok(())
40//! # }
41//! ```
42
43#![warn(missing_docs)]
44
45macro_rules! ready {
46 ($e:expr) => {
47 match $e {
48 Poll::Pending => return Poll::Pending,
49 Poll::Ready(x) => x,
50 }
51 };
52}
53
54pub mod ancillary;
55pub mod borrow_fd;
56mod listener;
57mod socket;
58mod sys;
59mod ucred;
60
61pub use listener::UnixSeqpacketListener;
62pub use socket::UnixSeqpacket;
63pub use ucred::UCred;
64
65#[doc(hidden)]
66#[deprecated(
67 since = "0.4.0",
68 note = "all I/O functions now take a shared reference to self, so splitting is no longer necessary"
69)]
70pub type ReadHalf<'a> = &'a UnixSeqpacket;
71
72#[doc(hidden)]
73#[deprecated(
74 since = "0.4.0",
75 note = "all I/O functions now take a shared reference to self, so splitting is no longer necessary"
76)]
77pub type WriteHalf<'a> = &'a UnixSeqpacket;