pub struct AsyncFd { /* private fields */ }
Expand description
An open file descriptor.
All functions on AsyncFd
are asynchronous and return a Future
.
Implementations§
source§impl AsyncFd
impl AsyncFd
Cancelation of operations, also see the Cancel
trait to cancel specific
operations.
sourcepub const fn cancel_all<'fd>(&'fd self) -> CancelAll<'fd> ⓘ
pub const fn cancel_all<'fd>(&'fd self) -> CancelAll<'fd> ⓘ
Attempt to cancel all in progress operations on this fd.
If the I/O operations were succesfully canceled this returns Ok(n)
,
where n
is the number of operations canceled. The canceled operations
will return ECANCELED
to indicate they were canceled.
If no operations were found, for example if they were already completed,
this will return Ok(0)
.
In general, operations that are interruptible (like socket IO) will get canceled, while disk IO operations cannot be canceled if already started.
§Notes
Due to the lazyness of Future
s it is possible that this will return
Ok(0)
if operations were never polled only to start it after their
first poll.
source§impl AsyncFd
impl AsyncFd
File(system) related system calls.
sourcepub const fn sync_data<'fd>(&'fd self) -> SyncData<'fd> ⓘ
pub const fn sync_data<'fd>(&'fd self) -> SyncData<'fd> ⓘ
This function is similar to sync_all
, except that it may not
synchronize file metadata to the filesystem.
This is intended for use cases that must synchronize content, but don’t need the metadata on disk. The goal of this method is to reduce disk operations.
§Notes
Any uncompleted writes may not be synced to disk.
sourcepub const fn advise<'fd>(
&'fd self,
offset: u64,
length: u32,
advice: c_int
) -> Advise<'fd> ⓘ
pub const fn advise<'fd>( &'fd self, offset: u64, length: u32, advice: c_int ) -> Advise<'fd> ⓘ
Predeclare an access pattern for file data.
Announce an intention to access file data in a specific pattern in the future, thus allowing the kernel to perform appropriate optimizations.
The advice applies to a (not necessarily existent) region starting at offset and extending for len bytes (or until the end of the file if len is 0). The advice is not binding; it merely constitutes an expectation on behalf of the application.
source§impl AsyncFd
impl AsyncFd
I/O system calls.
sourcepub const fn read<'fd, B>(&'fd self, buf: B) -> Read<'fd, B> ⓘwhere
B: BufMut,
pub const fn read<'fd, B>(&'fd self, buf: B) -> Read<'fd, B> ⓘwhere
B: BufMut,
Read from this fd into buf
.
sourcepub const fn read_at<'fd, B>(&'fd self, buf: B, offset: u64) -> Read<'fd, B> ⓘwhere
B: BufMut,
pub const fn read_at<'fd, B>(&'fd self, buf: B, offset: u64) -> Read<'fd, B> ⓘwhere
B: BufMut,
Read from this fd into buf
starting at offset
.
The current file cursor is not affected by this function. This means
that a call read_at(buf, 1024)
with a buffer of 1kb will not
continue reading at 2kb in the next call to read
.
sourcepub const fn read_n<'fd, B>(&'fd self, buf: B, n: usize) -> ReadN<'fd, B> ⓘwhere
B: BufMut,
pub const fn read_n<'fd, B>(&'fd self, buf: B, n: usize) -> ReadN<'fd, B> ⓘwhere
B: BufMut,
Read at least n
bytes from this fd into buf
.
sourcepub const fn read_n_at<'fd, B>(
&'fd self,
buf: B,
offset: u64,
n: usize
) -> ReadN<'fd, B> ⓘwhere
B: BufMut,
pub const fn read_n_at<'fd, B>(
&'fd self,
buf: B,
offset: u64,
n: usize
) -> ReadN<'fd, B> ⓘwhere
B: BufMut,
Read at least n
bytes from this fd into buf
starting at offset
.
The current file cursor is not affected by this function.
sourcepub fn read_vectored<'fd, B, const N: usize>(
&'fd self,
bufs: B
) -> ReadVectored<'fd, B, N> ⓘwhere
B: BufMutSlice<N>,
pub fn read_vectored<'fd, B, const N: usize>(
&'fd self,
bufs: B
) -> ReadVectored<'fd, B, N> ⓘwhere
B: BufMutSlice<N>,
Read from this fd into bufs
.
sourcepub fn read_vectored_at<'fd, B, const N: usize>(
&'fd self,
bufs: B,
offset: u64
) -> ReadVectored<'fd, B, N> ⓘwhere
B: BufMutSlice<N>,
pub fn read_vectored_at<'fd, B, const N: usize>(
&'fd self,
bufs: B,
offset: u64
) -> ReadVectored<'fd, B, N> ⓘwhere
B: BufMutSlice<N>,
Read from this fd into bufs
starting at offset
.
The current file cursor is not affected by this function.
sourcepub fn read_n_vectored<'fd, B, const N: usize>(
&'fd self,
bufs: B,
n: usize
) -> ReadNVectored<'fd, B, N> ⓘwhere
B: BufMutSlice<N>,
pub fn read_n_vectored<'fd, B, const N: usize>(
&'fd self,
bufs: B,
n: usize
) -> ReadNVectored<'fd, B, N> ⓘwhere
B: BufMutSlice<N>,
Read at least n
bytes from this fd into bufs
.
sourcepub fn read_n_vectored_at<'fd, B, const N: usize>(
&'fd self,
bufs: B,
offset: u64,
n: usize
) -> ReadNVectored<'fd, B, N> ⓘwhere
B: BufMutSlice<N>,
pub fn read_n_vectored_at<'fd, B, const N: usize>(
&'fd self,
bufs: B,
offset: u64,
n: usize
) -> ReadNVectored<'fd, B, N> ⓘwhere
B: BufMutSlice<N>,
Read at least n
bytes from this fd into bufs
.
The current file cursor is not affected by this function.
sourcepub const fn write<'fd, B>(&'fd self, buf: B) -> Write<'fd, B> ⓘwhere
B: Buf,
pub const fn write<'fd, B>(&'fd self, buf: B) -> Write<'fd, B> ⓘwhere
B: Buf,
Write buf
to this fd.
sourcepub const fn write_at<'fd, B>(&'fd self, buf: B, offset: u64) -> Write<'fd, B> ⓘwhere
B: Buf,
pub const fn write_at<'fd, B>(&'fd self, buf: B, offset: u64) -> Write<'fd, B> ⓘwhere
B: Buf,
Write buf
to this fd at offset
.
The current file cursor is not affected by this function.
sourcepub const fn write_all<'fd, B>(&'fd self, buf: B) -> WriteAll<'fd, B> ⓘwhere
B: Buf,
pub const fn write_all<'fd, B>(&'fd self, buf: B) -> WriteAll<'fd, B> ⓘwhere
B: Buf,
Write all of buf
to this fd.
sourcepub const fn write_all_at<'fd, B>(
&'fd self,
buf: B,
offset: u64
) -> WriteAll<'fd, B> ⓘwhere
B: Buf,
pub const fn write_all_at<'fd, B>(
&'fd self,
buf: B,
offset: u64
) -> WriteAll<'fd, B> ⓘwhere
B: Buf,
Write all of buf
to this fd at offset
.
The current file cursor is not affected by this function.
sourcepub fn write_vectored<'fd, B, const N: usize>(
&'fd self,
bufs: B
) -> WriteVectored<'fd, B, N> ⓘwhere
B: BufSlice<N>,
pub fn write_vectored<'fd, B, const N: usize>(
&'fd self,
bufs: B
) -> WriteVectored<'fd, B, N> ⓘwhere
B: BufSlice<N>,
Write bufs
to this file.
sourcepub fn write_vectored_at<'fd, B, const N: usize>(
&'fd self,
bufs: B,
offset: u64
) -> WriteVectored<'fd, B, N> ⓘwhere
B: BufSlice<N>,
pub fn write_vectored_at<'fd, B, const N: usize>(
&'fd self,
bufs: B,
offset: u64
) -> WriteVectored<'fd, B, N> ⓘwhere
B: BufSlice<N>,
Write bufs
to this file at offset
.
The current file cursor is not affected by this function.
sourcepub fn write_all_vectored<'fd, B, const N: usize>(
&'fd self,
bufs: B
) -> WriteAllVectored<'fd, B, N> ⓘwhere
B: BufSlice<N>,
pub fn write_all_vectored<'fd, B, const N: usize>(
&'fd self,
bufs: B
) -> WriteAllVectored<'fd, B, N> ⓘwhere
B: BufSlice<N>,
Write all bufs
to this file.
sourcepub fn write_all_vectored_at<'fd, B, const N: usize>(
&'fd self,
bufs: B,
offset: u64
) -> WriteAllVectored<'fd, B, N> ⓘwhere
B: BufSlice<N>,
pub fn write_all_vectored_at<'fd, B, const N: usize>(
&'fd self,
bufs: B,
offset: u64
) -> WriteAllVectored<'fd, B, N> ⓘwhere
B: BufSlice<N>,
Write all bufs
to this file at offset
.
The current file cursor is not affected by this function.
sourcepub const fn splice_to<'fd>(
&'fd self,
target: RawFd,
length: u32,
flags: c_int
) -> Splice<'fd> ⓘ
pub const fn splice_to<'fd>( &'fd self, target: RawFd, length: u32, flags: c_int ) -> Splice<'fd> ⓘ
Splice length
bytes to target
fd.
See the splice(2)
manual for correct usage.
sourcepub const fn splice_to_at<'fd>(
&'fd self,
offset: u64,
target: RawFd,
target_offset: u64,
length: u32,
flags: c_int
) -> Splice<'fd> ⓘ
pub const fn splice_to_at<'fd>( &'fd self, offset: u64, target: RawFd, target_offset: u64, length: u32, flags: c_int ) -> Splice<'fd> ⓘ
Same as AsyncFd::splice_to
, but starts reading data at offset
from
the file (instead of the current position of the read cursor) and starts
writing at target_offset
to target
.
sourcepub const fn splice_from<'fd>(
&'fd self,
target: RawFd,
length: u32,
flags: c_int
) -> Splice<'fd> ⓘ
pub const fn splice_from<'fd>( &'fd self, target: RawFd, length: u32, flags: c_int ) -> Splice<'fd> ⓘ
Splice length
bytes from target
fd.
See the splice(2)
manual for correct usage.
sourcepub const fn splice_from_at<'fd>(
&'fd self,
offset: u64,
target: RawFd,
target_offset: u64,
length: u32,
flags: c_int
) -> Splice<'fd> ⓘ
pub const fn splice_from_at<'fd>( &'fd self, offset: u64, target: RawFd, target_offset: u64, length: u32, flags: c_int ) -> Splice<'fd> ⓘ
Same as AsyncFd::splice_from
, but starts reading writing at offset
to the file (instead of the current position of the write cursor) and
starts reading at target_offset
from target
.
source§impl AsyncFd
impl AsyncFd
Socket related system calls.
sourcepub fn connect<'fd, A>(&'fd self, address: impl Into<Box<A>>) -> Connect<'fd, A> ⓘwhere
A: SocketAddress,
pub fn connect<'fd, A>(&'fd self, address: impl Into<Box<A>>) -> Connect<'fd, A> ⓘwhere
A: SocketAddress,
Initiate a connection on this socket to the specified address.
sourcepub const fn send<'fd, B>(&'fd self, buf: B, flags: c_int) -> Send<'fd, B> ⓘwhere
B: Buf,
pub const fn send<'fd, B>(&'fd self, buf: B, flags: c_int) -> Send<'fd, B> ⓘwhere
B: Buf,
Sends data on the socket to a connected peer.
sourcepub const fn send_zc<'fd, B>(&'fd self, buf: B, flags: c_int) -> Send<'fd, B> ⓘwhere
B: Buf,
pub const fn send_zc<'fd, B>(&'fd self, buf: B, flags: c_int) -> Send<'fd, B> ⓘwhere
B: Buf,
Same as AsyncFd::send
, but tries to avoid making intermediate copies
of buf
.
§Notes
Zerocopy execution is not guaranteed and may fall back to copying. The
request may also fail with EOPNOTSUPP
, when a protocol doesn’t support
zerocopy, in which case users are recommended to use AsyncFd::send
instead.
The Future
only returns once it safe for the buffer to be used again,
for TCP for example this means until the data is ACKed by the peer.
sourcepub const fn send_all<'fd, B>(&'fd self, buf: B) -> SendAll<'fd, B> ⓘwhere
B: Buf,
pub const fn send_all<'fd, B>(&'fd self, buf: B) -> SendAll<'fd, B> ⓘwhere
B: Buf,
Sends all data in buf
on the socket to a connected peer.
Returns io::ErrorKind::WriteZero
if not all bytes could be written.
sourcepub fn send_vectored<'fd, B, const N: usize>(
&'fd self,
bufs: B,
flags: c_int
) -> SendMsg<'fd, B, NoAddress, N> ⓘwhere
B: BufSlice<N>,
pub fn send_vectored<'fd, B, const N: usize>(
&'fd self,
bufs: B,
flags: c_int
) -> SendMsg<'fd, B, NoAddress, N> ⓘwhere
B: BufSlice<N>,
Sends data in bufs
on the socket to a connected peer.
sourcepub fn send_vectored_zc<'fd, B, const N: usize>(
&'fd self,
bufs: B,
flags: c_int
) -> SendMsg<'fd, B, NoAddress, N> ⓘwhere
B: BufSlice<N>,
pub fn send_vectored_zc<'fd, B, const N: usize>(
&'fd self,
bufs: B,
flags: c_int
) -> SendMsg<'fd, B, NoAddress, N> ⓘwhere
B: BufSlice<N>,
Same as AsyncFd::send_vectored
, but tries to avoid making
intermediate copies of buf
.
sourcepub fn send_all_vectored<'fd, B, const N: usize>(
&'fd self,
bufs: B
) -> SendAllVectored<'fd, B, N> ⓘwhere
B: BufSlice<N>,
pub fn send_all_vectored<'fd, B, const N: usize>(
&'fd self,
bufs: B
) -> SendAllVectored<'fd, B, N> ⓘwhere
B: BufSlice<N>,
Sends all data in bufs
on the socket to a connected peer, using
vectored I/O.
Returns io::ErrorKind::WriteZero
if not all bytes could be written.
sourcepub const fn sendto<'fd, B, A>(
&'fd self,
buf: B,
address: A,
flags: c_int
) -> SendTo<'fd, B, A> ⓘwhere
B: Buf,
A: SocketAddress,
pub const fn sendto<'fd, B, A>(
&'fd self,
buf: B,
address: A,
flags: c_int
) -> SendTo<'fd, B, A> ⓘwhere
B: Buf,
A: SocketAddress,
Sends data on the socket to a connected peer.
sourcepub const fn sendto_zc<'fd, B, A>(
&'fd self,
buf: B,
address: A,
flags: c_int
) -> SendTo<'fd, B, A> ⓘwhere
B: Buf,
A: SocketAddress,
pub const fn sendto_zc<'fd, B, A>(
&'fd self,
buf: B,
address: A,
flags: c_int
) -> SendTo<'fd, B, A> ⓘwhere
B: Buf,
A: SocketAddress,
Same as AsyncFd::sendto
, but tries to avoid making intermediate copies
of buf
.
See AsyncFd::send_zc
for additional notes.
sourcepub fn sendto_vectored<'fd, B, A, const N: usize>(
&'fd self,
bufs: B,
address: A,
flags: c_int
) -> SendMsg<'fd, B, A, N> ⓘwhere
B: BufSlice<N>,
A: SocketAddress,
pub fn sendto_vectored<'fd, B, A, const N: usize>(
&'fd self,
bufs: B,
address: A,
flags: c_int
) -> SendMsg<'fd, B, A, N> ⓘwhere
B: BufSlice<N>,
A: SocketAddress,
Sends data in bufs
on the socket to a connected peer.
sourcepub fn sendto_vectored_zc<'fd, B, A, const N: usize>(
&'fd self,
bufs: B,
address: A,
flags: c_int
) -> SendMsg<'fd, B, A, N> ⓘwhere
B: BufSlice<N>,
A: SocketAddress,
pub fn sendto_vectored_zc<'fd, B, A, const N: usize>(
&'fd self,
bufs: B,
address: A,
flags: c_int
) -> SendMsg<'fd, B, A, N> ⓘwhere
B: BufSlice<N>,
A: SocketAddress,
Same as AsyncFd::sendto_vectored
, but tries to avoid making
intermediate copies of buf
.
sourcepub const fn recv<'fd, B>(&'fd self, buf: B, flags: c_int) -> Recv<'fd, B> ⓘwhere
B: BufMut,
pub const fn recv<'fd, B>(&'fd self, buf: B, flags: c_int) -> Recv<'fd, B> ⓘwhere
B: BufMut,
Receives data on the socket from the remote address to which it is connected.
sourcepub const fn multishot_recv<'fd>(
&'fd self,
pool: ReadBufPool,
flags: c_int
) -> MultishotRecv<'fd>
pub const fn multishot_recv<'fd>( &'fd self, pool: ReadBufPool, flags: c_int ) -> MultishotRecv<'fd>
Continuously receive data on the socket from the remote address to which it is connected.
§Notes
This will return ENOBUFS
if no buffer is available in the pool
to
read into.
Be careful when using this as a peer sending a lot data might take up all your buffers from your pool!
sourcepub const fn recv_n<'fd, B>(&'fd self, buf: B, n: usize) -> RecvN<'fd, B> ⓘwhere
B: BufMut,
pub const fn recv_n<'fd, B>(&'fd self, buf: B, n: usize) -> RecvN<'fd, B> ⓘwhere
B: BufMut,
Receives at least n
bytes on the socket from the remote address to
which it is connected.
sourcepub fn recv_vectored<'fd, B, const N: usize>(
&'fd self,
bufs: B,
flags: c_int
) -> RecvVectored<'fd, B, N> ⓘwhere
B: BufMutSlice<N>,
pub fn recv_vectored<'fd, B, const N: usize>(
&'fd self,
bufs: B,
flags: c_int
) -> RecvVectored<'fd, B, N> ⓘwhere
B: BufMutSlice<N>,
Receives data on the socket from the remote address to which it is connected, using vectored I/O.
sourcepub fn recv_n_vectored<'fd, B, const N: usize>(
&'fd self,
bufs: B,
n: usize
) -> RecvNVectored<'fd, B, N> ⓘwhere
B: BufMutSlice<N>,
pub fn recv_n_vectored<'fd, B, const N: usize>(
&'fd self,
bufs: B,
n: usize
) -> RecvNVectored<'fd, B, N> ⓘwhere
B: BufMutSlice<N>,
Receives at least n
bytes on the socket from the remote address to
which it is connected, using vectored I/O.
sourcepub fn recvfrom<'fd, B, A>(
&'fd self,
buf: B,
flags: c_int
) -> RecvFrom<'fd, B, A> ⓘwhere
B: BufMut,
A: SocketAddress,
pub fn recvfrom<'fd, B, A>(
&'fd self,
buf: B,
flags: c_int
) -> RecvFrom<'fd, B, A> ⓘwhere
B: BufMut,
A: SocketAddress,
Receives data on the socket and returns the source address.
sourcepub fn recvfrom_vectored<'fd, B, A, const N: usize>(
&'fd self,
bufs: B,
flags: c_int
) -> RecvFromVectored<'fd, B, A, N> ⓘwhere
B: BufMutSlice<N>,
A: SocketAddress,
pub fn recvfrom_vectored<'fd, B, A, const N: usize>(
&'fd self,
bufs: B,
flags: c_int
) -> RecvFromVectored<'fd, B, A, N> ⓘwhere
B: BufMutSlice<N>,
A: SocketAddress,
Receives data on the socket and the source address using vectored I/O.
sourcepub const fn shutdown<'fd>(&'fd self, how: Shutdown) -> Shutdown<'fd> ⓘ
pub const fn shutdown<'fd>(&'fd self, how: Shutdown) -> Shutdown<'fd> ⓘ
Shuts down the read, write, or both halves of this connection.
sourcepub fn accept<'fd, A>(&'fd self) -> Accept<'fd, A> ⓘ
pub fn accept<'fd, A>(&'fd self) -> Accept<'fd, A> ⓘ
Accept a new socket stream (AsyncFd
).
If an accepted stream is returned, the remote address of the peer is returned along with it.
sourcepub fn accept4<'fd, A>(&'fd self, flags: c_int) -> Accept<'fd, A> ⓘ
pub fn accept4<'fd, A>(&'fd self, flags: c_int) -> Accept<'fd, A> ⓘ
Accept a new socket stream (AsyncFd
) setting flags
on the accepted
socket.
Also see AsyncFd::accept
.
sourcepub const fn multishot_accept<'fd>(&'fd self) -> MultishotAccept<'fd>
pub const fn multishot_accept<'fd>(&'fd self) -> MultishotAccept<'fd>
Accept multiple socket streams.
This is not the same as calling AsyncFd::accept
in a loop as this
uses a multishot operation, which means only a single operation is
created kernel side, making this more efficient.
sourcepub const fn multishot_accept4<'fd>(
&'fd self,
flags: c_int
) -> MultishotAccept<'fd>
pub const fn multishot_accept4<'fd>( &'fd self, flags: c_int ) -> MultishotAccept<'fd>
Accept a new socket stream (AsyncFd
) setting flags
on the accepted
socket.
Also see AsyncFd::multishot_accept
.
sourcepub fn socket_option<'fd, T>(
&'fd self,
level: c_int,
optname: c_int
) -> SocketOption<'fd, T> ⓘ
pub fn socket_option<'fd, T>( &'fd self, level: c_int, optname: c_int ) -> SocketOption<'fd, T> ⓘ
Get socket option.
At the time of writing this limited to the SOL_SOCKET
level.
§Safety
The caller must ensure that T
is the valid type for the option.
sourcepub fn set_socket_option<'fd, T>(
&'fd self,
level: c_int,
optname: c_int,
optvalue: T
) -> SetSocketOption<'fd, T> ⓘ
pub fn set_socket_option<'fd, T>( &'fd self, level: c_int, optname: c_int, optvalue: T ) -> SetSocketOption<'fd, T> ⓘ
Set socket option.
At the time of writing this limited to the SOL_SOCKET
level.
§Safety
The caller must ensure that T
is the valid type for the option.
source§impl AsyncFd
impl AsyncFd
sourcepub const fn new(fd: OwnedFd, sq: SubmissionQueue) -> AsyncFd
pub const fn new(fd: OwnedFd, sq: SubmissionQueue) -> AsyncFd
Create a new AsyncFd
.
sourcepub unsafe fn from_raw_fd(fd: RawFd, sq: SubmissionQueue) -> AsyncFd
pub unsafe fn from_raw_fd(fd: RawFd, sq: SubmissionQueue) -> AsyncFd
Create a new AsyncFd
from a RawFd
.
§Safety
The caller must ensure that fd
is valid and that it’s no longer used
by anything other than the returned AsyncFd
.