Struct fd_queue::UnixStream
source · [−]pub struct UnixStream { /* private fields */ }
Expand description
A structure representing a connected Unix socket with support for passing
RawFd
.
This is the primary implementation of EnqueueFd
and DequeueFd
and it is based
on a blocking, Unix domain socket. Conceptually the key interfaces on
UnixStream
interact as shown in the following diagram:
EnqueueFd => Write => Read => DequeueFd
That is, you first enqueue a RawFd
to the UnixStream
and then
Write
at least one byte. On the other side of the UnixStream
you then Read
at least one byte and then dequeue the RawFd
.
Examples
use std::fs::File;
let (mut sock1, mut sock2) = UnixStream::pair()?;
// sender side
// let file1: File = ...
sock1.enqueue(&file1).expect("Can't endqueue the file descriptor.");
sock1.write(b"a")?;
sock1.flush()?;
// receiver side
let mut buf = [0u8; 1];
sock2.read(&mut buf)?;
let fd = sock2.dequeue().expect("Can't dequeue the file descriptor.");
let file2 = unsafe { File::from_raw_fd(fd) };
Implementations
sourceimpl UnixStream
impl UnixStream
sourcepub const FD_QUEUE_SIZE: usize = 2usize
pub const FD_QUEUE_SIZE: usize = 2usize
The size of the bounded queue of outbound RawFd
.
sourcepub fn connect<P: AsRef<Path>>(path: P) -> Result<UnixStream>
pub fn connect<P: AsRef<Path>>(path: P) -> Result<UnixStream>
Connects to the socket named by path
.
Examples
use fd_queue::UnixStream;
// let path = ...
let sock = match UnixStream::connect(path) {
Ok(sock) => sock,
Err(e) => {
println!("Couldn't connect to a socket: {}", e);
return Ok(());
}
};
sourcepub fn pair() -> Result<(UnixStream, UnixStream)>
pub fn pair() -> Result<(UnixStream, UnixStream)>
Creates an unnamed pair of connected sockets.
Returns two UnixStream
s which are connected to each other.
Examples
use fd_queue::UnixStream;
let (sock1, sock2) = match UnixStream::pair() {
Ok((sock1, sock2)) => (sock1, sock2),
Err(e) => {
println!("Couldn't create a pair of sockets: {}", e);
return;
}
};
sourcepub fn try_clone(&self) -> Result<UnixStream>
pub fn try_clone(&self) -> Result<UnixStream>
Creates a new independently owned handle to the underlying socket.
The returned UnixStream
is a reference to the same stream that this object references.
Both handles will read and write the same stream of data, and options set on one stream
will be propagated to the other stream.
Examples
use fd_queue::UnixStream;
let (sock1, _) = UnixStream::pair()?;
let sock2 = match sock1.try_clone() {
Ok(sock) => sock,
Err(e) => {
println!("Couldn't clone a socket: {}", e);
return Ok(());
}
};
sourcepub fn local_addr(&self) -> Result<SocketAddr>
pub fn local_addr(&self) -> Result<SocketAddr>
Returns the socket address of the local half of this connection.
Examples
use fd_queue::UnixStream;
// let path = ...
let sock = UnixStream::connect(path)?;
let addr = match sock.local_addr() {
Ok(addr) => addr,
Err(e) => {
println!("Couldn't get the local address: {}", e);
return Ok(());
}
};
sourcepub fn peer_addr(&self) -> Result<SocketAddr>
pub fn peer_addr(&self) -> Result<SocketAddr>
Returns the socket address of the remote half of this connection.
Examples
use fd_queue::UnixStream;
// let path = ...
let sock = UnixStream::connect(path)?;
let addr = match sock.peer_addr() {
Ok(addr) => addr,
Err(e) => {
println!("Couldn't get the local address: {}", e);
return Ok(());
}
};
sourcepub fn take_error(&self) -> Result<Option<Error>>
pub fn take_error(&self) -> Result<Option<Error>>
Returns the value of the SO_ERROR
option.
Examples
use fd_queue::UnixStream;
let (sock, _) = UnixStream::pair()?;
let err = match sock.take_error() {
Ok(Some(err)) => err,
Ok(None) => {
println!("No error found.");
return Ok(());
}
Err(e) => {
println!("Couldn't take the SO_ERROR option: {}", e);
return Ok(());
}
};
sourcepub fn shutdown(&self, how: Shutdown) -> Result<()>
pub fn shutdown(&self, how: Shutdown) -> Result<()>
Shuts down the read, write, or both halves of this connection.
This function will cause all pending and future I/O calls on the specified portions to immediately return with an appropriate value.
Examples
use fd_queue::UnixStream;
use std::net::Shutdown;
use std::io::Read;
let (mut sock, _) = UnixStream::pair()?;
sock.shutdown(Shutdown::Read).expect("Couldn't shutdown.");
let mut buf = [0u8; 256];
match sock.read(buf.as_mut()) {
Ok(0) => {},
_ => panic!("Read unexpectly not shut down."),
}
Trait Implementations
sourceimpl AsRawFd for UnixStream
impl AsRawFd for UnixStream
sourceimpl Debug for UnixStream
impl Debug for UnixStream
sourceimpl DequeueFd for UnixStream
impl DequeueFd for UnixStream
sourceimpl EnqueueFd for UnixStream
impl EnqueueFd for UnixStream
sourceimpl From<UnixStream> for UnixStream
impl From<UnixStream> for UnixStream
sourcefn from(inner: StdUnixStream) -> Self
fn from(inner: StdUnixStream) -> Self
Converts to this type from the input type.
sourceimpl FromRawFd for UnixStream
impl FromRawFd for UnixStream
sourceunsafe fn from_raw_fd(fd: RawFd) -> Self
unsafe fn from_raw_fd(fd: RawFd) -> Self
Constructs a new instance of Self
from the given raw file
descriptor. Read more
sourceimpl IntoRawFd for UnixStream
impl IntoRawFd for UnixStream
sourcefn into_raw_fd(self) -> RawFd
fn into_raw_fd(self) -> RawFd
Consumes this object, returning the raw underlying file descriptor. Read more
sourceimpl Read for UnixStream
impl Read for UnixStream
Receive bytes and RawFd
that are transmitted across the UnixStream
.
The RawFd
that are received along with the bytes will be available
through the method of the DequeueFd
implementation. The number of
RawFd
that can be received in a single call to one of the Read
methods is bounded by FD_QUEUE_SIZE
. It is an error if the other side of this
UnixStream
attempted to send more control messages (including RawFd
)
than will fit in the buffer that has been sized for receiving up to
FD_QUEUE_SIZE
RawFd
.
sourcefn read(&mut self, buf: &mut [u8]) -> Result<usize>
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
Pull some bytes from this source into the specified buffer, returning how many bytes were read. Read more
sourcefn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize>
fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize>
Like read
, except that it reads into a slice of buffers. Read more
sourcefn is_read_vectored(&self) -> bool
fn is_read_vectored(&self) -> bool
can_vector
)Determines if this Read
er has an efficient read_vectored
implementation. Read more
1.0.0 · sourcefn read_to_end(&mut self, buf: &mut Vec<u8, Global>) -> Result<usize, Error>
fn read_to_end(&mut self, buf: &mut Vec<u8, Global>) -> Result<usize, Error>
Read all bytes until EOF in this source, placing them into buf
. Read more
1.0.0 · sourcefn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
Read all bytes until EOF in this source, appending them to buf
. Read more
1.6.0 · sourcefn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
Read the exact number of bytes required to fill buf
. Read more
sourcefn read_buf(&mut self, buf: &mut ReadBuf<'_>) -> Result<(), Error>
fn read_buf(&mut self, buf: &mut ReadBuf<'_>) -> Result<(), Error>
read_buf
)Pull some bytes from this source into the specified buffer. Read more
sourcefn read_buf_exact(&mut self, buf: &mut ReadBuf<'_>) -> Result<(), Error>
fn read_buf_exact(&mut self, buf: &mut ReadBuf<'_>) -> Result<(), Error>
read_buf
)Read the exact number of bytes required to fill buf
. Read more
1.0.0 · sourcefn by_ref(&mut self) -> &mut Self
fn by_ref(&mut self) -> &mut Self
Creates a “by reference” adaptor for this instance of Read
. Read more
sourceimpl Write for UnixStream
impl Write for UnixStream
Transmit bytes and RawFd
across the UnixStream
.
The RawFd
that are transmitted along with the bytes are ones that were
previously enqueued for transmission through the method of EnqueueFd
.
sourcefn write(&mut self, buf: &[u8]) -> Result<usize>
fn write(&mut self, buf: &[u8]) -> Result<usize>
Write a buffer into this writer, returning how many bytes were written. Read more
sourcefn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize>
fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize>
sourcefn flush(&mut self) -> Result<()>
fn flush(&mut self) -> Result<()>
Flush this output stream, ensuring that all intermediately buffered contents reach their destination. Read more
sourcefn is_write_vectored(&self) -> bool
fn is_write_vectored(&self) -> bool
can_vector
)Determines if this Write
r has an efficient write_vectored
implementation. Read more
1.0.0 · sourcefn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
Attempts to write an entire buffer into this writer. Read more
sourcefn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
write_all_vectored
)Attempts to write multiple buffers into this writer. Read more
Auto Trait Implementations
impl RefUnwindSafe for UnixStream
impl Send for UnixStream
impl Sync for UnixStream
impl Unpin for UnixStream
impl UnwindSafe for UnixStream
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> Instrument for T
impl<T> Instrument for T
sourcefn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
sourcefn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
sourceimpl<T> WithSubscriber for T
impl<T> WithSubscriber for T
sourcefn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
sourcefn with_current_subscriber(self) -> WithDispatch<Self>
fn with_current_subscriber(self) -> WithDispatch<Self>
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more