Struct UnixStream 

pub struct UnixStream { /* private fields */ }

Available on crate feature net only.

A Unix stream between two local sockets on Windows & WSL.

A Unix stream can either be created by connecting to an endpoint, via the connect method, or by accepting a connection from a listener.

Examples

use compio_io::AsyncWrite;
use compio_net::UnixStream;

// Connect to a peer
let mut stream = UnixStream::connect("unix-server.sock").await.unwrap();

// Write some data.
stream.write("hello world!").await.unwrap();

Implementations

impl UnixStream

pub async fn connect(path: impl AsRef<Path>) -> Result<UnixStream, Error>

Opens a Unix connection to the specified file path. See UnixStream::connect_addr for more details.

pub async fn connect_addr(addr: &SockAddr) -> Result<UnixStream, Error>

Opens a Unix connection to the specified address. There must be a UnixListener or equivalent listening on the corresponding Unix domain socket to successfully connect and return a UnixStream.

To configure the socket before connecting, you can use the UnixSocket type.

pub fn from_std(stream: UnixStream) -> Result<UnixStream, Error>

Available on Unix only.

Creates new UnixStream from a std::os::unix::net::UnixStream.

pub fn close(self) -> impl Future<Output = Result<(), Error>>

Close the socket. If the returned future is dropped before polling, the socket won’t be closed.

See TcpStream::close for more details.

pub fn peer_addr(&self) -> Result<SockAddr, Error>

Returns the socket path of the remote peer of this connection.

pub fn local_addr(&self) -> Result<SockAddr, Error>

Returns the socket path of the local half of this connection.

pub fn take_error(&self) -> Result<Option<Error>, Error>

Returns the value of the SO_ERROR option.

pub fn split(&self) -> (ReadHalf<'_, UnixStream>, WriteHalf<'_, UnixStream>)

Splits a UnixStream into a read half and a write half, which can be used to read and write the stream concurrently.

This method is more efficient than into_split, but the halves cannot be moved into independently spawned tasks.

pub fn into_split(self) -> (UnixStream, UnixStream)

Splits a UnixStream into a read half and a write half, which can be used to read and write the stream concurrently.

Unlike split, the owned halves can be moved to separate tasks.

pub fn to_poll_fd(&self) -> Result<PollFd<Socket>, Error>

Create PollFd from inner socket.

pub fn into_poll_fd(self) -> Result<PollFd<Socket>, Error>

Create PollFd from inner socket.

Trait Implementations

impl AsFd for UnixStream

Available on Unix only.

fn as_fd(&self) -> BorrowedFd<'_>

Borrows the file descriptor.

impl AsRawFd for UnixStream

fn as_raw_fd(&self) -> i32

Extracts the raw file descriptor.

impl AsyncRead for &UnixStream

async fn read<B>(&mut self, buf: B) -> BufResult<usize, B>

where B: IoBufMut,

Read some bytes from this source into the IoBufMut buffer and return a BufResult, consisting of the buffer and a usize indicating how many bytes were read.

async fn read_vectored<V>(&mut self, buf: V) -> BufResult<usize, V>

where V: IoVectoredBufMut,

Like read, except that it reads into a type implements IoVectoredBufMut.

impl AsyncRead for UnixStream

async fn read<B>(&mut self, buf: B) -> BufResult<usize, B>

where B: IoBufMut,

Read some bytes from this source into the IoBufMut buffer and return a BufResult, consisting of the buffer and a usize indicating how many bytes were read.

async fn read_vectored<V>(&mut self, buf: V) -> BufResult<usize, V>

where V: IoVectoredBufMut,

Like read, except that it reads into a type implements IoVectoredBufMut.

impl AsyncReadAncillary for &UnixStream

async fn read_with_ancillary<T, C>( &mut self, buffer: T, control: C, ) -> BufResult<(usize, usize), (T, C)>

where T: IoBufMut, C: IoBufMut,

Read data with ancillary data into an owned buffer.

async fn read_vectored_with_ancillary<T, C>( &mut self, buffer: T, control: C, ) -> BufResult<(usize, usize), (T, C)>

where T: IoVectoredBufMut, C: IoBufMut,

Read data with ancillary data into a vectored buffer.

impl AsyncReadAncillary for UnixStream

async fn read_with_ancillary<T, C>( &mut self, buffer: T, control: C, ) -> BufResult<(usize, usize), (T, C)>

where T: IoBufMut, C: IoBufMut,

Read data with ancillary data into an owned buffer.

async fn read_vectored_with_ancillary<T, C>( &mut self, buffer: T, control: C, ) -> BufResult<(usize, usize), (T, C)>

