From db8796ab408ceae9aaffed303112175c28700df0 Mon Sep 17 00:00:00 2001 From: Philipp Dresselmann Date: Fri, 13 Dec 2024 21:59:54 +0100 Subject: [PATCH] chore(docs): Add an example for the uds_recv_fd module --- util/src/mio/uds_recv_fd.rs | 52 +++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/util/src/mio/uds_recv_fd.rs b/util/src/mio/uds_recv_fd.rs index 834b10c81..8cba2a30a 100644 --- a/util/src/mio/uds_recv_fd.rs +++ b/util/src/mio/uds_recv_fd.rs @@ -12,6 +12,58 @@ use crate::fd::{claim_fd_inplace, IntoStdioErr}; /// A wrapper around a socket that combines reading from the socket with tracking /// received file descriptors. Limits the maximum number of file descriptors that /// can be received in a single read operation via the `MAX_FDS` parameter. +/// +/// # Example +/// +/// ```rust +/// use std::collections::VecDeque; +/// use std::io::Cursor; +/// use std::io::Read; +/// use std::os::fd::AsRawFd; +/// use std::os::fd::OwnedFd; +/// +/// use mio::net::UnixStream; +/// use rosenpass_util::mio::ReadWithFileDescriptors; +/// use rosenpass_util::io::TryIoResultKindHintExt; +/// +/// const MAX_REQUEST_FDS : usize = 2; // Limit to 2 descriptors per read operation +/// let mut read_fd_buffer = VecDeque::::new(); // File descriptor queue +/// +/// // In this case, the unused writable end of the connection can be ignored +/// let (io_stream, _) = UnixStream::pair().expect("failed to create socket pair"); +/// +/// // Wait until the output stream is writable... +/// +/// // Wrap the socket to start tracking received file descriptors +/// let mut fd_passing_sock = ReadWithFileDescriptors::::new( +/// &io_stream, +/// &mut read_fd_buffer, +/// ); +//// +/// // Simulated reads; the actual operations will depend on the protocol (implementation details) +/// let mut recv_buffer = Vec::::new(); +/// let bytes_read = fd_passing_sock.read(&mut recv_buffer[..]).expect("error reading from socket"); +/// assert_eq!(bytes_read, 0); +/// assert_eq!(&recv_buffer[..bytes_read], []); +/// +/// // Alternatively, it's possible to use the try_io_err_kind_hint utility provided by this crate +/// match fd_passing_sock.read(&mut recv_buffer).try_io_err_kind_hint() { +/// Err(_) => { +/// // Handle errors here ... +/// } +/// Ok(result) => { +/// // Process messages here ... +/// assert_eq!(0, result); // Nothing to read in this example +/// } +/// }; +/// +/// // The wrapped components can still be accessed +/// assert_eq!(fd_passing_sock.socket().as_raw_fd(), io_stream.as_raw_fd()); +/// let (socket, fd_queue) = fd_passing_sock.into_parts(); +/// assert_eq!(socket.as_raw_fd(), io_stream.as_raw_fd()); +/// +/// // Shutdown, cleanup, etc. goes here ... +/// ``` pub struct ReadWithFileDescriptors where Sock: FdPassingExt,