boost::capy::ReadSource

Concept for types providing complete reads from a data source.

Synopsis

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

template<typename T>
concept ReadSource = ReadStream<T> &&
    requires(T& source, mutable_buffer_archetype buffers)
    {
        { source.read(buffers) } ‐> IoAwaitable;
        requires awaitable_decomposes_to<
            decltype(source.read(buffers)),
            std::error_code, std::size_t>;
    };

Description

A type satisfies ReadSource if it satisfies ReadStream and additionally provides a read member function that accepts any MutableBufferSequence and is an IoAwaitable whose return value decomposes to (error_code, std::size_t).

ReadSource refines ReadStream. Every ReadSource is a ReadStream. Algorithms constrained on ReadStream accept both raw streams and sources.

Syntactic Requirements

`T` must satisfy ReadStream (provides `read_some`)
`T` must provide a `read` member function template accepting any MutableBufferSequence
The return type of `read` must satisfy IoAwaitable
The awaitable must decompose to `(error_code, std::size_t)` via structured bindings

Semantic Requirements

The inherited read_some operation reads one or more bytes (partial read). See ReadStream.

The read operation fills the entire buffer sequence. On return, exactly one of the following is true:

**Success**: `!ec` and `n` equals `buffer_size( buffers )`. The entire buffer sequence was filled.
**End‐of‐stream**: `ec == cond::eof` and `n` indicates the number of bytes transferred before EOF was reached.
**Error**: `ec` and `n` indicates the number of bytes transferred before the error.

Successful partial reads are not permitted; either the entire buffer is filled or the operation returns with an error.

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

When the buffer sequence contains multiple buffers, each buffer is filled completely before proceeding to the next.

Buffer Lifetime

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

Conforming Signatures

template< MutableBufferSequence MB >
IoAwaitable auto read_some( MB buffers );   // inherited from ReadStream

template< MutableBufferSequence MB >
IoAwaitable auto read( MB 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< ReadSource Source >
task<> read_header( Source& source )
{
    char header[16];
    auto [ec, n] = co_await source.read(
        mutable_buffer( header ) );
    if( ec )
        co_return;
    // header contains exactly 16 bytes
}

Template Parameters

Name	Description
T	The source type.