where T: IoVectoredBufMut, C: IoBufMut,

Read data with ancillary data into a vectored buffer.

impl AsyncReadAncillaryManaged for &UnixStream

async fn read_managed_with_ancillary<C>( &mut self, len: usize, control: C, ) -> Result<Option<(<&UnixStream as AsyncReadManaged>::Buffer, C)>, Error>

where C: IoBufMut,

Read data into a managed buffer with ancillary data.

impl AsyncReadAncillaryManaged for UnixStream

async fn read_managed_with_ancillary<C>( &mut self, len: usize, control: C, ) -> Result<Option<(<UnixStream as AsyncReadManaged>::Buffer, C)>, Error>

where C: IoBufMut,

Read data into a managed buffer with ancillary data.

impl AsyncReadAncillaryMulti for &UnixStream

type Return = RecvMsgMultiResult

A wrapped type for the payload data and the ancillary data.

fn read_multi_with_ancillary( &mut self, control_len: usize, ) -> impl Stream<Item = Result<<&UnixStream as AsyncReadAncillaryMulti>::Return, Error>>

Read data and ancillary data into multiple managed buffers.

impl AsyncReadAncillaryMulti for UnixStream

type Return = RecvMsgMultiResult

A wrapped type for the payload data and the ancillary data.

fn read_multi_with_ancillary( &mut self, control_len: usize, ) -> impl Stream<Item = Result<<UnixStream as AsyncReadAncillaryMulti>::Return, Error>>

Read data and ancillary data into multiple managed buffers.

impl AsyncReadManaged for &UnixStream

type Buffer = BufferRef

Filled buffer type

async fn read_managed( &mut self, len: usize, ) -> Result<Option<<&UnixStream as AsyncReadManaged>::Buffer>, Error>

Read some bytes from this source and return a Self::Buffer.

impl AsyncReadManaged for UnixStream

type Buffer = BufferRef

Filled buffer type

async fn read_managed( &mut self, len: usize, ) -> Result<Option<<UnixStream as AsyncReadManaged>::Buffer>, Error>

Read some bytes from this source and return a Self::Buffer.

impl AsyncReadMulti for &UnixStream

fn read_multi( &mut self, len: usize, ) -> impl Stream<Item = Result<<&UnixStream as AsyncReadManaged>::Buffer, Error>>

Read some bytes from this source and return a stream of AsyncReadManaged::Buffer.

impl AsyncReadMulti for UnixStream

fn read_multi( &mut self, len: usize, ) -> impl Stream<Item = Result<<UnixStream as AsyncReadManaged>::Buffer, Error>>

Read some bytes from this source and return a stream of AsyncReadManaged::Buffer.

impl AsyncWrite for &UnixStream

async fn write<T>(&mut self, buf: T) -> BufResult<usize, T>

where T: IoBuf,

Write some bytes from the buffer into this source and return a BufResult, consisting of the buffer and a usize indicating how many bytes were written.

async fn write_vectored<T>(&mut self, buf: T) -> BufResult<usize, T>

where T: IoVectoredBuf,

Like write, except that it write bytes from a buffer implements IoVectoredBuf into the source.

async fn flush(&mut self) -> Result<(), Error>

Attempts to flush the object, ensuring that any buffered data reach their destination.

async fn shutdown(&mut self) -> Result<(), Error>

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

impl AsyncWrite for UnixStream

async fn write<T>(&mut self, buf: T) -> BufResult<usize, T>

where T: IoBuf,

Write some bytes from the buffer into this source and return a BufResult, consisting of the buffer and a usize indicating how many bytes were written.

async fn write_vectored<T>(&mut self, buf: T) -> BufResult<usize, T>

where T: IoVectoredBuf,

Like write, except that it write bytes from a buffer implements IoVectoredBuf into the source.

async fn flush(&mut self) -> Result<(), Error>

Attempts to flush the object, ensuring that any buffered data reach their destination.

async fn shutdown(&mut self) -> Result<(), Error>

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

impl AsyncWriteAncillary for &UnixStream

async fn write_with_ancillary<T, C>( &mut self, buffer: T, control: C, ) -> BufResult<usize, (T, C)>

where T: IoBuf, C: IoBuf,

Write data with ancillary data from an owned buffer.

async fn write_vectored_with_ancillary<T, C>( &mut self, buffer: T, control: C, ) -> BufResult<usize, (T, C)>

where T: IoVectoredBuf, C: IoBuf,

Write data with ancillary data from a vectored buffer.

impl AsyncWriteAncillary for UnixStream

Example

