Struct Handle 

pub struct Handle<T> { /* private fields */ }

An IO object (a socket, a pipe, a file) whose operations run on nuclei’s shards.

Send and Sync exactly when the object is.

std’s calls through Deref

Deref hands the object out for its own methods (socket options, addresses), and the handle’s methods of the same name take their place where it has them (connect, send, linger, …). A few of std’s calls reached through it go around the handle, so around the bytes it read ahead and the ones it wrote behind, or block its shard:

• shutdown shuts the halves at once, ahead of the bytes still behind, which then never reach the peer; shut waits for them first.
• set_nonblocking(false) makes the driver’s own calls on the object block the shard’s thread, and every task of the shard with them.
• take_error takes the error the socket holds, which the handle’s connect in progress or its next operation would have answered.
• Read and Write on a shared reference to the object (&TcpStream, &UnixStream) read past the bytes read ahead and write ahead of the bytes written behind, and answer WouldBlock where the handle’s own reads and writes wait. Called on the handle with std’s traits in scope (stream.read(&mut buf)), they reach the object through DerefMut, after the wait of get_mut.

use std::net::TcpListener;
use nuclei::Handle;

let listener = Handle::new(TcpListener::bind("127.0.0.1:0").unwrap()).unwrap();
assert!(listener.local_addr().unwrap().port() > 0);

Implementations

impl Handle<File>

pub async fn copy_range_to( &self, to: &Handle<File>, from_offset: u64, to_offset: u64, len: u64, ) -> Result<u64>

Copies up to len bytes from this file at from_offset to to at to_offset and answers how many were copied: fewer only where this file ends, and zero at its end. Neither file’s cursor is used or moved.

On Linux the bytes move in the kernel (copy_file_range(2)), in jobs of the blocking pool that each take a chunk of at most 16 MiB, so no job holds a pool thread for a whole copy. Where the kernel cannot copy between the two files, or the system has no such call (macOS, Windows, the other unix), the bytes go through a buffer of the runtime’s pool, one buffer a job.

The copy waits for the writes accepted before it on both files. For to it is a write: a read at its cursor made after the copy sees the bytes, and a future dropped while a chunk is out leaves that chunk to to, which every later call of to waits for; the chunks after it are not made. A failure after some bytes were copied is not reported: the count is, and the next call meets the failure again.

A file that is not a regular file (a pipe, a terminal) gets the system’s answer to one call.

Errors

InvalidInput when the end of either range is past the largest offset a file can have, or when both handles name one file and the ranges overlap; otherwise the system’s own error, among them that of a handle that cannot be read or written.

impl Handle<File>

pub async fn read_many_at<B>( &self, reads: Vec<(B, u64)>, ) -> Vec<(Result<usize>, B)>

where B: IoBufMut,

Reads at each offset of reads into the spare capacity of its buffer, after the bytes it holds, and gives every buffer back in the order of reads with its read’s result, as read_at_owned answers one: the bytes that came, zero at the end of the file or for a buffer with no spare capacity. The reads are made at once, in any order: on io_uring together, in the shard ring’s one submission, at most 64 out at a time; elsewhere as jobs of the blocking pool, as many at a time.

The reads see every write accepted at the cursor before the call, and every positional write that returned before it. Each read is one call of the system’s positional read into its buffer itself, never copied. If the future is dropped, the reads still out are left to end by themselves, and their buffers go with them.

Errors

Each read’s own, as read_at_owned’s. On a stream (a pipe, a terminal) the file has no offset to read at, and every read answers the system’s error for that.

impl Handle<File>

pub async fn read_at(&self, buf: &mut [u8], offset: u64) -> Result<usize>

Reads at offset into buf and answers how many bytes came, zero at the end of the file, as std’s FileExt::read_at does (on Windows seek_read, after which the system’s own position of the file is past the bytes read, as std documents; the handle’s cursor never moves).

The handle’s cursor and the reads and writes at it are left as they are, and any number of positional calls may run at once on one handle. The read sees every write accepted at the cursor before it, and every positional write that returned before it.

The bytes come through a buffer of the runtime’s pool, at most 64 KiB a call (a short read, as read_at may answer). On a file opened for direct IO the call reads exactly buf.len() bytes at offset, into memory placed in its page as buf is, so the kernel refuses (with EINVAL) exactly what it would refuse of buf itself. read_at_owned reads into the caller’s own buffer with no copy.

Errors

As the system’s positional read: on a stream (a pipe, a terminal) the file has no offset to read at.

pub async fn write_at(&self, buf: &[u8], offset: u64) -> Result<usize>

Writes buf at offset and answers how many bytes landed, as std’s FileExt::write_at does (on Windows seek_write, after which the system’s own position of the file is past the bytes written; the handle’s cursor never moves). On Linux a file opened to append takes the bytes at its end whatever the offset, as pwrite(2) does there.

The write lands after every write accepted at the cursor before it, and before any write the handle accepts after it returned; positional writes running at once land in any order, as pwrite from two threads does. If the future is dropped while the write is out, it still lands, and every later call of the handle waits for it.

The bytes go through a buffer of the runtime’s pool, at most 64 KiB a call (a short write, as write_at may answer). On a file opened for direct IO the call writes exactly buf at offset, from memory placed in its page as buf is, so the kernel refuses (with EINVAL) exactly what it would refuse of buf itself. write_at_owned writes from the caller’s own buffer with no copy.

Errors

As the system’s positional write.

pub async fn read_exact_at(&self, buf: &mut [u8], offset: u64) -> Result<()>

Reads exactly buf.len() bytes at offset, as std’s FileExt::read_exact_at does, with read_at.

Errors

UnexpectedEof when the file ends first (the bytes read so far are in buf), or the first error of a read.

pub async fn write_all_at(&self, buf: &[u8], offset: u64) -> Result<()>

Writes all of buf at offset, as std’s FileExt::write_all_at does, with write_at.

Errors

WriteZero when a write takes nothing, or the first error of a write.

pub async fn read_at_owned<B>(&self, buf: B, offset: u64) -> (Result<usize>, B)

where B: IoBufMut,

Reads at offset into the spare capacity of buf, after the bytes it holds, in one call of the system’s positional read, and gives buf back with how many bytes came: zero at the end of the file, or when buf has no spare capacity. The bytes are read into buf itself, never copied; on a file opened for direct IO the kernel’s alignment rules apply to buf’s own memory, which an AlignedBuf aligns. buf is any IoBufMut. Otherwise as read_at.

pub async fn write_at_owned<B>(&self, buf: B, offset: u64) -> (Result<usize>, B)

where B: IoBuf,

Writes all of buf at offset and gives it back with its length once the bytes landed. They are written from buf itself, never copied; on a file opened for direct IO the kernel’s alignment rules apply to buf’s own memory, which an AlignedBuf aligns. If the future is dropped while the write is out, it still lands, buf going with it. buf is any IoBuf. Otherwise as write_at.

impl Handle<File>

pub async fn create(path: impl AsRef<Path>) -> Result<Handle<File>>

Opens the file at path for writing, creating it or cutting it down to nothing.

pub async fn create_new(path: impl AsRef<Path>) -> Result<Handle<File>>

Creates the file at path and opens it for reading and writing, failing if it exists.

pub fn options() -> OpenOptions

The options to open a file with.

pub async fn sync_all(&self) -> Result<()>

Writes the file’s data and metadata through to the device, as std’s File::sync_all does, once every write accepted before the call (at the cursor, or positional and returned) landed. On io_uring the sync is an operation of the shard’s ring (IORING_OP_FSYNC); elsewhere a job of the blocking pool.

