boost::capy::buffer_param

A buffer sequence wrapper providing windowed access.

Synopsis

Declared in <boost/capy/buffers/buffer_param.hpp>

template<
    class BS,
    bool MakeConst = false>
requires ConstBufferSequence<BS> || MutableBufferSequence<BS>
class buffer_param;

Description

This template class wraps any buffer sequence and provides incremental access through a sliding window of buffer descriptors. It handles both const and mutable buffer sequences automatically.

Coroutine Lifetime Requirement

When used in coroutine APIs, the outer template function MUST accept the buffer sequence parameter BY VALUE:

task<> write(ConstBufferSequence auto buffers);   // CORRECT
task<> write(ConstBufferSequence auto& buffers);  // WRONG - dangling reference

Pass‐by‐value ensures the buffer sequence is copied into the coroutine frame and remains valid across suspension points. References would dangle when the caller's scope exits before the coroutine resumes.

Purpose

When iterating through large buffer sequences, it is often more efficient to process buffers in batches rather than one at a time. This class maintains a window of up to max_size buffer descriptors, automatically refilling from the underlying sequence as buffers are consumed.

Usage

Create a buffer_param from any buffer sequence and use data() to get the current window of buffers. After processing some bytes, call consume() to advance through the sequence.

task<> send(ConstBufferSequence auto buffers)
{
    buffer_param bp(buffers);
    while(true)
    {
        auto bufs = bp.data();
        if(bufs.empty())
            break;
        auto n = co_await do_something(bufs);
        bp.consume(n);
    }
}

Virtual Interface Pattern

This class enables passing arbitrary buffer sequences through a virtual function boundary. The template function captures the buffer sequence by value and drives the iteration, while the virtual function receives a simple span:

class base
{
public:
    task<> write(ConstBufferSequence auto buffers)
    {
        buffer_param bp(buffers);
        while(true)
        {
            auto bufs = bp.data();
            if(bufs.empty())
                break;
            std::size_t n = 0;
            co_await write_impl(bufs, n);
            bp.consume(n);
        }
    }

protected:
    virtual task<> write_impl(
        std::span<const_buffer> buffers,
        std::size_t& bytes_written) = 0;
};

Template Parameters

Name	Description
BS	The buffer sequence type. Must satisfy either ConstBufferSequence or MutableBufferSequence.