Send and receive a file descriptor over a Unix socket pair using SCM_RIGHTS:

use std::os::unix::io::RawFd;

use compio_io::ancillary::*;
use compio_net::UnixStream;

const BUF_SIZE: usize = ancillary_space::<RawFd>();

// Create a socket pair.
let (std_a, std_b) = std::os::unix::net::UnixStream::pair().unwrap();
let mut a = UnixStream::from_std(std_a).unwrap();
let mut b = UnixStream::from_std(std_b).unwrap();

// Pass fd 0 (stdin) as ancillary data via SCM_RIGHTS.
let mut ctrl_send = AncillaryBuf::<BUF_SIZE>::new();
let mut builder = ctrl_send.builder();
builder
    .push(libc::SOL_SOCKET, libc::SCM_RIGHTS, &(0 as RawFd))
    .unwrap();

// Send the payload together with the ancillary data.
a.write_with_ancillary(b"hello", ctrl_send).await.0.unwrap();

// Receive on the other end.
let payload = Vec::with_capacity(5);
let ctrl_recv = AncillaryBuf::<BUF_SIZE>::new();
let ((_, ctrl_len), (payload, ctrl_recv)) =
    b.read_with_ancillary(payload, ctrl_recv).await.unwrap();

assert_eq!(&payload[..], b"hello");

// Parse the received ancillary messages.
let mut iter = unsafe { AncillaryIter::new(&ctrl_recv[..ctrl_len]) };
let msg = iter.next().unwrap();
assert_eq!(msg.level(), libc::SOL_SOCKET);
assert_eq!(msg.ty(), libc::SCM_RIGHTS);
// The kernel duplicates the fd, so the received value may differ.
let _received_fd = unsafe { msg.data::<RawFd>() };
assert!(iter.next().is_none());

async fn write_with_ancillary<T, C>( &mut self, buffer: T, control: C, ) -> BufResult<usize, (T, C)>

where T: IoBuf, C: IoBuf,

Write data with ancillary data from an owned buffer.

async fn write_vectored_with_ancillary<T, C>( &mut self, buffer: T, control: C, ) -> BufResult<usize, (T, C)>

where T: IoVectoredBuf, C: IoBuf,

Write data with ancillary data from a vectored buffer.

impl AsyncWriteAncillaryZerocopy for &UnixStream

type BufferReadyFuture<T: IoBuf, C: IoBuf> = Extract<Zerocopy<SendMsgZc<[T; 1], C, SharedFd<Socket>>>, T, C>

The future that will be resolved when the buffer is safe to be reused.

type VectoredBufferReadyFuture<T: IoVectoredBuf, C: IoBuf> = Zerocopy<SendMsgZc<T, C, SharedFd<Socket>>>

The future that will be resolved when the vectored buffer is safe to be reused.

async fn write_zerocopy_with_ancillary<T, C>( &mut self, buf: T, control: C, ) -> BufResult<usize, <&UnixStream as AsyncWriteAncillaryZerocopy>::BufferReadyFuture<T, C>>

where T: IoBuf, C: IoBuf,

Write some bytes from buffer into this source using the underlying zero-copy mechanism. It returns a result of the underlying write operation and a future that will be resolved when the buffer is safe to be reused.

async fn write_zerocopy_vectored_with_ancillary<T, C>( &mut self, buf: T, control: C, ) -> BufResult<usize, <&UnixStream as AsyncWriteAncillaryZerocopy>::VectoredBufferReadyFuture<T, C>>

where T: IoVectoredBuf, C: IoBuf,

Like write_zerocopy_with_ancillary, except that it writes from a buffer implements IoVectoredBuf into the source.

impl AsyncWriteAncillaryZerocopy for UnixStream

type BufferReadyFuture<T: IoBuf, C: IoBuf> = Extract<Zerocopy<SendMsgZc<[T; 1], C, SharedFd<Socket>>>, T, C>

The future that will be resolved when the buffer is safe to be reused.

type VectoredBufferReadyFuture<T: IoVectoredBuf, C: IoBuf> = Zerocopy<SendMsgZc<T, C, SharedFd<Socket>>>

The future that will be resolved when the vectored buffer is safe to be reused.

async fn write_zerocopy_with_ancillary<T, C>( &mut self, buf: T, control: C, ) -> BufResult<usize, <UnixStream as AsyncWriteAncillaryZerocopy>::BufferReadyFuture<T, C>>

where T: IoBuf, C: IoBuf,

Write some bytes from buffer into this source using the underlying zero-copy mechanism. It returns a result of the underlying write operation and a future that will be resolved when the buffer is safe to be reused.

