Trait embedded_io_async::Write

source ·

pub trait Write: ErrorType {
    // Required method
    async fn write(&mut self, buf: &[u8]) -> Result<usize, Self::Error>;

    // Provided methods
    async fn flush(&mut self) -> Result<(), Self::Error> { ... }
    async fn write_all(&mut self, buf: &[u8]) -> Result<(), Self::Error> { ... }
}

Expand description

Async writer.

This trait is the embedded-io-async equivalent of std::io::Write.

Required Methods§

source

async fn write(&mut self, buf: &[u8]) -> Result<usize, Self::Error>

Write a buffer into this writer, returning how many bytes were written.

If the writer is not currently ready to accept more bytes (for example, its buffer is full), this function waits until it is ready to accept least one byte.

If it’s ready to accept bytes, a non-zero amount of bytes is written from the beginning of buf, and the amount is returned. It is not guaranteed that all available buffer space is filled, i.e. it is possible for the implementation to write an amount of bytes less than buf.len() while the writer continues to be ready to accept more bytes immediately.

Implementations should never return Ok(0) when buf.len() != 0. Situations where the writer is not able to accept more bytes and likely never will are better indicated with errors.

If buf.len() == 0, write returns without waiting, with either Ok(0) or an error. The Ok(0) doesn’t indicate an error.

Implementations are encouraged to make this function side-effect-free on cancel (AKA “cancel-safe”), i.e. guarantee that if you cancel (drop) a write() future that hasn’t completed yet, the stream’s state hasn’t changed (no bytes have been written).

This is not a requirement to allow implementations that write from the user’s buffer straight to the hardware with e.g. DMA.

Implementations should document whether they’re actually side-effect-free on cancel or not.

Provided Methods§

source

async fn flush(&mut self) -> Result<(), Self::Error>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

source

async fn write_all(&mut self, buf: &[u8]) -> Result<(), Self::Error>

Write an entire buffer into this writer.

This function calls write() in a loop until exactly buf.len() bytes have been written, waiting if needed.

This function is not side-effect-free on cancel (AKA “cancel-safe”), i.e. if you cancel (drop) a returned future that hasn’t completed yet, some bytes might have already been written.

Object Safety§

This trait is not object safe.

Implementations on Foreign Types§

source §

impl Write for &mut [u8]

Write is implemented for &mut [u8] by copying into the slice, overwriting its data.

Note that writing updates the slice to point to the yet unwritten part. The slice will be empty when it has been completely overwritten.

If the number of bytes to be written exceeds the size of the slice, write operations will return short writes: ultimately, Ok(0); in this situation, write_all returns an error of kind ErrorKind::WriteZero.

source §