Трейт AsyncRead

pub trait AsyncRead {
    // Required method
    fn poll_read(
        self: Pin<&mut Self>,
        cx: &mut Context<'_>,
        buf: &mut ReadBuf<'_>,
    ) -> Poll<Result<()>>;
}

Читает байты из источника.

Этот трейт аналогичен трейту std::io::Read, но интегрируется с системой асинхронных задач. В частности, метод poll_read, в отличие от Read::read, автоматически поставит текущую задачу в очередь на пробуждение и вернёт управление, если данные ещё недоступны, вместо того чтобы блокировать вызывающий поток.

В частности, это означает, что функция poll_read вернёт один из следующих результатов:

Poll::Ready(Ok(())) означает, что данные были немедленно прочитаны и помещены в выходной буфер. Объём прочитанных данных можно определить по увеличению длины среза, возвращённого методом ReadBuf::filled. Если разница равна 0, значит, достигнут конец файла (EOF) или выходной буфер имеет нулевую ёмкость (то есть buf.remaining() == 0).
Poll::Pending означает, что в предоставленный буфер не было прочитано ни одного байта. Объект ввода-вывода в данный момент недоступен для чтения, но может стать доступен в будущем. Важно отметить, что задача текущего future запланирована к разблокировке, когда объект станет доступен для чтения. Это означает, что, как и в случае с Future::poll, вы получите уведомление, когда объект ввода-вывода снова станет доступен для чтения.
Poll::Ready(Err(e)) для других ошибок — это стандартные ошибки ввода-вывода, возникающие в базовом объекте.

Важно, что этот трейт означает: метод read работает только в контексте задачи future. При использовании вне задачи объект может вызвать панику.

Утилиты для работы со значениями AsyncRead предоставляет AsyncReadExt.

Обязательные методы

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

Пытается прочитать данные из AsyncRead в buf.

При успехе возвращает Poll::Ready(Ok(())) и помещает данные в незаполненную часть buf. Если данные не были прочитаны (buf.filled().len() не изменился), это означает, что достигнут конец файла (EOF) или выходной буфер имеет нулевую ёмкость (то есть buf.remaining() == 0).

Если данные для чтения недоступны, метод возвращает Poll::Pending и организует получение текущей задачей (через cx.waker()) уведомления, когда объект станет доступен для чтения или будет закрыт.