Trait tokio_io::AsyncWrite

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:

• Ok(n) means that n bytes of data was immediately written .
• Err(e) if e.kind() == ErrorKind::WouldBlock means that no data was written from the buffer provided. The I/O object is not currently writable but may become writable in the future. Most importantly, the current future's task is scheduled to get unparked when the object is readable. This means that like Future::poll you'll receive a notification when the I/O object is writable again.
• Err(e) for other errors are standard I/O errors coming from the underlying object.

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

fn shutdown(&mut self) -> Poll<(), Error>

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

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

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.

Implementations on Foreign Types

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

fn shutdown(&mut self) -> Poll<(), Error>

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

impl<'a, T: ?Sized + AsyncWrite> AsyncWrite for &'a mut T

fn shutdown(&mut self) -> Poll<(), Error>

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

impl AsyncWrite for Sink

fn shutdown(&mut self) -> Poll<(), Error>

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

impl<T: AsyncWrite> AsyncWrite for BufWriter<T>

fn shutdown(&mut self) -> Poll<(), Error>

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

impl<'a> AsyncWrite for Cursor<&'a mut [u8]>

fn shutdown(&mut self) -> Poll<(), Error>

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

impl AsyncWrite for Cursor<Vec<u8>>

fn shutdown(&mut self) -> Poll<(), Error>

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

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

fn shutdown(&mut self) -> Poll<(), Error>

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

Implementors

• impl<T> AsyncWrite for AllowStdIo<T> where
    T: Write, 
• impl<T: AsyncWrite> AsyncWrite for FramedRead<T>
• impl<T: AsyncWrite> AsyncWrite for WriteHalf<T>