Трейт AsyncWrite

pub trait AsyncWrite {
    // Required methods
    fn poll_write(
        self: Pin<&mut Self>,
        cx: &mut Context<'_>,
        buf: &[u8],
    ) -> Poll<Result<usize>>;
    fn poll_flush(
        self: Pin<&mut Self>,
        cx: &mut Context<'_>,
    ) -> Poll<Result<()>>;
    fn poll_shutdown(
        self: Pin<&mut Self>,
        cx: &mut Context<'_>,
    ) -> Poll<Result<()>>;

    // Provided methods
    fn poll_write_vectored(
        self: Pin<&mut Self>,
        cx: &mut Context<'_>,
        bufs: &[IoSlice<'_>],
    ) -> Poll<Result<usize>> { ... }
    fn is_write_vectored(&self) -> bool { ... }
}

Асинхронно записывает байты.

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

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

Poll::Ready(Ok(n)) означает, что было немедленно записано n байт данных.
Poll::Pending означает, что из предоставленного буфера не было записано никаких данных. Объект ввода-вывода в данный момент не готов к записи, но может стать готовым в будущем. Что особенно важно, задача текущего future запланирована для разблокировки, когда объект будет готов к записи. Это означает, что, как и в случае с Future::poll, вы получите уведомление, когда объект ввода-вывода снова будет готов к записи.
Poll::Ready(Err(e)) для других ошибок — это стандартные ошибки ввода-вывода, возникающие в нижележащем объекте.

Утилиты для работы со значениями AsyncWrite предоставляет AsyncWriteExt. Большинство пользователей взаимодействуют с типами AsyncWrite через эти методы расширения, которые предоставляют удобные асинхронные функции, такие как write_all и flush.

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

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

Попытка записать байты из buf в объект.

В случае успеха возвращает Poll::Ready(Ok(num_bytes_written)). Если операция завершилась успешно, гарантируется, что n <= buf.len(). Возвращаемое значение 0 обычно означает, что нижележащий объект больше не может принимать байты и, вероятно, не сможет этого делать и в будущем, либо переданный буфер пуст.

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

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

Попытка сбросить данные объекта, чтобы все буферизованные данные достигли места назначения.

В случае успеха возвращает Poll::Ready(Ok(())).

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

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

Инициирует или пытается завершить работу этого средства записи; возвращает успех, когда соединение ввода-вывода полностью завершено.

Этот метод предназначен для асинхронного завершения работы соединений ввода-вывода. Например, он подходит для реализации завершения работы TLS-соединения или вызова TcpStream::shutdown для проксируемого соединения. Иногда протоколам необходимо передать последние фрагменты данных или выполнить процедуру корректного завершения соединения, при необходимости считывая и записывая дополнительные данные. Этот метод служит точкой расширения, позволяющей таким протоколам реализовать логику корректного завершения работы.

Этот метод shutdown обязателен для тех, кто реализует трейт AsyncWrite. Обёрткам обычно достаточно перенаправить этот вызов обёрнутому типу, а базовые типы, как правило, реализуют здесь логику завершения работы или просто возвращают Ok(().into()). Обратите внимание: если вы оборачиваете нижележащий AsyncWrite, вызов shutdown подразумевает, что весь поток транзитивно завершил работу. После выполнения логики завершения работы вашей обёртки следует завершить работу нижележащего потока.

Вызов shutdown подразумевает вызов flush. Когда этот метод возвращает Ready, это означает, что перед завершением работы успешно был выполнен сброс данных. То есть вызывающим сторонам не нужно вызывать flush перед вызовом shutdown. Можно рассчитывать на то, что вызов shutdown приведёт к записи всех ожидающих буферизованных данных.

Возвращаемое значение

Эта функция возвращает Poll<io::Result<()>>, которое может иметь следующие значения:

Poll::Ready(Ok(())) — означает, что соединение успешно завершило работу и связанные с ним ресурсы теперь можно безопасно освободить, удалить или закрыть. Этот метод гарантирует, что текущая задача больше не будет получать уведомления из-за его вызова, а сам объект ввода-вывода, вероятно, больше нельзя будет использовать.
Poll::Pending — означает, что завершение работы начато, но пока не может быть завершено. Возможно, для продолжения этой операции потребуется выполнить дополнительные операции ввода-вывода. Текущая задача будет запланирована для получения уведомления, когда она сможет продолжить операцию завершения работы. После пробуждения этот метод следует вызвать снова.
Poll::Ready(Err(e)) — означает, что при завершении работы произошла неисправимая ошибка и операция не завершилась успешно. Обычно это означает, что объект ввода-вывода больше нельзя использовать.

Ошибки

Эта функция может возвращать обычные ошибки ввода-вывода через Err, описанные выше. Кроме того, после вызова этого метода нижележащий метод Write::write может стать непригодным для использования (например, в дальнейшем будет возвращать ошибки). После вызова shutdown рекомендуется больше не вызывать метод write.

Паники

Эта функция вызовет панику, если её вызвать вне контекста задачи future.

Предоставляемые методы

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

Как и poll_write, за исключением того, что запись выполняется из среза буферов.

Данные копируются из каждого буфера по порядку; последний читаемый буфер может быть обработан не полностью. Этот метод должен вести себя так же, как вызов write с объединёнными буферами.

Реализация по умолчанию вызывает poll_write с первым непустым переданным буфером или с пустым буфером, если таких нет.

В случае успеха возвращает Poll::Ready(Ok(num_bytes_written)).

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

Примечание

Этот метод следует реализовать как одно «атомарное» действие записи. Если какие-либо данные были записаны частично, возвращать ошибку или состояние ожидания нельзя.

fn is_write_vectored(&self) -> bool

Определяет, имеет ли этот объект записи эффективную реализацию poll_write_vectored.

Если объект записи не переопределяет реализацию poll_write_vectored по умолчанию, использующий его код может захотеть вообще отказаться от этого метода и объединять записи в один буфер для повышения производительности.

Реализация по умолчанию возвращает false.

Совместимость с dyn

Этот трейт совместим с dyn.

В более старых версиях Rust совместимость с dyn называлась «безопасностью объектов».

Реализации для внешних типов

impl AsyncWrite for Cursor<&mut Vec<u8>>

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

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

fn is_write_vectored(&self) -> bool

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

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

impl AsyncWrite for Cursor<&mut [u8]>

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

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

fn is_write_vectored(&self) -> bool

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

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

impl AsyncWrite for Cursor<Box<[u8]>>

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

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

fn is_write_vectored(&self) -> bool

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

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

impl AsyncWrite for Cursor<Vec<u8>>

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

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

fn is_write_vectored(&self) -> bool

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

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

impl AsyncWrite for Vec<u8>

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

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

fn is_write_vectored(&self) -> bool

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

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

impl<P> AsyncWrite for Pin<P>
where P: DerefMut, P::Target: AsyncWrite,

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

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

fn is_write_vectored(&self) -> bool

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

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

impl<T: ?Sized + AsyncWrite + Unpin> AsyncWrite for &mut T

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

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

fn is_write_vectored(&self) -> bool

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

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

impl<T: ?Sized + AsyncWrite + Unpin> AsyncWrite for Box<T>

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

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

fn is_write_vectored(&self) -> bool

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

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

Реализаторы

impl AsyncWrite for ChildStdin

Доступно только при включенной функции crate process.

impl AsyncWrite for DuplexStream

Доступно только при включенной функции crate io-util.

impl AsyncWrite for Empty

Доступно только при включенной функции crate io-util.

impl AsyncWrite for File

Доступно только при включенной функции crate fs.

impl AsyncWrite for NamedPipeClient

Доступно только в Windows при включенной функции crate net.

impl AsyncWrite for NamedPipeServer

Доступно только в Windows при включенной функции crate net.

impl AsyncWrite for tokio::net::tcp::OwnedWriteHalf

Доступно только при включенной функции crate net.

impl AsyncWrite for tokio::net::unix::OwnedWriteHalf

Доступно только в Unix при включенной функции crate net.

impl AsyncWrite for Sender

Доступно только в Unix при включенной функции crate net.

impl AsyncWrite for SimplexStream

Доступно только при включенной функции crate io-util.

impl AsyncWrite for Sink

Доступно только при включенной функции crate io-util.

impl AsyncWrite for Stderr

Доступно только при включенной функции crate io-std.

impl AsyncWrite for Stdout

Доступно только при включенной функции crate io-std.

impl AsyncWrite for TcpStream

Доступно только при включенной функции crate net.

impl AsyncWrite for UnixStream

Доступно только в Unix при включенной функции crate net.

impl AsyncWrite for tokio::net::tcp::WriteHalf<'_>

Доступно только при включенной функции crate net.