Trait tokio::io::AsyncRead [−][src]
Reads bytes from a source.
This trait is analogous to the std::io::Read
trait, but integrates with
the asynchronous task system. In particular, the poll_read
method,
unlike Read::read
, will automatically queue the current task for wakeup
and return if data is not yet available, rather than blocking the calling
thread.
Specifically, this means that the poll_read
function will return one of
the following:
-
Poll::Ready(Ok(n))
means thatn
bytes of data was immediately read and placed into the output buffer, wheren
== 0 implies that EOF has been reached. -
Poll::Pending
means that no data was read into the buffer provided. The I/O object is not currently readable but may become readable in the future. Most importantly, the current future’s task is scheduled to get unparked when the object is readable. This means that likeFuture::poll
you’ll receive a notification when the I/O object is readable again. -
Poll::Ready(Err(e))
for other errors are standard I/O errors coming from the underlying object.
This trait importantly means that the read
method only works in the
context of a future’s task. The object may panic if used outside of a task.
Utilities for working with AsyncRead
values are provided by
AsyncReadExt
.
Required methods
fn poll_read(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
[src]
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
Attempts to read from the AsyncRead
into buf
.
On success, returns Poll::Ready(Ok(num_bytes_read))
.
If no data is available for reading, the method returns
Poll::Pending
and arranges for the current task (via
cx.waker()
) to receive a notification when the object becomes
readable or is closed.
Provided methods
unsafe fn prepare_uninitialized_buffer(
&self,
buf: &mut [MaybeUninit<u8>]
) -> bool
[src]
&self,
buf: &mut [MaybeUninit<u8>]
) -> bool
Prepares an uninitialized buffer to be safe to pass to read
. Returns
true
if the supplied buffer was zeroed out.
While it would be highly unusual, implementations of io::Read
are
able to read data from the buffer passed as an argument. Because of
this, the buffer passed to io::Read
must be initialized memory. In
situations where large numbers of buffers are used, constantly having to
zero out buffers can be expensive.
This function does any necessary work to prepare an uninitialized buffer
to be safe to pass to read
. If read
guarantees to never attempt to
read data out of the supplied buffer, then prepare_uninitialized_buffer
doesn’t need to do any work.
If this function returns true
, then the memory has been zeroed out.
This allows implementations of AsyncRead
which are composed of
multiple subimplementations to efficiently implement
prepare_uninitialized_buffer
.
This function isn’t actually unsafe
to call but unsafe
to implement.
The implementer must ensure that either the whole buf
has been zeroed
or poll_read_buf()
overwrites the buffer without reading it and returns
correct value.
This function is called from poll_read_buf
.
Safety
Implementations that return false
must never read from data slices
that they did not write to.
fn poll_read_buf<B: BufMut>(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut B
) -> Poll<Result<usize>> where
Self: Sized,
[src]
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut B
) -> Poll<Result<usize>> where
Self: Sized,
Pulls some bytes from this source into the specified BufMut
, returning
how many bytes were read.
The buf
provided will have bytes read into it and the internal cursor
will be advanced if any bytes were read. Note that this method typically
will not reallocate the buffer provided.
Implementations on Foreign Types
impl<T: ?Sized + AsyncRead + Unpin> AsyncRead for Box<T>
[src]
unsafe fn prepare_uninitialized_buffer(
&self,
buf: &mut [MaybeUninit<u8>]
) -> bool
[src]
&self,
buf: &mut [MaybeUninit<u8>]
) -> bool
fn poll_read(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
[src]
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
impl<T: ?Sized + AsyncRead + Unpin> AsyncRead for &mut T
[src]
unsafe fn prepare_uninitialized_buffer(
&self,
buf: &mut [MaybeUninit<u8>]
) -> bool
[src]
&self,
buf: &mut [MaybeUninit<u8>]
) -> bool
fn poll_read(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
[src]
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
impl<P> AsyncRead for Pin<P> where
P: DerefMut + Unpin,
P::Target: AsyncRead,
[src]
P: DerefMut + Unpin,
P::Target: AsyncRead,
unsafe fn prepare_uninitialized_buffer(
&self,
buf: &mut [MaybeUninit<u8>]
) -> bool
[src]
&self,
buf: &mut [MaybeUninit<u8>]
) -> bool
fn poll_read(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
[src]
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
impl AsyncRead for &[u8]
[src]
unsafe fn prepare_uninitialized_buffer(
&self,
_buf: &mut [MaybeUninit<u8>]
) -> bool
[src]
&self,
_buf: &mut [MaybeUninit<u8>]
) -> bool
fn poll_read(
self: Pin<&mut Self>,
_cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
[src]
self: Pin<&mut Self>,
_cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
impl<T: AsRef<[u8]> + Unpin> AsyncRead for Cursor<T>
[src]
unsafe fn prepare_uninitialized_buffer(
&self,
_buf: &mut [MaybeUninit<u8>]
) -> bool
[src]
&self,
_buf: &mut [MaybeUninit<u8>]
) -> bool
fn poll_read(
self: Pin<&mut Self>,
_cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
[src]
self: Pin<&mut Self>,
_cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
Implementors
impl AsyncRead for File
[src]
unsafe fn prepare_uninitialized_buffer(
&self,
_buf: &mut [MaybeUninit<u8>]
) -> bool
[src]
&self,
_buf: &mut [MaybeUninit<u8>]
) -> bool
fn poll_read(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
dst: &mut [u8]
) -> Poll<Result<usize>>
[src]
self: Pin<&mut Self>,
cx: &mut Context<'_>,
dst: &mut [u8]
) -> Poll<Result<usize>>
impl AsyncRead for DuplexStream
[src]
fn poll_read(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
[src]
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
impl AsyncRead for Empty
[src]
unsafe fn prepare_uninitialized_buffer(
&self,
_buf: &mut [MaybeUninit<u8>]
) -> bool
[src]
&self,
_buf: &mut [MaybeUninit<u8>]
) -> bool
fn poll_read(
self: Pin<&mut Self>,
_: &mut Context<'_>,
_: &mut [u8]
) -> Poll<Result<usize>>
[src]
self: Pin<&mut Self>,
_: &mut Context<'_>,
_: &mut [u8]
) -> Poll<Result<usize>>
impl AsyncRead for Repeat
[src]
unsafe fn prepare_uninitialized_buffer(
&self,
_buf: &mut [MaybeUninit<u8>]
) -> bool
[src]
&self,
_buf: &mut [MaybeUninit<u8>]
) -> bool
fn poll_read(
self: Pin<&mut Self>,
_: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
[src]
self: Pin<&mut Self>,
_: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
impl AsyncRead for Stdin
[src]
unsafe fn prepare_uninitialized_buffer(
&self,
_buf: &mut [MaybeUninit<u8>]
) -> bool
[src]
&self,
_buf: &mut [MaybeUninit<u8>]
) -> bool
fn poll_read(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
[src]
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
impl AsyncRead for TcpStream
[src]
unsafe fn prepare_uninitialized_buffer(&self, _: &mut [MaybeUninit<u8>]) -> bool
[src]
fn poll_read(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
[src]
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
impl AsyncRead for UnixStream
[src]
unsafe fn prepare_uninitialized_buffer(&self, _: &mut [MaybeUninit<u8>]) -> bool
[src]
fn poll_read(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
[src]
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
impl AsyncRead for tokio::net::tcp::OwnedReadHalf
[src]
unsafe fn prepare_uninitialized_buffer(&self, _: &mut [MaybeUninit<u8>]) -> bool
[src]
fn poll_read(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
[src]
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
impl AsyncRead for tokio::net::tcp::ReadHalf<'_>
[src]
unsafe fn prepare_uninitialized_buffer(&self, _: &mut [MaybeUninit<u8>]) -> bool
[src]
fn poll_read(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
[src]
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
impl AsyncRead for tokio::net::unix::OwnedReadHalf
[src]
unsafe fn prepare_uninitialized_buffer(&self, _: &mut [MaybeUninit<u8>]) -> bool
[src]
fn poll_read(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
[src]
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
impl AsyncRead for tokio::net::unix::ReadHalf<'_>
[src]
unsafe fn prepare_uninitialized_buffer(&self, _: &mut [MaybeUninit<u8>]) -> bool
[src]
fn poll_read(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
[src]
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
impl AsyncRead for ChildStderr
[src]
unsafe fn prepare_uninitialized_buffer(
&self,
_buf: &mut [MaybeUninit<u8>]
) -> bool
[src]
&self,
_buf: &mut [MaybeUninit<u8>]
) -> bool
fn poll_read(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
[src]
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
impl AsyncRead for ChildStdout
[src]
unsafe fn prepare_uninitialized_buffer(
&self,
_buf: &mut [MaybeUninit<u8>]
) -> bool
[src]
&self,
_buf: &mut [MaybeUninit<u8>]
) -> bool
fn poll_read(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
[src]
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
impl<E> AsyncRead for PollEvented<E> where
E: Evented + Read + Unpin,
[src]
E: Evented + Read + Unpin,
fn poll_read(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
[src]
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
impl<R: AsyncRead> AsyncRead for BufReader<R>
[src]
fn poll_read(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
[src]
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
unsafe fn prepare_uninitialized_buffer(
&self,
buf: &mut [MaybeUninit<u8>]
) -> bool
[src]
&self,
buf: &mut [MaybeUninit<u8>]
) -> bool
impl<R: AsyncRead> AsyncRead for Take<R>
[src]
unsafe fn prepare_uninitialized_buffer(
&self,
buf: &mut [MaybeUninit<u8>]
) -> bool
[src]
&self,
buf: &mut [MaybeUninit<u8>]
) -> bool
fn poll_read(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
[src]
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
impl<RW: AsyncRead + AsyncWrite> AsyncRead for BufStream<RW>
[src]
fn poll_read(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
[src]
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
unsafe fn prepare_uninitialized_buffer(
&self,
buf: &mut [MaybeUninit<u8>]
) -> bool
[src]
&self,
buf: &mut [MaybeUninit<u8>]
) -> bool
impl<S, B> AsyncRead for StreamReader<S, B> where
S: Stream<Item = Result<B, Error>>,
B: Buf,
[src]
S: Stream<Item = Result<B, Error>>,
B: Buf,
fn poll_read(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
[src]
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
fn poll_read_buf<BM: BufMut>(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut BM
) -> Poll<Result<usize>> where
Self: Sized,
[src]
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut BM
) -> Poll<Result<usize>> where
Self: Sized,
unsafe fn prepare_uninitialized_buffer(
&self,
_buf: &mut [MaybeUninit<u8>]
) -> bool
[src]
&self,
_buf: &mut [MaybeUninit<u8>]
) -> bool
impl<T: AsyncRead> AsyncRead for tokio::io::ReadHalf<T>
[src]
fn poll_read(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
[src]
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut [u8]
) -> Poll<Result<usize>>
fn poll_read_buf<B: BufMut>(
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut B
) -> Poll<Result<usize>>
[src]
self: Pin<&mut Self>,
cx: &mut Context<'_>,
buf: &mut B
) -> Poll<Result<usize>>