boost::capy::WriteStream

Concept for types that provide awaitable write operations.

Synopsis

Declared in <boost/capy/concept/write_stream.hpp>

template<typename T>
concept WriteStream = requires(T& stream, const_buffer_archetype buffers)
    {
        { stream.write_some(buffers) } ‐> IoAwaitable;
        requires awaitable_decomposes_to<
            decltype(stream.write_some(buffers)),
            system::error_code, std::size_t>;
    };

Description

A type satisfies WriteStream if it provides a write_some member function template that accepts any ConstBufferSequence and is an IoAwaitable whose return value decomposes to (error_code,std::size_t).

Syntactic Requirements

`T` must provide a `write_some` member function template accepting any ConstBufferSequence
The return type of `write_some` must satisfy IoAwaitable
The awaitable's result must decompose to `(error_code,std::size_t)` via structured bindings

Semantic Requirements

If buffer_size( buffers ) > 0, the operation writes one or more bytes of data to the stream from the buffer sequence:

On success: `!ec.failed()`, and `n` is the number of bytes written.
On error: `ec.failed()`, and `n` is 0.

If buffer_empty( buffers ) is true, the operation completes immediately. !ec.failed(), and n is 0.

Buffers in the sequence are written completely before proceeding to the next buffer.

Buffer Lifetime

The caller must ensure that the memory referenced by buffers remains valid until the co_await expression returns.

Conforming Signatures

template< ConstBufferSequence Buffers >
IoAwaitable auto write_some( Buffers buffers );

Coroutine Buffer Lifetime: When implementing coroutine member functions, prefer accepting buffer sequences by value rather than by reference. Buffer sequences passed by reference may become dangling if the caller's stack frame is destroyed before the coroutine completes. Passing by value ensures the buffer sequence is copied into the coroutine frame and remains valid across suspension points.

Example

template< WriteStream Stream >
task<> write_all( Stream& s, char const* buf, std::size_t size )
{
    std::size_t total = 0;
    while( total < size )
    {
        auto [ec, n] = co_await s.write_some(
            const_buffer( buf + total, size - total ) );
        if( ec.failed() )
            co_return;
        total += n;
    }
}

Template Parameters

Name	Description
T	The stream type.