Errors

A write that failed (reported here as by a flush), or the sync’s own failure. Once a sync of the handle failed, every later one fails with that error: the system reports a failure to write data back once, so a later sync that succeeded would not mean the data reached the device. Open the file again to start over.

pub async fn sync_data(&self) -> Result<()>

Writes the file’s data through to the device, and the metadata a read needs, as std’s File::sync_data does (IORING_FSYNC_DATASYNC on io_uring); otherwise as sync_all.

Errors

As sync_all.

pub async fn sync_range(&self, offset: u64, len: u64) -> Result<()>

Writes back the dirty data of the len bytes of the file from offset and waits for it (len of zero: to the end of the file), as Linux’s sync_file_range does, once every write accepted before the call landed. On io_uring this is an operation of the shard’s ring (IORING_OP_SYNC_FILE_RANGE, for a range its length field holds, else a job of the blocking pool).

This is not a durability guarantee: it writes no metadata and flushes no cache of the device, so a crash may still lose the data. Use sync_data for that. On the systems that have no such call (macOS, Windows, other unix) it does what sync_data does for the whole file, which is stronger and covers the range.

Errors

As sync_all: a write that failed, or the call’s own failure, which every later sync of the handle then repeats (the system reports a write-back error to one call only).

pub async fn allocate( &self, offset: u64, len: u64, mode: Allocate, ) -> Result<()>

Changes the space the len bytes of the file from offset use, as mode says: reserves it, keeps the length, frees it, or zeroes it. The call is a write of the range: it lands after every write accepted at the cursor before it and every positional write that returned before it, a read at the cursor made after it sees what it did, and a future dropped while the call is out leaves it to the file, which every later call of the handle waits for. On io_uring it is an operation of the shard’s ring (fallocate(2)); elsewhere a job of the blocking pool (fcntl on macOS, DeviceIoControl and SetFileInformationByHandle on Windows).

A system that cannot do mode answers Unsupported (macOS cannot zero a range in place), and a file system may refuse a mode as the system says.

Errors

InvalidInput when the end of the range is past the largest offset a file can have; otherwise the system’s own answer, among them that of an empty range, a handle that cannot be written, and a stream.

pub async fn set_len(&self, len: u64) -> Result<()>

Sets the file’s length: cut down, or grown with zeros. The cursor stays where it is. Bytes of the file read ahead before the cut are never handed out after it.

pub async fn metadata(&self) -> Result<Metadata>

The file’s metadata.

pub async fn set_permissions(&self, perm: Permissions) -> Result<()>

Sets the file’s permissions.

pub async fn set_times(&self, times: FileTimes) -> Result<()>

Sets the file’s access and modification times.

pub async fn set_modified(&self, time: SystemTime) -> Result<()>

Sets the file’s modification time.

pub async fn try_clone(&self) -> Result<Handle<File>>

A second handle to the same open file, with a cursor of its own starting where the file’s offset is (writes in flight landed first).

impl Handle<File>

pub async fn lock_file(&self, shared: bool) -> Result<()>

Locks the whole file, shared for any number of holders if shared, else exclusively for one, as std’s File::lock_shared and File::lock do, waiting for the lock on the blocking pool so the worker is free meanwhile. The lock is advisory, and it is released by unlock_file or when the file is closed.

If the future is dropped while it waits, the lock is never left held with nobody to release it: a job that had not started is cancelled, and one that got the lock gives it back.

std’s own File::lock, reached through Deref, blocks the worker thread that makes it.

Errors

The system’s own, as std’s.

pub async fn try_lock_file(&self, shared: bool) -> Result<(), TryLockError>

Locks the whole file if it is free now, shared if shared, else exclusively, as std’s File::try_lock_shared and File::try_lock do. The call does not wait, so it is made on the calling thread.

Errors

WouldBlock when another holder has the lock, else the system’s own error, as std’s.

pub async fn unlock_file(&self) -> Result<()>

Releases the lock this file holds, as std’s File::unlock does, once every write accepted before the call landed (as a flush waits for them), so a holder that wrote under the lock lets go only after its bytes are in the file.

Errors

A write that failed (reported here as by a flush), or the system’s own error. The lock is released even when a write failed.

impl Handle<File>

A file’s calls. std’s own File::lock, FileExt::read_at and FileExt::write_at (on Windows seek_read and seek_write), reached through Deref, block the worker thread that makes them. Use the async calls instead: lock_file, try_lock_file and unlock_file, read_at and write_at, and, with no copy of the bytes, read_at_owned and write_at_owned.

pub async fn open(p: impl AsRef<Path>) -> Result<Handle<StdFile>>

Opens the file at p for reading: on the calling thread when it is a regular file on a local file system and the kernel’s caches answer at once (Linux), on the blocking pool otherwise.

Errors

As File::open.

pub async fn read_owned<B>(&self, buf: B) -> (Result<usize>, B)

where B: IoBufMut,

Reads at the cursor into the spare capacity of buf, after the bytes it holds, and gives buf back with how many bytes came: zero at the end of the file, or when buf has no spare capacity. The bytes are read into buf itself, never copied, once the writes before the read landed.

If the future is dropped before it completes, the cursor stays where it was. buf is any IoBufMut: a Vec<u8>, an AlignedBuf for a file opened for direct IO, or a type of the caller’s.

pub async fn write_owned<B>(&self, buf: B) -> (Result<usize>, B)

where B: IoBuf,

Writes all of buf at the cursor (at the end, for a file opened to append), after the writes before it, and gives it back with its length once the bytes reached the file. They are written from buf itself, never copied.

If the future is dropped before it completes, the write is withdrawn while it still waits for the writes before it, and lands whole, in its place, once it started. buf is any IoBuf, as for read_owned.

pub async fn read_vectored_owned<V>(&self, bufs: V) -> (Result<usize>, V)

where V: IoVecBufMut,

Reads at the cursor into the spare capacity of bufs, after the bytes each holds, filling each buffer’s room before the next one’s, as read_owned reads into one, and gives bufs back with how many bytes came: zero at the end of the file, or when no buffer has spare capacity. One call of the kernel takes every room (preadv, or IORING_OP_READV on the ring); on Windows, which has no vectored read of a buffered file, one read a buffer, in order, until one comes short.

pub async fn write_vectored_owned<V>(&self, bufs: V) -> (Result<usize>, V)

where V: IoVecBuf,

Writes all of the bytes of bufs, each buffer’s in order, at the cursor as one write (as write_owned writes one buffer), and gives bufs back with how many bytes that was. No other write of the handle comes between two of them. One call of the kernel takes every buffer left (pwritev, writev for a file opened to append, or IORING_OP_WRITEV on the ring; on Windows, which has no vectored write of a buffered file, one write a buffer, in order), from the buffers themselves, never copied; on a file opened for direct IO each buffer’s memory and length meet the kernel’s alignment rules on their own.

impl<T: IoObject> Handle<T>

pub fn new(io: T) -> Result<Handle<T>>

Takes io over: what kind of object it is (a socket, a file, a pipe) decides how its IO runs. On unix it is made non-blocking.

Errors

When the object cannot be inspected or set up.

impl<T> Handle<T>

pub fn get_ref(&self) -> &T

The IO object.

pub fn get_mut(&mut self) -> &mut T

The IO object, to change. Bytes written behind reach the kernel first (this waits for them), then the handle’s IO stops, and every call still out on its descriptor ends; its next operation takes the object as it is then (another descriptor discards what the old one left).

pub fn into_inner(self) -> T

