From ec6706ffebe456d412213dfe2e8e4e763e37101a Mon Sep 17 00:00:00 2001 From: Philipp Dresselmann Date: Thu, 19 Dec 2024 10:00:55 +0100 Subject: [PATCH] chore(docs): Add a docstring example for uds_send_fd --- util/src/mio/uds_send_fd.rs | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/util/src/mio/uds_send_fd.rs b/util/src/mio/uds_send_fd.rs index cd5db4f..ee148d6 100644 --- a/util/src/mio/uds_send_fd.rs +++ b/util/src/mio/uds_send_fd.rs @@ -11,6 +11,43 @@ use uds::UnixStreamExt as FdPassingExt; use crate::{repeat, return_if}; /// A structure that facilitates writing data and file descriptors to a Unix domain socket +/// +/// # Example +/// +/// ```rust +/// use std::io::{Read, Write}; +/// use std::net::UdpSocket; +/// use std::os::fd::{AsFd, AsRawFd}; +/// +/// use mio::net::UnixStream; +/// use rosenpass_util::mio::WriteWithFileDescriptors; +/// +/// // Create socket descriptors that should be sent (not limited to UDP sockets) +/// let peer_endpoint = "[::1]:0"; +/// let peer_socket = UdpSocket::bind(peer_endpoint).expect("bind failed"); +/// let peer_socket_fd = peer_socket.as_fd(); +/// let mut fds_to_send = vec![&peer_socket_fd].into(); +/// +/// // Create writable end (must be an Unix Domain Socket) +/// // In this case, the readable end of the connection can be ignored +/// let (mut dummy_sink, io_stream) = UnixStream::pair().expect("failed to create socket pair"); +/// let mut writable_stream = WriteWithFileDescriptors::::new( +/// &io_stream, &mut fds_to_send); +/// +/// // Send data and file descriptors (note that at least one byte should be written) +/// writable_stream.write(&[0xffu8; 42]).expect("failed to write"); +/// // Discard data; the dummy_sink is only required to keep the connection alive here +/// let mut recv_buffer = Vec::::new(); +/// dummy_sink.read(&mut recv_buffer[..]).expect("error reading from socket"); +/// writable_stream.flush().expect("failed to flush"); // Currently a NOOP +/// +/// // The wrapped components can still be accessed +/// let (socket, fds) = writable_stream.into_parts(); +/// assert_eq!(socket.as_raw_fd(), io_stream.as_raw_fd()); +/// assert!(fds_to_send.is_empty(), "Failed to send file descriptors"); +/// +/// // Shutdown, cleanup, etc. goes here ... +/// ``` pub struct WriteWithFileDescriptors where Sock: FdPassingExt,