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 are written. Specifically this means that the write function for traits that implement this type 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.

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()).

Invocation of a shutdown implies invocation of flush. Once this method returns Ready it implies that a flush successfully happened before the shutdown happened.

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