The IO object, back from the handle, once the bytes written behind reached the kernel and every call still out on its descriptor ended (this waits for them). Bytes the handle read ahead and had not handed out are dropped with it.

impl Handle<TcpStream>

pub async fn shut(&self, how: Shutdown) -> Result<()>

Shuts down the reading half of the stream, its writing half, or both, as std’s shutdown does, once the bytes written behind reached the kernel.

Write and Both wait until the kernel took every byte the handle accepted, so the peer reads all of them before the end of the stream, then ask the kernel; a peer that never reads holds them up, as it would hold up std’s blocking writes. Read leaves the writes alone. After Read or Both, reads answer as std’s do: Linux hands out what came before the shutdown, then the end; macOS and Windows end at once, so there the handle drops what it read ahead.

It is not named shutdown, so that stream.shutdown(how) still calls std’s own, reached through Deref, which shuts the halves at once: the bytes still behind then never reach the peer, and it reads the end before them.

Errors

The error that stopped the bytes written behind, and what shutdown(2) answers: a half shut already on macOS (NotConnected), as std’s.

impl Handle<UnixStream>

pub async fn shut(&self, how: Shutdown) -> Result<()>

Shuts down the reading half of the stream, its writing half, or both, as std’s shutdown does, once the bytes written behind reached the kernel.

Write and Both wait until the kernel took every byte the handle accepted, so the peer reads all of them before the end of the stream, then ask the kernel; a peer that never reads holds them up, as it would hold up std’s blocking writes. Read leaves the writes alone. After Read or Both, reads answer as std’s do: Linux hands out what came before the shutdown, then the end; macOS and Windows end at once, so there the handle drops what it read ahead.

It is not named shutdown, so that stream.shutdown(how) still calls std’s own, reached through Deref, which shuts the halves at once: the bytes still behind then never reach the peer, and it reads the end before them.

Errors

The error that stopped the bytes written behind, and what shutdown(2) answers: a half shut already on macOS (NotConnected), as std’s.

impl Handle<TcpStream>

pub fn abort(self) -> Result<()>

Closes the stream now and resets the connection: SO_LINGER goes to zero, the bytes written behind and the buffers lent to writes still out are dropped, nothing lingers, and the close sends the peer a reset, so its reads fail with ConnectionReset rather than end as if every byte came. The kernel drops what its own queue holds too.

A plain drop instead delivers the bytes behind, for at most the runtime’s write_behind_linger, and ends the stream cleanly; one whose time runs out resets the connection the same way.

Errors

When SO_LINGER cannot be set: the stream then closes as a drop closes it.

impl Handle<TcpStream>

pub async fn send_file(&self, file: &File, offset: u64, len: u64) -> Result<u64>

Sends up to len bytes of file, from offset, to the stream, and returns how many it sent: fewer than len when the file ends first.

Where the system has sendfile(2) (Linux, Android, macOS, FreeBSD) or TransmitFile (Windows, through the completion port) the bytes go from the page cache to the socket in the kernel and never enter user space; elsewhere (and on a Windows provider without TransmitFile) they are read at offset and written, which works the same and copies. The file’s own cursor does not move. Bytes written to the stream before the call go out first; do not write to the stream while the call runs, or its bytes may land between the call’s.

If the future is dropped before it completes, the stream has got a prefix of the range, in order and whole, and a chunk of at most the runtime’s send_file_chunk (one MiB by default) may still be on its way.

Errors

An error the stream or the file met (also the error of an earlier write behind), InvalidInput for a range past what an offset can name, and file not being a regular file. The bytes sent before an error are not counted.

impl Handle<UnixStream>

pub async fn send_file(&self, file: &File, offset: u64, len: u64) -> Result<u64>

Sends up to len bytes of file, from offset, to the stream, and returns how many it sent: fewer than len when the file ends first.

Where the system has sendfile(2) (Linux, Android, macOS, FreeBSD) or TransmitFile (Windows, through the completion port) the bytes go from the page cache to the socket in the kernel and never enter user space; elsewhere (and on a Windows provider without TransmitFile) they are read at offset and written, which works the same and copies. The file’s own cursor does not move. Bytes written to the stream before the call go out first; do not write to the stream while the call runs, or its bytes may land between the call’s.

If the future is dropped before it completes, the stream has got a prefix of the range, in order and whole, and a chunk of at most the runtime’s send_file_chunk (one MiB by default) may still be on its way.

Errors

An error the stream or the file met (also the error of an earlier write behind), InvalidInput for a range past what an offset can name, and file not being a regular file. The bytes sent before an error are not counted.

impl Handle<TcpStream>

pub async fn read_owned<B>(&self, buf: B) -> (Result<usize>, B)

where B: IoBufMut,

Reads into the spare capacity of buf, after the bytes it holds, and gives buf back with how many bytes came: zero at the end of the stream, or when buf has no spare capacity. The driver reads into buf itself, so the bytes are never copied.

If the future is dropped before it completes, bytes the driver read into buf stay with the handle for its next read, so none is lost. buf is any IoBufMut.

pub async fn read_vectored_owned<V>(&self, bufs: V) -> (Result<usize>, V)

where V: IoVecBufMut,

Reads into the spare capacity of bufs, after the bytes each holds, filling each buffer’s room before the next one’s, and gives bufs back with how many bytes came: zero at the end of the stream, or when no buffer has spare capacity. One read of the kernel takes every room at once (readv, a recvmsg of several buffers, a WSARecv of several WSABUFs), as read_owned lends one buffer: the bytes land in the buffers themselves, never copied. Bytes another read left behind are copied in instead, in the same order.

pub async fn readable(&self) -> Result<()>

Waits until a read would end at once.

Errors

When the stream cannot be watched.

