Trait tokio_io::AsyncWrite [−] [src]

pub trait AsyncWrite: Write {
    fn shutdown(&mut self) -> Poll<(), Error>;

    fn write_buf<B: Buf>(&mut self, buf: &mut B) -> Poll<usize, Error>
    where
        Self: Sized,
    { ... }
}

A trait for writable objects which operated in an asynchronous and futures-aware fashion.

This trait inherits from io::Write and indicates that an I/O object is nonblocking, meaning that it will return an error instead of blocking when bytes cannot currently be written, but hasn't closed. Specifically this means that the write function for types that implement this trait can have a few return values:

This trait importantly means that the write method only works in the context of a future's task. The object may panic if used outside of a task.

Required Methods

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

This method is intended to be used for asynchronous shutdown of I/O connections. For example this is suitable for implementing shutdown of a TLS connection or calling TcpStream::shutdown on a proxied connection. Protocols sometimes need to flush out final pieces of data or otherwise perform a graceful shutdown handshake, reading/writing more data as appropriate. This method is the hook for such protocols to implement the graceful shutdown logic.

This shutdown method is required by implementors of the AsyncWrite trait. Wrappers typically just want to proxy this call through to the wrapped type, and base types will typically implement shutdown logic here or just return Ok(().into()). Note that if you're wrapping an underlying AsyncWrite a call to shutdown implies that transitively the entire stream has been shut down. After your wrapper's shutdown logic has been executed you should shut down the underlying stream.

Invocation of a shutdown implies an invocation of flush. Once this method returns Ready it implies that a flush successfully happened before the shutdown happened. That is, callers don't need to call flush before calling shutdown. They can rely that by calling shutdown any pending buffered data will be written out.

Return value

This function returns a Poll<(), io::Error> classified as such:

  • Ok(Async::Ready(())) - indicates that the connection was successfully shut down and is now safe to deallocate/drop/close resources associated with it. This method means that the current task will no longer receive any notifications due to this method and the I/O object itself is likely no longer usable.

  • Ok(Async::NotReady) - indicates that shutdown is initiated but could not complete just yet. This may mean that more I/O needs to happen to continue this shutdown operation. The current task is scheduled to receive a notification when it's otherwise ready to continue the shutdown operation. When woken up this method should be called again.

  • Err(e) - indicates a fatal error has happened with shutdown, indicating that the shutdown operation did not complete successfully. This typically means that the I/O object is no longer usable.

Errors

This function can return normal I/O errors through Err, described above. Additionally this method may also render the underlying Write::write method no longer usable (e.g. will return errors in the future). It's recommended that once shutdown is called the write method is no longer called.

Panics

This function will panic if not called within the context of a future's task.

Provided Methods

Write a Buf into this value, returning how many bytes were written.

Note that this method will advance the buf provided automatically by the number of bytes written.

Implementors