[−][src]Trait tokio::prelude::AsyncRead
Read bytes asynchronously.
This trait inherits from std::io::Read
and indicates that an I/O object is
non-blocking. All non-blocking I/O objects must return an error when
bytes are unavailable instead of blocking the current 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.
Required methods
fn poll_read(
self: Pin<&mut Self>,
cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
self: Pin<&mut Self>,
cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
Attempt 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 [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
.
fn poll_read_buf<B>(
self: Pin<&mut Self>,
cx: &mut Context,
buf: &mut B
) -> Poll<Result<usize, Error>> where
B: BufMut,
self: Pin<&mut Self>,
cx: &mut Context,
buf: &mut B
) -> Poll<Result<usize, Error>> where
B: BufMut,
Pull 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> AsyncRead for Cursor<T> where
T: Unpin + AsRef<[u8]>,
[src]
T: Unpin + AsRef<[u8]>,
unsafe fn prepare_uninitialized_buffer(&self, _buf: &mut [u8]) -> bool
[src]
fn poll_read(
self: Pin<&mut Cursor<T>>,
_cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
[src]
self: Pin<&mut Cursor<T>>,
_cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
impl<'_> AsyncRead for &'_ [u8]
[src]
unsafe fn prepare_uninitialized_buffer(&self, _buf: &mut [u8]) -> bool
[src]
fn poll_read(
self: Pin<&mut &'_ [u8]>,
_cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
[src]
self: Pin<&mut &'_ [u8]>,
_cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
impl<'_, T> AsyncRead for &'_ mut T where
T: AsyncRead + Unpin + ?Sized,
[src]
T: AsyncRead + Unpin + ?Sized,
unsafe fn prepare_uninitialized_buffer(&self, buf: &mut [u8]) -> bool
[src]
fn poll_read(
self: Pin<&mut &'_ mut T>,
cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
[src]
self: Pin<&mut &'_ mut T>,
cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
impl<P> AsyncRead for Pin<P> where
P: DerefMut + Unpin,
<P as Deref>::Target: AsyncRead,
[src]
P: DerefMut + Unpin,
<P as Deref>::Target: AsyncRead,
unsafe fn prepare_uninitialized_buffer(&self, buf: &mut [u8]) -> bool
[src]
fn poll_read(
self: Pin<&mut Pin<P>>,
cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
[src]
self: Pin<&mut Pin<P>>,
cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
impl<T> AsyncRead for Box<T> where
T: AsyncRead + Unpin + ?Sized,
[src]
T: AsyncRead + Unpin + ?Sized,
unsafe fn prepare_uninitialized_buffer(&self, buf: &mut [u8]) -> bool
[src]
fn poll_read(
self: Pin<&mut Box<T>>,
cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
[src]
self: Pin<&mut Box<T>>,
cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
impl<E> AsyncRead for PollEvented<E> where
E: Evented + Read + Unpin,
[src]
E: Evented + Read + Unpin,
fn poll_read(
self: Pin<&mut PollEvented<E>>,
cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
[src]
self: Pin<&mut PollEvented<E>>,
cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
Implementors
impl AsyncRead for File
[src]
fn poll_read(
self: Pin<&mut File>,
cx: &mut Context,
dst: &mut [u8]
) -> Poll<Result<usize, Error>>
[src]
self: Pin<&mut File>,
cx: &mut Context,
dst: &mut [u8]
) -> Poll<Result<usize, Error>>
impl AsyncRead for Stdin
[src]
fn poll_read(
self: Pin<&mut Stdin>,
cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
[src]
self: Pin<&mut Stdin>,
cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
impl AsyncRead for TcpStreamReadHalf
[src]
unsafe fn prepare_uninitialized_buffer(&self, &mut [u8]) -> bool
[src]
fn poll_read(
self: Pin<&mut TcpStreamReadHalf>,
cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
[src]
self: Pin<&mut TcpStreamReadHalf>,
cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
fn poll_read_buf<B>(
self: Pin<&mut TcpStreamReadHalf>,
cx: &mut Context,
buf: &mut B
) -> Poll<Result<usize, Error>> where
B: BufMut,
[src]
self: Pin<&mut TcpStreamReadHalf>,
cx: &mut Context,
buf: &mut B
) -> Poll<Result<usize, Error>> where
B: BufMut,
impl AsyncRead for TcpStream
[src]
unsafe fn prepare_uninitialized_buffer(&self, &mut [u8]) -> bool
[src]
fn poll_read(
self: Pin<&mut TcpStream>,
cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
[src]
self: Pin<&mut TcpStream>,
cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
fn poll_read_buf<B>(
self: Pin<&mut TcpStream>,
cx: &mut Context,
buf: &mut B
) -> Poll<Result<usize, Error>> where
B: BufMut,
[src]
self: Pin<&mut TcpStream>,
cx: &mut Context,
buf: &mut B
) -> Poll<Result<usize, Error>> where
B: BufMut,
impl AsyncRead for UnixStreamReadHalf
[src]
unsafe fn prepare_uninitialized_buffer(&self, &mut [u8]) -> bool
[src]
fn poll_read(
self: Pin<&mut UnixStreamReadHalf>,
cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
[src]
self: Pin<&mut UnixStreamReadHalf>,
cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
fn poll_read_buf<B>(
self: Pin<&mut UnixStreamReadHalf>,
cx: &mut Context,
buf: &mut B
) -> Poll<Result<usize, Error>> where
B: BufMut,
[src]
self: Pin<&mut UnixStreamReadHalf>,
cx: &mut Context,
buf: &mut B
) -> Poll<Result<usize, Error>> where
B: BufMut,
impl AsyncRead for UnixStream
[src]
unsafe fn prepare_uninitialized_buffer(&self, &mut [u8]) -> bool
[src]
fn poll_read(
self: Pin<&mut UnixStream>,
cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
[src]
self: Pin<&mut UnixStream>,
cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
fn poll_read_buf<B>(
self: Pin<&mut UnixStream>,
cx: &mut Context,
buf: &mut B
) -> Poll<Result<usize, Error>> where
B: BufMut,
[src]
self: Pin<&mut UnixStream>,
cx: &mut Context,
buf: &mut B
) -> Poll<Result<usize, Error>> where
B: BufMut,
impl<'_> AsyncRead for TcpStreamReadHalfMut<'_>
[src]
unsafe fn prepare_uninitialized_buffer(&self, &mut [u8]) -> bool
[src]
fn poll_read(
self: Pin<&mut TcpStreamReadHalfMut<'_>>,
cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
[src]
self: Pin<&mut TcpStreamReadHalfMut<'_>>,
cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
fn poll_read_buf<B>(
self: Pin<&mut TcpStreamReadHalfMut<'_>>,
cx: &mut Context,
buf: &mut B
) -> Poll<Result<usize, Error>> where
B: BufMut,
[src]
self: Pin<&mut TcpStreamReadHalfMut<'_>>,
cx: &mut Context,
buf: &mut B
) -> Poll<Result<usize, Error>> where
B: BufMut,
impl<'_> AsyncRead for UnixStreamReadHalfMut<'_>
[src]
unsafe fn prepare_uninitialized_buffer(&self, &mut [u8]) -> bool
[src]
fn poll_read(
self: Pin<&mut UnixStreamReadHalfMut<'_>>,
cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
[src]
self: Pin<&mut UnixStreamReadHalfMut<'_>>,
cx: &mut Context,
buf: &mut [u8]
) -> Poll<Result<usize, Error>>
fn poll_read_buf<B>(
self: Pin<&mut UnixStreamReadHalfMut<'_>>,
cx: &mut Context,
buf: &mut B
) -> Poll<Result<usize, Error>> where
B: BufMut,
[src]
self: Pin<&mut UnixStreamReadHalfMut<'_>>,
cx: &mut Context,
buf: &mut B
) -> Poll<Result<usize, Error>> where
B: BufMut,
impl<R> AsyncRead for BufReader<R> where
R: AsyncRead,
[src]
R: AsyncRead,