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)),
            std::error_code, std::size_t>;
    };

Description

A type satisfies WriteStream if it provides a write_some member function template that accepts any ConstBufferSequence and await‐returns (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

Attempts to write up to buffer_size( buffers ) bytes from the buffer sequence to the stream.

If buffer_size( buffers ) > 0:

If !ec, then n >= 1 && n <= buffer_size( buffers ). n bytes were written from the buffer sequence.
If ec, then n >= 0 && n <= buffer_size( buffers ). n is the number of bytes written before the I/O condition arose.

If buffer_empty( buffers ) is true, n is 0. The empty buffer is not itself a cause for error, but ec may reflect the state of the stream.

Buffers in the sequence are consumed in order.

Error Reporting

I/O conditions arising from the underlying I/O system (EOF, connection reset, broken pipe, etc.) are reported via the error_code component of the return value. Failures in the library wrapper itself (such as memory allocation failure) are reported via exceptions.

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 ) );
        total += n;
        if( ec )
            co_return;
    }
}

Exceptions

Name

Thrown on

std::bad_alloc

If coroutine frame allocation fails.

Template Parameters

Name	Description
T	The stream type.