Trait Write

Source

pub trait Write:
    HasMemory
    + Memory
    + Debug
    + Send {
    type Error: Error + Send + Sync + 'static;

    // Required method
    fn write(
        &mut self,
        data: BytesView,
    ) -> impl Future<Output = Result<(), Self::Error>> + Send;
}

Expand description

Allowing for writing of bytes.

Only supports asynchronous access. Accepts the byte sequences to be written as bytesbuf::BytesView instances.

§Ownership

The methods on this trait accept &mut self and take an exclusive reference to the object for the duration of the operation. This implies that only one write operation can be concurrently executed on the object.

§Memory management for efficient I/O

For optimal efficiency when performing I/O, writes should be performed from memory optimized for the underlying I/O endpoint. This is achieved by reserving memory from the implementation’s memory provider and generating your bytes into the returned memory buffer before performing the write operation.

To be clear, the expectation is that whatever data you want to write is placed into the implementation’s provided memory buffers right from the start. If your data starts “somewhere else” and must be copied, optimal I/O efficiency cannot be achieved as copying by definition is a form of inefficiency. The data must be born in the memory buffers used for the write operation.

There are two ways to ensure you are using memory suitable for optimally efficient I/O:

You may call Memory::reserve() on the implementing type to reserve memory from its memory provider.
You may sometimes want to call reserve() at certain times when Rust borrowing rules do not allow you to call it directly on the implementation because it has already been borrowed. In this case, you can obtain an independent reference to the memory provider first via HasMemory::memory(), which allows you to bypass the need to borrow the implementing object itself.

Some implementations do not perform real I/O and only move data around in memory. Such implementations typically do not have any special memory requirements and will operate with the same efficiency regardless of which buffers the data is in. Any relaxed behaviors like this will typically be described in the implementation’s API documentation.

§Thread safety

This trait requires Send from both the implementation and any returned futures.

Required Associated Types§

Source

type Error: Error + Send + Sync + 'static

Type used to signal errors by the implementation of this trait.

Required Methods§

Source

fn write( &mut self, data: BytesView, ) -> impl Future<Output = Result<(), Self::Error>> + Send

Writes the provided byte sequence.

The method completes when all bytes have been written. Partial writes are considered a failure.

§Example

use bytesbuf::mem::Memory;
use bytesbuf_io::Write;

let mut sink = get_sink();

let mut buf = sink.reserve(100);
buf.put_slice(*b"Hello, world!");
let bytes = buf.consume_all();

sink.write(bytes).await.unwrap();