boost::capy::any_buffer_sink

Type‐erased wrapper for any BufferSink.

Synopsis

Declared in <boost/capy/io/any_buffer_sink.hpp>

class any_buffer_sink;

Description

This class provides type erasure for any type satisfying the BufferSink concept, enabling runtime polymorphism for buffer sink operations. It uses cached awaitable storage to achieve zero steady‐state allocation after construction.

The wrapper exposes two interfaces for producing data: the BufferSink interface (prepare, commit, commit_eof) and the WriteSink interface (write_some, write, write_eof). Choose the interface that matches how your data is produced:

Choosing an Interface

Use the BufferSink interface when you are a generator that produces data into externally‐provided buffers. The sink owns the memory; you call prepare to obtain writable buffers, fill them, then call commit or commit_eof.

Use the WriteSink interface when you already have buffers containing the data to write: ‐ If the entire body is available up front, call write_eof(buffers) to send everything atomically. ‐ If data arrives incrementally, call write or write_some in a loop, then write_eof() when done. Prefer write (complete) unless your streaming pattern benefits from partial writes via write_some.

If the wrapped type only satisfies BufferSink, the WriteSink operations are provided automatically.

Construction Modes

‐ Owning: Pass by value to transfer ownership. The wrapper allocates storage and owns the sink. ‐ Reference: Pass a pointer to wrap without ownership. The pointed‐to sink must outlive this wrapper.

Awaitable Preallocation

The constructor preallocates storage for the type‐erased awaitable. This reserves all virtual address space at server startup so memory usage can be measured up front, rather than allocating piecemeal as traffic arrives.

Thread Safety

Not thread‐safe. Concurrent operations on the same wrapper are undefined behavior.

Example

// Owning - takes ownership of the sink
any_buffer_sink abs(some_buffer_sink{args...});

// Reference - wraps without ownership
some_buffer_sink sink;
any_buffer_sink abs(&sink);

// BufferSink interface: generate into callee-owned buffers
mutable_buffer arr[16];
auto bufs = abs.prepare(arr);
// Write data into bufs[0..bufs.size())
auto [ec] = co_await abs.commit(bytes_written);
auto [ec2] = co_await abs.commit_eof(0);

// WriteSink interface: send caller-owned buffers
auto [ec3, n] = co_await abs.write(make_buffer("hello", 5));
auto [ec4] = co_await abs.write_eof();

// Or send everything at once
auto [ec5, n2] = co_await abs.write_eof(
    make_buffer(body_data));