boost::capy::BufferSource

Concept for types that produce buffer data asynchronously.

Synopsis

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

template<typename T>
concept BufferSource = requires(T& src, std::span<const_buffer> dest, std::size_t n)
    {
        { src.pull(dest) } ‐> IoAwaitable;
        requires awaitable_decomposes_to<
            decltype(src.pull(dest)),
            std::error_code, std::span<const_buffer>>;
        src.consume(n);
    };

Description

A type satisfies BufferSource if it provides a pull member function that fills a caller‐provided span of buffer descriptors and is an IoAwaitable whose return value decomposes to (error_code,std::span<const_buffer>), plus a consume member function to indicate how many bytes were used.

Use this concept when you need to produce data asynchronously for transfer to a sink, such as streaming HTTP request bodies or reading file contents for transmission.

Syntactic Requirements

`T` must provide a `pull` member function accepting a `std::span<const_buffer>` for output
The return type must satisfy IoAwaitable
The awaitable must decompose to `(error_code,std::span<const_buffer>)` via structured bindings
`T` must provide a `consume` member function accepting a byte count

Semantic Requirements

The pull operation fills the provided buffer span with data starting from the current unconsumed position. On return, exactly one of the following is true:

**Data available**: `!ec` and `bufs.size() > 0`. The returned span contains buffer descriptors.
**Source exhausted**: `ec == cond::eof` and `bufs.empty()`. No more data is available; the transfer is complete.
**Error**: `ec` is `true` and `ec != cond::eof`. An error occurred.

Calling pull multiple times without intervening consume returns the same unconsumed data. The consume operation advances the read position by the specified number of bytes. The next pull returns data starting after the consumed bytes.

Buffer Lifetime

The memory referenced by the returned buffer descriptors must remain valid until the next call to pull, consume, or until the source is destroyed.

Conforming Signatures

some_io_awaitable<io_result<std::span<const_buffer>>>
pull( std::span<const_buffer> dest );

void consume( std::size_t n ) noexcept;

Example

template<BufferSource Source, WriteStream Stream>
io_task<std::size_t> transfer( Source& source, Stream& stream )
{
    const_buffer arr[16];
    std::size_t total = 0;
    for(;;)
    {
        auto [ec, bufs] = co_await source.pull( arr );
        if( ec == cond::eof )
            co_return {{}, total};
        if( ec )
            co_return {ec, total};
        auto [write_ec, n] = co_await stream.write_some( bufs );
        if( write_ec )
            co_return {write_ec, total};
        source.consume( n );
        total += n;
    }
}

Template Parameters

Name	Description
T	The source type.