async fn write_zerocopy_vectored_with_ancillary<T, C>( &mut self, buf: T, control: C, ) -> BufResult<usize, <UnixStream as AsyncWriteAncillaryZerocopy>::VectoredBufferReadyFuture<T, C>>

where T: IoVectoredBuf, C: IoBuf,

Like write_zerocopy_with_ancillary, except that it writes from a buffer implements IoVectoredBuf into the source.

impl AsyncWriteZerocopy for &UnixStream

type BufferReadyFuture<T: IoBuf> = Zerocopy<SendZc<T, SharedFd<Socket>>>

The future that will be resolved when the buffer is safe to be reused.

type VectoredBufferReadyFuture<T: IoVectoredBuf> = Zerocopy<SendVectoredZc<T, SharedFd<Socket>>>

The future that will be resolved when the vectored buffer is safe to be reused.

async fn write_zerocopy<T>( &mut self, buf: T, ) -> BufResult<usize, <&UnixStream as AsyncWriteZerocopy>::BufferReadyFuture<T>>

where T: IoBuf,

Write some bytes from buffer into this source using the underlying zero-copy mechanism. It returns a result of the underlying write operation and a future that will be resolved when the buffer is safe to be reused.

async fn write_zerocopy_vectored<T>( &mut self, buf: T, ) -> BufResult<usize, <&UnixStream as AsyncWriteZerocopy>::VectoredBufferReadyFuture<T>>

where T: IoVectoredBuf,

Like write_zerocopy, except that it writes from a buffer implements IoVectoredBuf into the source.

impl AsyncWriteZerocopy for UnixStream

type BufferReadyFuture<T: IoBuf> = Zerocopy<SendZc<T, SharedFd<Socket>>>

The future that will be resolved when the buffer is safe to be reused.

type VectoredBufferReadyFuture<T: IoVectoredBuf> = Zerocopy<SendVectoredZc<T, SharedFd<Socket>>>

The future that will be resolved when the vectored buffer is safe to be reused.

async fn write_zerocopy<T>( &mut self, buf: T, ) -> BufResult<usize, <UnixStream as AsyncWriteZerocopy>::BufferReadyFuture<T>>

where T: IoBuf,

Write some bytes from buffer into this source using the underlying zero-copy mechanism. It returns a result of the underlying write operation and a future that will be resolved when the buffer is safe to be reused.

async fn write_zerocopy_vectored<T>( &mut self, buf: T, ) -> BufResult<usize, <UnixStream as AsyncWriteZerocopy>::VectoredBufferReadyFuture<T>>

where T: IoVectoredBuf,

Like write_zerocopy, except that it writes from a buffer implements IoVectoredBuf into the source.

impl Clone for UnixStream

fn clone(&self) -> UnixStream

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for UnixStream

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl FromRawFd for UnixStream

Available on Unix only.

unsafe fn from_raw_fd(fd: i32) -> UnixStream

Constructs a new instance of Self from the given raw file descriptor.

impl<'a> Splittable for &'a UnixStream

type ReadHalf = ReadHalf<'a, UnixStream>

The type of the read half, which normally implements AsyncRead or AsyncReadAt.

type WriteHalf = WriteHalf<'a, UnixStream>

The type of the write half, which normally implements AsyncWrite or AsyncWriteAt.

fn split( self, ) -> (<&'a UnixStream as Splittable>::ReadHalf, <&'a UnixStream as Splittable>::WriteHalf)

Consumes self and returns a tuple containing separate read and write halves.

impl<'a> Splittable for &'a mut UnixStream

type ReadHalf = ReadHalf<'a, UnixStream>

The type of the read half, which normally implements AsyncRead or AsyncReadAt.

type WriteHalf = WriteHalf<'a, UnixStream>

The type of the write half, which normally implements AsyncWrite or AsyncWriteAt.

fn split( self, ) -> (<&'a mut UnixStream as Splittable>::ReadHalf, <&'a mut UnixStream as Splittable>::WriteHalf)

Consumes self and returns a tuple containing separate read and write halves.

impl Splittable for UnixStream

type ReadHalf = UnixStream

The type of the read half, which normally implements AsyncRead or AsyncReadAt.

type WriteHalf = UnixStream

The type of the write half, which normally implements AsyncWrite or AsyncWriteAt.

fn split( self, ) -> (<UnixStream as Splittable>::ReadHalf, <UnixStream as Splittable>::WriteHalf)

Consumes self and returns a tuple containing separate read and write halves.

impl ToSharedFd<Socket> for UnixStream

fn to_shared_fd(&self) -> SharedFd<Socket>

Return a cloned SharedFd.