boost::capy::buffer_param

A buffer sequence wrapper providing windowed access.

Synopsis

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

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;
};

Types

Name

Description

buffer_type

The buffer type (const_buffer or mutable_buffer)

Member Functions

Name

Description

buffer_param [constructor]

Construct from a buffer sequence.

consume

Consume bytes from the buffer sequence.

data

Return the current window of buffer descriptors.

more

Check if more buffers exist beyond the current window.

Data Members

Name

arr_ [variant member]

dummy_ [variant member]

Template Parameters

Name Description

BS

The buffer sequence type. Must satisfy either ConstBufferSequence or MutableBufferSequence.

See Also

ConstBufferSequence, MutableBufferSequence

Created with MrDocs