pub fn poll_read_ready(&self, cx: &mut Context<'_>) -> Poll<Result<()>>

Polls until a read would end at once.

Errors

When the stream cannot be watched.

pub fn try_read(&self, buf: &mut [u8]) -> Result<usize>

Reads what came ahead into buf without waiting; zero at the end of the stream.

Errors

WouldBlock when nothing came yet (the driver goes on reading, so a later call finds what comes), and as read(2).

pub fn try_read_vectored(&self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize>

Reads what came ahead into bufs without waiting, as try_read.

Errors

As try_read.

impl Handle<TcpStream>

pub async fn write_owned<B>(&self, buf: B) -> (Result<usize>, B)

where B: IoBuf,

Writes all of buf and gives it back with its length. The driver writes from buf itself, so the bytes are never copied, and the write ends once the kernel took the last of them.

If the future is dropped before it completes, the stream gets buf whole or not at all: a write none of which went out is withdrawn, and one that started is finished by the driver. On Windows a TCP write is always finished: there a cancelled send may have handed bytes to the stack while it says it took none. buf is any IoBuf.

pub async fn write_vectored_owned<V>(&self, bufs: V) -> (Result<usize>, V)

where V: IoVecBuf,

Writes all of the bytes of bufs, each buffer’s in order, as one write, and gives bufs back with how many bytes that was. No other write of the stream comes between two of them. Each call of the kernel takes every buffer left at once (writev, a sendmsg of several buffers, a WSASend of several WSABUFs), from the buffers themselves, never copied; a call the kernel takes part of goes on from the first byte it did not take. If the future is dropped, as with write_owned: the stream gets all of the bytes or none of them.

pub async fn writable(&self) -> Result<()>

Waits until a write would be taken at once.

Errors

When the stream cannot be watched.

pub fn poll_write_ready(&self, cx: &mut Context<'_>) -> Poll<Result<()>>

Polls until a write would be taken at once.

Errors

When the stream cannot be watched.

pub fn try_write(&self, buf: &[u8]) -> Result<usize>

Hands buf to the write-behind without waiting; returns how many bytes it took.

Errors

WouldBlock when the write-behind has no room, and the error that stopped earlier bytes.

pub fn try_write_vectored(&self, bufs: &[IoSlice<'_>]) -> Result<usize>

Hands the bytes of bufs, in order, to the write-behind without waiting, as try_write.

Errors

As try_write.

impl Handle<TcpStream>

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

The stream’s two halves, borrowed: to read on one task and write on another. Nothing is allocated.

pub fn into_split(self) -> (OwnedReadHalf<TcpStream>, OwnedWriteHalf<TcpStream>)

The stream’s two halves, owning it together; see OwnedReadHalf::reunite.

pub async fn ready(&self, interest: Interest) -> Result<Ready>

Waits until some of interest is ready, and says what is.

Errors

When the stream cannot be watched.

impl Handle<TcpStream>

pub async fn write_zero_copy<B>(&self, buf: B) -> (Result<usize>, Released<B>)

where B: IoBuf,

Writes all of buf as write_owned does, with the kernel’s zero-copy send where it has one, and returns the write’s result with a Released that gives buf back once the kernel let go of it.

The write ends once the kernel took the last byte, as write_owned’s does, but the kernel keeps reading buf until the peer acknowledged every byte; only then does the Released resolve to it. So a peer that writes before it reads cannot hold the write up, and writes pipeline: the next one may start while earlier buffers are still out.

A write of less than the runtime’s zero_copy_threshold (1 MiB by default), where copying costs less, and every write on epoll, kqueue, I/O completion ports or an io_uring kernel without zero-copy sends (or without memory it may lock for them), is copied by the kernel as write_owned’s is, and its Released is ready at once. So is a write served by a ring only its own thread may reap: a thread’s own shard (a stream polled by block_on outside the runtime’s workers), or the workers of a runtime built with handoff_after(None). Their rings could not be handed to another thread, which a buffer still out when the thread stops would need.

If the future is dropped before it completes, the stream gets buf whole or not at all, as with write_owned. Either way buf is dropped only once the kernel let go of it. buf is any IoBuf.

impl Handle<UnixStream>

pub async fn read_owned<B>(&self, buf: B) -> (Result<usize>, B)

where B: IoBufMut,

Reads into the spare capacity of buf, after the bytes it holds, and gives buf back with how many bytes came: zero at the end of the stream, or when buf has no spare capacity. The driver reads into buf itself, so the bytes are never copied.

If the future is dropped before it completes, bytes the driver read into buf stay with the handle for its next read, so none is lost. buf is any IoBufMut.

pub async fn read_vectored_owned<V>(&self, bufs: V) -> (Result<usize>, V)

where V: IoVecBufMut,

Reads into the spare capacity of bufs, after the bytes each holds, filling each buffer’s room before the next one’s, and gives bufs back with how many bytes came: zero at the end of the stream, or when no buffer has spare capacity. One read of the kernel takes every room at once (readv, a recvmsg of several buffers, a WSARecv of several WSABUFs), as read_owned lends one buffer: the bytes land in the buffers themselves, never copied. Bytes another read left behind are copied in instead, in the same order.

pub async fn readable(&self) -> Result<()>

Waits until a read would end at once.

Errors

When the stream cannot be watched.

pub fn poll_read_ready(&self, cx: &mut Context<'_>) -> Poll<Result<()>>

Polls until a read would end at once.

Errors

When the stream cannot be watched.

pub fn try_read(&self, buf: &mut [u8]) -> Result<usize>

Reads what came ahead into buf without waiting; zero at the end of the stream.

Errors

WouldBlock when nothing came yet (the driver goes on reading, so a later call finds what comes), and as read(2).

pub fn try_read_vectored(&self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize>

Reads what came ahead into bufs without waiting, as try_read.

Errors

As try_read.

impl Handle<UnixStream>

pub async fn write_owned<B>(&self, buf: B) -> (Result<usize>, B)

where B: IoBuf,

Writes all of buf and gives it back with its length. The driver writes from buf itself, so the bytes are never copied, and the write ends once the kernel took the last of them.

If the future is dropped before it completes, the stream gets buf whole or not at all: a write none of which went out is withdrawn, and one that started is finished by the driver. On Windows a TCP write is always finished: there a cancelled send may have handed bytes to the stack while it says it took none. buf is any IoBuf.

pub async fn write_vectored_owned<V>(&self, bufs: V) -> (Result<usize>, V)

where V: IoVecBuf,

Writes all of the bytes of bufs, each buffer’s in order, as one write, and gives bufs back with how many bytes that was. No other write of the stream comes between two of them. Each call of the kernel takes every buffer left at once (writev, a sendmsg of several buffers, a WSASend of several WSABUFs), from the buffers themselves, never copied; a call the kernel takes part of goes on from the first byte it did not take. If the future is dropped, as with write_owned: the stream gets all of the bytes or none of them.

pub async fn writable(&self) -> Result<()>

Waits until a write would be taken at once.

Errors

When the stream cannot be watched.

pub fn poll_write_ready(&self, cx: &mut Context<'_>) -> Poll<Result<()>>

Polls until a write would be taken at once.

Errors

When the stream cannot be watched.

pub fn try_write(&self, buf: &[u8]) -> Result<usize>

Hands buf to the write-behind without waiting; returns how many bytes it took.

Errors

WouldBlock when the write-behind has no room, and the error that stopped earlier bytes.

pub fn try_write_vectored(&self, bufs: &[IoSlice<'_>]) -> Result<usize>

Hands the bytes of bufs, in order, to the write-behind without waiting, as try_write.

Errors

As try_write.

impl Handle<UnixStream>

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

The stream’s two halves, borrowed: to read on one task and write on another. Nothing is allocated.

pub fn into_split( self, ) -> (OwnedReadHalf<UnixStream>, OwnedWriteHalf<UnixStream>)

The stream’s two halves, owning it together; see OwnedReadHalf::reunite.

pub async fn ready(&self, interest: Interest) -> Result<Ready>

Waits until some of interest is ready, and says what is.

Errors

When the stream cannot be watched.

impl Handle<PipeReader>

pub async fn read_owned<B>(&self, buf: B) -> (Result<usize>, B)

where B: IoBufMut,

Reads into the spare capacity of buf, after the bytes it holds, and gives buf back with how many bytes came: zero at the end of the stream, or when buf has no spare capacity. The driver reads into buf itself, so the bytes are never copied.

If the future is dropped before it completes, bytes the driver read into buf stay with the handle for its next read, so none is lost. buf is any IoBufMut.

pub async fn read_vectored_owned<V>(&self, bufs: V) -> (Result<usize>, V)

where V: IoVecBufMut,

Reads into the spare capacity of bufs, after the bytes each holds, filling each buffer’s room before the next one’s, and gives bufs back with how many bytes came: zero at the end of the stream, or when no buffer has spare capacity. One read of the kernel takes every room at once (readv, a recvmsg of several buffers, a WSARecv of several WSABUFs), as read_owned lends one buffer: the bytes land in the buffers themselves, never copied. Bytes another read left behind are copied in instead, in the same order.

pub async fn readable(&self) -> Result<()>

Waits until a read would end at once.

Errors

When the stream cannot be watched.

pub fn poll_read_ready(&self, cx: &mut Context<'_>) -> Poll<Result<()>>

Polls until a read would end at once.

Errors

When the stream cannot be watched.

pub fn try_read(&self, buf: &mut [u8]) -> Result<usize>

Reads what came ahead into buf without waiting; zero at the end of the stream.

Errors

WouldBlock when nothing came yet (the driver goes on reading, so a later call finds what comes), and as read(2).

pub fn try_read_vectored(&self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize>

Reads what came ahead into bufs without waiting, as try_read.

Errors

As try_read.

impl Handle<PipeWriter>

pub async fn write_owned<B>(&self, buf: B) -> (Result<usize>, B)

where B: IoBuf,

Writes all of buf and gives it back with its length. The driver writes from buf itself, so the bytes are never copied, and the write ends once the kernel took the last of them.

If the future is dropped before it completes, the stream gets buf whole or not at all: a write none of which went out is withdrawn, and one that started is finished by the driver. On Windows a TCP write is always finished: there a cancelled send may have handed bytes to the stack while it says it took none. buf is any IoBuf.

pub async fn write_vectored_owned<V>(&self, bufs: V) -> (Result<usize>, V)

where V: IoVecBuf,

Writes all of the bytes of bufs, each buffer’s in order, as one write, and gives bufs back with how many bytes that was. No other write of the stream comes between two of them. Each call of the kernel takes every buffer left at once (writev, a sendmsg of several buffers, a WSASend of several WSABUFs), from the buffers themselves, never copied; a call the kernel takes part of goes on from the first byte it did not take. If the future is dropped, as with write_owned: the stream gets all of the bytes or none of them.

pub async fn writable(&self) -> Result<()>

Waits until a write would be taken at once.

Errors

When the stream cannot be watched.

pub fn poll_write_ready(&self, cx: &mut Context<'_>) -> Poll<Result<()>>

Polls until a write would be taken at once.

Errors

When the stream cannot be watched.

pub fn try_write(&self, buf: &[u8]) -> Result<usize>

Hands buf to the write-behind without waiting; returns how many bytes it took.

Errors

WouldBlock when the write-behind has no room, and the error that stopped earlier bytes.

pub fn try_write_vectored(&self, bufs: &[IoSlice<'_>]) -> Result<usize>

Hands the bytes of bufs, in order, to the write-behind without waiting, as try_write.

Errors

As try_write.

impl Handle<TcpListener>

pub async fn bind<A: ToSocketAddrs>(addr: A) -> Result<Handle<TcpListener>>

A listener bound to the first of the addresses addr names that it can bind.

Errors

The last address’s error when none could be bound, or the lookup’s.

pub async fn accept(&self) -> Result<(Handle<TcpStream>, SocketAddr)>

The next connection, with its peer’s address.

On macOS an accept that finds the process out of descriptors closes the connection it took off the backlog, as the system’s own does; the next ones fail with the same error and take none until a descriptor is free.

Errors

As accept(2): a connection reset before it was taken, or the process out of descriptors.

pub fn poll_accept( &self, cx: &mut Context<'_>, ) -> Poll<Result<(Handle<TcpStream>, SocketAddr)>>

Polls for the next connection, with its peer’s address: Pending with cx’s waker kept until one comes.

Errors

As accept.

pub fn incoming( &self, ) -> impl Stream<Item = Result<Handle<TcpStream>>> + Send + Unpin + '_

The connections as they come, without their addresses; the stream never ends, and an error is one of its items.

pub async fn accept_multi(&self) -> Result<TcpStreamGenerator>

The connections as they come, from a stream that owns its own copy of the listener, so it may outlive this handle. A connection reset before it was taken is skipped, and so is the process having no descriptor left to accept into: the stream waits, with a growing pause, until there is one, and the connections wait in the listener’s backlog (on macOS but for the one the first accept to find none took, which the system closes, as accept says). Any other error ends the stream, and TcpStreamGenerator::take_error says what it was.

On io_uring the stream keeps one accept armed for every connection that comes, so it takes connections ahead of its polls; those it took and never yielded close when it drops, as a listener’s own backlog does when the last copy of the listener closes.

Errors

When the listener’s descriptor cannot be copied.

impl Handle<TcpStream>

pub async fn connect<A: ToSocketAddrs>( sock_addrs: A, ) -> Result<Handle<TcpStream>>

A stream connected to the first of sock_addrs that takes the connection.

Errors

The last address’s error when none took it, or the lookup’s.

pub async fn send(&self, buf: &[u8]) -> Result<usize>

Sends bytes; returns how many were taken (into the write-behind, as for AsyncWrite).

Errors

As send(2), or the error that stopped earlier bytes.

pub async fn recv(&self, buf: &mut [u8]) -> Result<usize>

Receives bytes; zero at the end of the stream.

Errors

As recv(2).

pub async fn peek(&self, buf: &mut [u8]) -> Result<usize>

Looks at the bytes the next receive returns, without taking them.

Errors

As recv(2) with MSG_PEEK.

pub fn poll_peek( &self, cx: &mut Context<'_>, buf: &mut ReadBuf<'_>, ) -> Poll<Result<usize>>

Polls for the bytes the next receive returns, into the unfilled part of buf, without taking them; buf advances by what came.

Errors

As recv(2) with MSG_PEEK.

pub fn linger(&self) -> Result<Option<Duration>>

SO_LINGER: how long a close waits for unsent data, None if it does not wait.

pub fn set_linger(&self, linger: Option<Duration>) -> Result<()>

Sets SO_LINGER: with Some(time) a close waits up to time (whole seconds) for unsent data; with None it returns at once and the system sends what is left.

pub fn set_zero_linger(&self) -> Result<()>

Sets SO_LINGER to zero: the close drops unsent data and resets the connection.

impl Handle<TcpStream>

pub fn set_keepalive_timing(&self, keepalive: TcpKeepalive) -> Result<()>

Turns keepalive probes on (SO_KEEPALIVE), timed as keepalive says (TCP_KEEPIDLE, TCP_KEEPINTVL, TCP_KEEPCNT; macOS calls the first TCP_KEEPALIVE).

Errors

Unsupported where the system has no such options, InvalidInput for a value past what it takes, and what setsockopt(2) answers (a zero time or count).

pub fn keepalive_timing(&self) -> Result<TcpKeepalive>

The keepalive’s timing: the system’s values where none was set.

Errors

Unsupported where the system has no such options.

pub fn set_user_timeout(&self, timeout: Option<Duration>) -> Result<()>

Sets TCP_USER_TIMEOUT (Linux): how long sent bytes may go unacknowledged before the connection is dropped, in whole milliseconds; None or zero leaves it to the system.

Errors

Unsupported off Linux, InvalidInput for a time past what the system takes.

pub fn user_timeout(&self) -> Result<Option<Duration>>

TCP_USER_TIMEOUT (Linux), None where the system’s own applies.

Errors

Unsupported off Linux.

impl Handle<TcpStream>

pub fn set_quickack(&self, quickack: bool) -> Result<()>

Sets TCP_QUICKACK (Linux): with true the stream acknowledges at once rather than waiting to send it with data. The kernel turns it off again as it sees fit, so it is set again where it matters.

Errors

Unsupported off Linux.

pub fn quickack(&self) -> Result<bool>

TCP_QUICKACK (Linux): whether the stream acknowledges at once now.

Errors

Unsupported off Linux.

impl Handle<UdpSocket>

pub async fn bind<A: ToSocketAddrs>(addr: A) -> Result<Handle<UdpSocket>>

A socket bound to the first of the addresses addr names that it can bind.

Errors

The last address’s error when none could be bound, or the lookup’s.

pub async fn connect<A: ToSocketAddrs>( sock_addrs: A, ) -> Result<Handle<UdpSocket>>

A socket on an ephemeral local port, connected to the first of sock_addrs it can connect to: send and recv then talk to that peer only.

This makes a socket: it is called as UdpSocket::connect(addr). Called on a socket, socket.connect(addr) is std’s own UdpSocket::connect, reached through Deref, which connects that socket in place and looks a name up with a blocking call, on the calling thread (a shard’s, with every task of it). Connect a socket in place with a numeric address, or look the name up first with lookup_host.

Errors

The last address’s error when none worked, or the lookup’s.

pub async fn send(&self, buf: &[u8]) -> Result<usize>

Sends a datagram to the connected peer.

Errors

As send(2) of this datagram. On Windows the completion port sends it after the call returns, so a failure the stack finds only then (its size is checked first) is the next send’s error.

pub async fn recv(&self, buf: &mut [u8]) -> Result<usize>

Receives a datagram from the connected peer; what does not fit buf is cut.

Errors

As recv(2).

pub async fn send_owned<B>(&self, buf: B) -> (Result<usize>, B)

where B: IoBuf,

Sends all of buf as one datagram to the connected peer and gives it back with its length. The driver sends from buf itself, so the bytes are never copied.

If the future is dropped before it completes, the datagram is sent whole or not at all: one the driver has not handed to the kernel is withdrawn, and one already handed over goes out. buf is any IoBuf.

pub async fn send_to_owned<A, B>(&self, buf: B, addr: A) -> (Result<usize>, B)

where A: ToSocketAddrs, B: IoBuf,

Sends all of buf as one datagram to the first address addr names and gives it back with its length, as send_owned sends to the connected peer.

pub async fn recv_owned<B>(&self, buf: B) -> (Result<usize>, B)

where B: IoBufMut,

Receives a datagram from the connected peer into the spare capacity of buf, after the bytes it holds, and gives buf back with the datagram’s length. The driver receives into buf itself, so the bytes are never copied; what does not fit is cut.

If the future is dropped before it completes, a datagram the driver received into buf stays with the socket for its next receive, so none is lost. buf is any IoBufMut.

pub async fn recv_from_owned<B>( &self, buf: B, ) -> (Result<(usize, SocketAddr)>, B)

where B: IoBufMut,

Receives a datagram with its sender’s address into the spare capacity of buf, as recv_owned.

pub async fn peek(&self, buf: &mut [u8]) -> Result<usize>

Looks at the next datagram without taking it.

Errors

As recv(2) with MSG_PEEK.

pub async fn send_to<A: ToSocketAddrs>( &self, buf: &[u8], addr: A, ) -> Result<usize>

Sends a datagram to the first address addr names.

Errors

As sendto(2) of this datagram (on Windows, as for send), or the lookup’s.

pub async fn recv_from(&self, buf: &mut [u8]) -> Result<(usize, SocketAddr)>

Receives a datagram with its sender’s address.

Errors

As recvfrom(2).

pub async fn peek_from(&self, buf: &mut [u8]) -> Result<(usize, SocketAddr)>

Looks at the next datagram and its sender without taking it.

Errors

As recvfrom(2) with MSG_PEEK.

pub fn poll_recv_from( &self, cx: &mut Context<'_>, buf: &mut ReadBuf<'_>, ) -> Poll<Result<SocketAddr>>

Polls for a datagram and its sender, received into the unfilled part of buf, which advances by its length; what does not fit is cut. Pending with cx’s waker kept until one comes.

Errors

As recvfrom(2).

pub fn poll_send_to( &self, cx: &mut Context<'_>, buf: &[u8], target: SocketAddr, ) -> Poll<Result<usize>>

Polls to send a datagram to target, Pending with cx’s waker kept while one is still queued.

Errors

As sendto(2) of this datagram (on Windows, as for send).

pub async fn readable(&self) -> Result<()>

Waits until a receive would end at once: a datagram came, or an error (which the receive reports).

Errors

When the socket cannot be watched.

pub async fn writable(&self) -> Result<()>

Waits until a send would be taken at once.

Errors

When the socket cannot be watched.

pub async fn ready(&self, interest: Interest) -> Result<Ready>

Waits until some of interest is ready, and says what is.

Errors

When the socket cannot be watched.

pub fn poll_recv_ready(&self, cx: &mut Context<'_>) -> Poll<Result<()>>

Polls until a receive would end at once.

Errors

When the socket cannot be watched.

pub fn poll_send_ready(&self, cx: &mut Context<'_>) -> Poll<Result<()>>

Polls until a send would be taken at once.

Errors

When the socket cannot be watched.

pub fn try_send(&self, buf: &[u8]) -> Result<usize>

Sends a datagram to the connected peer without waiting.

Errors

WouldBlock when a datagram is still queued, and as send(2).

pub fn try_recv(&self, buf: &mut [u8]) -> Result<usize>

Receives a datagram from the connected peer without waiting; what does not fit buf is cut.

Errors

WouldBlock when none came yet, and as recv(2).

pub fn try_peek(&self, buf: &mut [u8]) -> Result<usize>

Looks at the next datagram without taking it or waiting.

Errors

WouldBlock when none came yet, and as recv(2) with MSG_PEEK.

pub fn try_send_to(&self, buf: &[u8], target: SocketAddr) -> Result<usize>

Sends a datagram to target without waiting.

Errors

WouldBlock when a datagram is still queued, and as sendto(2).

pub fn try_recv_from(&self, buf: &mut [u8]) -> Result<(usize, SocketAddr)>

Receives a datagram and its sender’s address without waiting.

Errors

WouldBlock when none came yet, and as recvfrom(2).

pub fn try_peek_from(&self, buf: &mut [u8]) -> Result<(usize, SocketAddr)>

Looks at the next datagram and its sender without taking it or waiting.

Errors

WouldBlock when none came yet, and as recvfrom(2) with MSG_PEEK.

pub async fn peek_sender(&self) -> Result<SocketAddr>

The sender of the next datagram, which stays to be received.

Errors

As recvfrom(2) with MSG_PEEK.

pub fn poll_peek_sender(&self, cx: &mut Context<'_>) -> Poll<Result<SocketAddr>>

Polls for the sender of the next datagram, which stays to be received. At most one byte of it is copied, and dropped.

Errors

As recvfrom(2) with MSG_PEEK.

pub async fn recv_buf(&self, buf: &mut ReadBuf<'_>) -> Result<usize>

Receives a datagram from the connected peer into the unfilled part of buf, which advances by its length; what does not fit is cut.

Errors

As recv(2).

pub async fn recv_buf_from( &self, buf: &mut ReadBuf<'_>, ) -> Result<(usize, SocketAddr)>

Receives a datagram and its sender’s address into the unfilled part of buf, which advances by its length; what does not fit is cut.

Errors

As recvfrom(2).

impl Handle<UnixListener>

pub fn bind<P: AsRef<Path>>(path: P) -> Result<Handle<UnixListener>>

A listener bound to path.

Errors

As UnixListener::bind.

pub fn bind_addr(addr: &UnixSocketAddr) -> Result<Handle<UnixListener>>

A listener bound to addr: a path, or on Linux a name in the abstract namespace.

Errors

As UnixListener::bind_addr.

pub async fn accept(&self) -> Result<(Handle<UnixStream>, UnixSocketAddr)>

The next connection, with its peer’s address. On macOS an accept that finds the process out of descriptors closes the connection it took, and the next ones take none until a descriptor is free, as a TCP listener’s do.

Errors

As accept(2).

pub fn incoming( &self, ) -> impl Stream<Item = Result<Handle<UnixStream>>> + Send + Unpin + '_

The connections as they come, without their addresses; the stream never ends, and an error is one of its items.

impl Handle<UnixStream>

pub async fn connect<P: AsRef<Path>>(path: P) -> Result<Handle<UnixStream>>

A stream connected to the listener at path.

Errors

As connect(2).

pub async fn connect_addr(addr: &UnixSocketAddr) -> Result<Handle<UnixStream>>

A stream connected to the listener at addr: a path, or on Linux a name in the abstract namespace.

Errors

As connect(2); an unnamed address names no listener.

pub fn peer_cred(&self) -> Result<UCred>

The credentials of the process at the other end, as the connection was made.

Errors

When the system cannot tell them.

pub fn pair() -> Result<(Handle<UnixStream>, Handle<UnixStream>)>

Two streams connected to each other.

Errors

As socketpair(2).

pub async fn send(&self, buf: &[u8]) -> Result<usize>

Sends bytes; returns how many were taken.

Errors

As send(2), or the error that stopped earlier bytes.

pub async fn recv(&self, buf: &mut [u8]) -> Result<usize>

Receives bytes; zero at the end of the stream.

Errors

As recv(2).

pub async fn peek(&self, buf: &mut [u8]) -> Result<usize>

Looks at the bytes the next receive returns, without taking them.

Errors

As recv(2) with MSG_PEEK.

impl Handle<UnixDatagram>

pub fn bind<P: AsRef<Path>>(path: P) -> Result<Handle<UnixDatagram>>

A socket bound to path.

Errors

As UnixDatagram::bind.

pub fn bind_addr(addr: &UnixSocketAddr) -> Result<Handle<UnixDatagram>>

A socket bound to addr: a path, or on Linux a name in the abstract namespace.

Errors

As UnixDatagram::bind_addr.

pub fn unbound() -> Result<Handle<UnixDatagram>>

A socket bound to no address: it sends with send_to, or to the peer its connect names.

Errors

When the system has no socket to give.

pub fn pair() -> Result<(Handle<UnixDatagram>, Handle<UnixDatagram>)>

Two sockets connected to each other.

Errors

As socketpair(2).

pub async fn send(&self, buf: &[u8]) -> Result<usize>

Sends a datagram to the connected peer.

Errors

As send(2) of this datagram.

pub async fn recv(&self, buf: &mut [u8]) -> Result<usize>

Receives a datagram from the connected peer; what does not fit buf is cut.

Errors

As recv(2).

pub async fn send_owned<B>(&self, buf: B) -> (Result<usize>, B)

where B: IoBuf,

Sends all of buf as one datagram to the connected peer and gives it back with its length. The driver sends from buf itself, so the bytes are never copied.

If the future is dropped before it completes, the datagram is sent whole or not at all: one the driver has not handed to the kernel is withdrawn, and one already handed over goes out. buf is any IoBuf.

pub async fn send_to_owned<P, B>(&self, buf: B, path: P) -> (Result<usize>, B)

where P: AsRef<Path>, B: IoBuf,

Sends all of buf as one datagram to the socket at path and gives it back with its length, as send_owned sends to the connected peer.

pub async fn recv_owned<B>(&self, buf: B) -> (Result<usize>, B)

where B: IoBufMut,

Receives a datagram from the connected peer into the spare capacity of buf, after the bytes it holds, and gives buf back with the datagram’s length. The driver receives into buf itself, so the bytes are never copied; what does not fit is cut.

If the future is dropped before it completes, a datagram the driver received into buf stays with the socket for its next receive, so none is lost. buf is any IoBufMut.

pub async fn recv_from_owned<B>( &self, buf: B, ) -> (Result<(usize, UnixSocketAddr)>, B)

where B: IoBufMut,

Receives a datagram with its sender’s address into the spare capacity of buf, as recv_owned.

pub async fn peek(&self, buf: &mut [u8]) -> Result<usize>

Looks at the next datagram without taking it.

Errors

As recv(2) with MSG_PEEK.

pub async fn send_to<P: AsRef<Path>>( &self, buf: &[u8], path: P, ) -> Result<usize>

Sends a datagram to the socket at path.

Errors

As sendto(2) of this datagram.

pub async fn recv_from(&self, buf: &mut [u8]) -> Result<(usize, UnixSocketAddr)>

Receives a datagram with its sender’s address.

Errors

As recvfrom(2).

pub async fn peek_from(&self, buf: &mut [u8]) -> Result<(usize, UnixSocketAddr)>

Looks at the next datagram and its sender without taking it.

Errors

As recvfrom(2) with MSG_PEEK.

pub async fn readable(&self) -> Result<()>

Waits until a receive would end at once: a datagram came, or an error (which the receive reports).

Errors

When the socket cannot be watched.

pub async fn writable(&self) -> Result<()>

Waits until a send would be taken at once.

Errors

When the socket cannot be watched.

pub async fn ready(&self, interest: Interest) -> Result<Ready>

Waits until some of interest is ready, and says what is.

Errors

When the socket cannot be watched.

pub fn poll_recv_ready(&self, cx: &mut Context<'_>) -> Poll<Result<()>>

Polls until a receive would end at once.

Errors

When the socket cannot be watched.

pub fn poll_send_ready(&self, cx: &mut Context<'_>) -> Poll<Result<()>>

Polls until a send would be taken at once.

Errors

When the socket cannot be watched.

pub fn try_send(&self, buf: &[u8]) -> Result<usize>

Sends a datagram to the connected peer without waiting.

Errors

WouldBlock when a datagram is still queued, and as send(2).

pub fn try_send_to<P: AsRef<Path>>(&self, buf: &[u8], path: P) -> Result<usize>

Sends a datagram to the socket at path without waiting.

Errors

WouldBlock when a datagram is still queued, and as sendto(2).

pub fn try_recv(&self, buf: &mut [u8]) -> Result<usize>

Receives a datagram from the connected peer without waiting; what does not fit buf is cut.

Errors

WouldBlock when none came yet, and as recv(2).

pub fn try_recv_from(&self, buf: &mut [u8]) -> Result<(usize, UnixSocketAddr)>

Receives a datagram and its sender’s address without waiting.

Errors

WouldBlock when none came yet, and as recvfrom(2).

impl Handle<TcpStream>

pub fn try_io<R>( &self, interest: Interest, f: impl FnOnce() -> Result<R>, ) -> Result<R>

Runs f, a call of the caller’s own on the socket (through get_ref or its descriptor), if the socket may be ready for interest, and clears that readiness if f answers WouldBlock. The side then takes its caller’s calls only, until the handle’s own next read or write on it. Nothing is reordered: bytes the handle wrote behind go out first, and data it read ahead must be read before.

Errors

WouldBlock when none of interest may be ready (or bytes written behind are still going out), ResourceBusy when the handle holds data it read ahead, and what f answers.

pub async fn async_io<R>( &self, interest: Interest, f: impl FnMut() -> Result<R>, ) -> Result<R>

Runs f, a call of the caller’s own on the socket, each time it may be ready for interest, until f answers other than WouldBlock, clearing the readiness each time it does; as try_io, bytes written behind go out first.

Errors

ResourceBusy when the handle holds data it read ahead, and what f answers.

impl Handle<UdpSocket>

pub fn try_io<R>( &self, interest: Interest, f: impl FnOnce() -> Result<R>, ) -> Result<R>

Runs f, a call of the caller’s own on the socket (through get_ref or its descriptor), if the socket may be ready for interest, and clears that readiness if f answers WouldBlock. The side then takes its caller’s calls only, until the handle’s own next read or write on it. Nothing is reordered: bytes the handle wrote behind go out first, and data it read ahead must be read before.

Errors

WouldBlock when none of interest may be ready (or bytes written behind are still going out), ResourceBusy when the handle holds data it read ahead, and what f answers.

pub async fn async_io<R>( &self, interest: Interest, f: impl FnMut() -> Result<R>, ) -> Result<R>

Runs f, a call of the caller’s own on the socket, each time it may be ready for interest, until f answers other than WouldBlock, clearing the readiness each time it does; as try_io, bytes written behind go out first.

Errors

ResourceBusy when the handle holds data it read ahead, and what f answers.

impl Handle<UnixStream>

pub fn try_io<R>( &self, interest: Interest, f: impl FnOnce() -> Result<R>, ) -> Result<R>

Runs f, a call of the caller’s own on the socket (through get_ref or its descriptor), if the socket may be ready for interest, and clears that readiness if f answers WouldBlock. The side then takes its caller’s calls only, until the handle’s own next read or write on it. Nothing is reordered: bytes the handle wrote behind go out first, and data it read ahead must be read before.

Errors

WouldBlock when none of interest may be ready (or bytes written behind are still going out), ResourceBusy when the handle holds data it read ahead, and what f answers.

pub async fn async_io<R>( &self, interest: Interest, f: impl FnMut() -> Result<R>, ) -> Result<R>

Runs f, a call of the caller’s own on the socket, each time it may be ready for interest, until f answers other than WouldBlock, clearing the readiness each time it does; as try_io, bytes written behind go out first.

Errors

ResourceBusy when the handle holds data it read ahead, and what f answers.

impl Handle<UnixDatagram>

pub fn try_io<R>( &self, interest: Interest, f: impl FnOnce() -> Result<R>, ) -> Result<R>

Runs f, a call of the caller’s own on the socket (through get_ref or its descriptor), if the socket may be ready for interest, and clears that readiness if f answers WouldBlock. The side then takes its caller’s calls only, until the handle’s own next read or write on it. Nothing is reordered: bytes the handle wrote behind go out first, and data it read ahead must be read before.

Errors

WouldBlock when none of interest may be ready (or bytes written behind are still going out), ResourceBusy when the handle holds data it read ahead, and what f answers.

pub async fn async_io<R>( &self, interest: Interest, f: impl FnMut() -> Result<R>, ) -> Result<R>

Runs f, a call of the caller’s own on the socket, each time it may be ready for interest, until f answers other than WouldBlock, clearing the readiness each time it does; as try_io, bytes written behind go out first.

Errors

ResourceBusy when the handle holds data it read ahead, and what f answers.

Trait Implementations

impl<T: AsFd> AsFd for Handle<T>

Available on Unix only.

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

Borrows the file descriptor.

impl<T: AsRawFd> AsRawFd for Handle<T>

Available on Unix only.

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl<S> AsRef<Handle<S>> for ReadHalf<'_, S>

fn as_ref(&self) -> &Handle<S>

Converts this type into a shared reference of the (usually inferred) input type.

impl<S> AsRef<Handle<S>> for WriteHalf<'_, S>

fn as_ref(&self) -> &Handle<S>

Converts this type into a shared reference of the (usually inferred) input type.

impl<S> AsRef<Handle<S>> for OwnedReadHalf<S>

fn as_ref(&self) -> &Handle<S>

Converts this type into a shared reference of the (usually inferred) input type.

impl<S> AsRef<Handle<S>> for OwnedWriteHalf<S>

fn as_ref(&self) -> &Handle<S>

Converts this type into a shared reference of the (usually inferred) input type.

impl AsyncBufRead for Handle<File>

fn poll_fill_buf( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Result<&[u8]>>

Attempt to return the contents of the internal buffer, filling it with more data from the inner reader if it is empty.

fn consume(self: Pin<&mut Self>, amt: usize)

Tells this buffer that amt bytes have been consumed from the buffer, so they should no longer be returned in calls to poll_read.

impl AsyncRead for Handle<File>

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut [u8], ) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into buf.

fn poll_read_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &mut [IoSliceMut<'_>], ) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into bufs using vectored IO operations.

impl AsyncRead for &Handle<File>

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut [u8], ) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into buf.

fn poll_read_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &mut [IoSliceMut<'_>], ) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into bufs using vectored IO operations.

impl AsyncRead for &Handle<TcpStream>

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut [u8], ) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into buf.

fn poll_read_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &mut [IoSliceMut<'_>], ) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into bufs using vectored IO operations.

impl AsyncRead for Handle<TcpStream>

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut [u8], ) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into buf.

fn poll_read_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &mut [IoSliceMut<'_>], ) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into bufs using vectored IO operations.

impl AsyncRead for &Handle<UnixStream>

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut [u8], ) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into buf.

fn poll_read_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &mut [IoSliceMut<'_>], ) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into bufs using vectored IO operations.

impl AsyncRead for Handle<UnixStream>

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut [u8], ) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into buf.

fn poll_read_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &mut [IoSliceMut<'_>], ) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into bufs using vectored IO operations.

impl AsyncRead for &Handle<PipeReader>

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut [u8], ) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into buf.

fn poll_read_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &mut [IoSliceMut<'_>], ) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into bufs using vectored IO operations.

impl AsyncRead for Handle<PipeReader>

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut [u8], ) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into buf.

fn poll_read_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &mut [IoSliceMut<'_>], ) -> Poll<Result<usize>>

Attempt to read from the AsyncRead into bufs using vectored IO operations.

impl AsyncSeek for Handle<File>

fn poll_seek( self: Pin<&mut Self>, cx: &mut Context<'_>, pos: SeekFrom, ) -> Poll<Result<u64>>

Attempt to seek to an offset, in bytes, in a stream.

impl AsyncWrite for Handle<File>

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize>>

Attempt to write bytes from bufs into the object using vectored IO operations.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

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

fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempt to close the object.

impl AsyncWrite for &Handle<File>

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize>>

Attempt to write bytes from bufs into the object using vectored IO operations.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

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

fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempt to close the object.

impl AsyncWrite for &Handle<TcpStream>

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize>>

Attempt to write bytes from bufs into the object using vectored IO operations.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

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

fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempt to close the object.

impl AsyncWrite for Handle<TcpStream>

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize>>

Attempt to write bytes from bufs into the object using vectored IO operations.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

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

fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempt to close the object.

impl AsyncWrite for &Handle<UnixStream>

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize>>

Attempt to write bytes from bufs into the object using vectored IO operations.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

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

fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempt to close the object.

impl AsyncWrite for Handle<UnixStream>

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize>>

Attempt to write bytes from bufs into the object using vectored IO operations.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

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

fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempt to close the object.

impl AsyncWrite for &Handle<PipeWriter>

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize>>

Attempt to write bytes from bufs into the object using vectored IO operations.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

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

fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempt to close the object.

impl AsyncWrite for Handle<PipeWriter>

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize>>

Attempt to write bytes from bufs into the object using vectored IO operations.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

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

fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempt to close the object.

impl<T: Debug> Debug for Handle<T>

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

Formats the value using the given formatter.

impl<T> Deref for Handle<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T> DerefMut for Handle<T>

fn deref_mut(&mut self) -> &mut T

As Handle::get_mut.

impl<T> Drop for Handle<T>

fn drop(&mut self)

Never waits: the source closes the object once no call can use its descriptor (at once, or as the last lease or the driver lets go of it).

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<T: IntoRawFd> IntoRawFd for Handle<T>

Available on Unix only.

fn into_raw_fd(self) -> RawFd

Consumes this object, returning the raw underlying file descriptor.