Diff coverage report for

//

//

// Copyright (c) 2025 Vinnie Falco (vinnie dot falco at gmail dot com)

// Copyright (c) 2025 Vinnie Falco (vinnie dot falco at gmail dot com)

//

//

// Distributed under the Boost Software License, Version 1.0. (See accompanying

// Distributed under the Boost Software License, Version 1.0. (See accompanying

// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

//

//

// Official repository: https://github.com/cppalliance/capy

// Official repository: https://github.com/cppalliance/capy

//

//

#ifndef BOOST_CAPY_IO_ANY_BUFFER_SINK_HPP

#ifndef BOOST_CAPY_IO_ANY_BUFFER_SINK_HPP

#define BOOST_CAPY_IO_ANY_BUFFER_SINK_HPP

#define BOOST_CAPY_IO_ANY_BUFFER_SINK_HPP

#include <boost/capy/detail/config.hpp>

#include <boost/capy/detail/config.hpp>

#include <boost/capy/detail/await_suspend_helper.hpp>

#include <boost/capy/detail/await_suspend_helper.hpp>

#include <boost/capy/buffers.hpp>

#include <boost/capy/buffers.hpp>

#include <boost/capy/buffers/buffer_copy.hpp>

#include <boost/capy/buffers/buffer_copy.hpp>

#include <boost/capy/buffers/buffer_param.hpp>

#include <boost/capy/buffers/buffer_param.hpp>

#include <boost/capy/concept/buffer_sink.hpp>

#include <boost/capy/concept/buffer_sink.hpp>

#include <boost/capy/concept/io_awaitable.hpp>

#include <boost/capy/concept/io_awaitable.hpp>

#include <boost/capy/concept/write_sink.hpp>

#include <boost/capy/concept/write_sink.hpp>

#include <boost/capy/coro.hpp>

#include <boost/capy/coro.hpp>

#include <boost/capy/ex/executor_ref.hpp>

#include <boost/capy/ex/executor_ref.hpp>

#include <boost/capy/io_result.hpp>

#include <boost/capy/io_result.hpp>

#include <boost/capy/task.hpp>

#include <boost/capy/io_task.hpp>

#include <concepts>

#include <concepts>

#include <coroutine>

#include <coroutine>

#include <cstddef>

#include <cstddef>

#include <exception>

#include <exception>

#include <new>

#include <new>

#include <span>

#include <stop_token>

#include <stop_token>

#include <system_error>

#include <system_error>

#include <utility>

#include <utility>

namespace boost {

namespace boost {

namespace capy {

namespace capy {

/** Type-erased wrapper for any BufferSink.

/** Type-erased wrapper for any BufferSink.

    This class provides type erasure for any type satisfying the

    This class provides type erasure for any type satisfying the

    @ref BufferSink concept, enabling runtime polymorphism for

    @ref BufferSink concept, enabling runtime polymorphism for

    buffer sink operations. It uses cached awaitable storage to achieve

    buffer sink operations. It uses cached awaitable storage to achieve

    zero steady-state allocation after construction.

    zero steady-state allocation after construction.

    The wrapper also satisfies @ref WriteSink through templated

    The wrapper exposes two interfaces for producing data:

    @ref write methods. These methods copy data from the caller's

    the @ref BufferSink interface (`prepare`, `commit`, `commit_eof`)

    buffers into the sink's internal storage, incurring one extra

    and the @ref WriteSink interface (`write_some`, `write`,

    buffer copy compared to using @ref prepare and @ref commit

    `write_eof`). Choose the interface that matches how your data

    directly.

    is produced:

    @par 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 @ref prepare to obtain writable buffers,

    fill them, then call @ref commit or @ref 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

      @ref write_eof(buffers) to send everything atomically.

    - If data arrives incrementally, call @ref write or

      @ref write_some in a loop, then @ref write_eof() when done.

      Prefer `write` (complete) unless your streaming pattern

      benefits from partial writes via `write_some`.

    If the wrapped type only satisfies @ref BufferSink, the

    @ref WriteSink operations are provided automatically.

    @par Construction Modes

    The wrapper supports two construction modes:

    - **Owning**: Pass by value to transfer ownership. The wrapper

    - **Owning**: Pass by value to transfer ownership. The wrapper

      allocates storage and owns the sink.

      allocates storage and owns the sink.

    - **Reference**: Pass a pointer to wrap without ownership. The

    - **Reference**: Pass a pointer to wrap without ownership. The

      pointed-to sink must outlive this wrapper.

      pointed-to sink must outlive this wrapper.

    @par Awaitable Preallocation

    @par Awaitable Preallocation

    The constructor preallocates storage for the type-erased awaitable.

    The constructor preallocates storage for the type-erased awaitable.

    This reserves all virtual address space at server startup

    This reserves all virtual address space at server startup

    so memory usage can be measured up front, rather than

    so memory usage can be measured up front, rather than

    allocating piecemeal as traffic arrives.

    allocating piecemeal as traffic arrives.

    @par Thread Safety

    @par Thread Safety

    Not thread-safe. Concurrent operations on the same wrapper

    Not thread-safe. Concurrent operations on the same wrapper

    are undefined behavior.

    are undefined behavior.

    @par Example

    @par Example

    @code

    @code

    // Owning - takes ownership of the sink

    // Owning - takes ownership of the sink

    any_buffer_sink abs(some_buffer_sink{args...});

    any_buffer_sink abs(some_buffer_sink{args...});

    // Reference - wraps without ownership

    // Reference - wraps without ownership

    some_buffer_sink sink;

    some_buffer_sink sink;

    any_buffer_sink abs(&sink);

    any_buffer_sink abs(&sink);

    // BufferSink interface: generate into callee-owned buffers

    mutable_buffer arr[16];

    mutable_buffer arr[16];

    auto bufs = abs.prepare(arr);

    auto bufs = abs.prepare(arr);

    // Write data into bufs[0..bufs.size())

    // Write data into bufs[0..bufs.size())

    auto [ec] = co_await abs.commit(bytes_written);

    auto [ec] = co_await abs.commit(bytes_written);

    auto [ec2] = co_await abs.commit_eof();

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

    @endcode

    @endcode

    @see any_buffer_source, BufferSink, WriteSink

    @see any_buffer_source, BufferSink, WriteSink

*/

*/

class any_buffer_sink

class any_buffer_sink

{

{

    struct vtable;

    struct vtable;

    struct awaitable_ops;

    struct awaitable_ops;

    struct write_awaitable_ops;

    template<BufferSink S>

    template<BufferSink S>

    struct vtable_for_impl;

    struct vtable_for_impl;

    // hot-path members first for cache locality

    void* sink_ = nullptr;

    void* sink_ = nullptr;

    vtable const* vt_ = nullptr;

    vtable const* vt_ = nullptr;

    void* storage_ = nullptr;

    void* cached_awaitable_ = nullptr;

    void* cached_awaitable_ = nullptr;

    awaitable_ops const* active_ops_ = nullptr;

    awaitable_ops const* active_ops_ = nullptr;

    write_awaitable_ops const* active_write_ops_ = nullptr;

    void* storage_ = nullptr;

public:

public:

    /** Destructor.

    /** Destructor.

        Destroys the owned sink (if any) and releases the cached

        Destroys the owned sink (if any) and releases the cached

        awaitable storage.

        awaitable storage.

    */

    */

    ~any_buffer_sink();

    ~any_buffer_sink();

    /** Default constructor.

    /** Default constructor.

        Constructs an empty wrapper. Operations on a default-constructed

        Constructs an empty wrapper. Operations on a default-constructed

        wrapper result in undefined behavior.

        wrapper result in undefined behavior.

    */

    */

    any_buffer_sink() = default;

    any_buffer_sink() = default;

    /** Non-copyable.

    /** Non-copyable.

        The awaitable cache is per-instance and cannot be shared.

        The awaitable cache is per-instance and cannot be shared.

    */

    */

    any_buffer_sink(any_buffer_sink const&) = delete;

    any_buffer_sink(any_buffer_sink const&) = delete;

    any_buffer_sink& operator=(any_buffer_sink const&) = delete;

    any_buffer_sink& operator=(any_buffer_sink const&) = delete;

    /** Move constructor.

    /** Move constructor.

        Transfers ownership of the wrapped sink (if owned) and

        Transfers ownership of the wrapped sink (if owned) and

        cached awaitable storage from `other`. After the move, `other` is

        cached awaitable storage from `other`. After the move, `other` is

        in a default-constructed state.

        in a default-constructed state.

        @param other The wrapper to move from.

        @param other The wrapper to move from.

    */

    */

    {

    {

    /** Move assignment operator.

    /** Move assignment operator.

        Destroys any owned sink and releases existing resources,

        Destroys any owned sink and releases existing resources,

        then transfers ownership from `other`.

        then transfers ownership from `other`.

        @param other The wrapper to move from.

        @param other The wrapper to move from.

        @return Reference to this wrapper.

        @return Reference to this wrapper.

    */

    */

    any_buffer_sink&

    any_buffer_sink&

    operator=(any_buffer_sink&& other) noexcept;

    operator=(any_buffer_sink&& other) noexcept;

    /** Construct by taking ownership of a BufferSink.

    /** Construct by taking ownership of a BufferSink.

        Allocates storage and moves the sink into this wrapper.

        Allocates storage and moves the sink into this wrapper.

        The wrapper owns the sink and will destroy it.

        The wrapper owns the sink and will destroy it. If `S` also

        satisfies @ref WriteSink, native write operations are

        forwarded through the virtual boundary.

        @param s The sink to take ownership of.

        @param s The sink to take ownership of.

    */

    */

    template<BufferSink S>

    template<BufferSink S>

        requires (!std::same_as<std::decay_t<S>, any_buffer_sink>)

        requires (!std::same_as<std::decay_t<S>, any_buffer_sink>)

    any_buffer_sink(S s);

    any_buffer_sink(S s);

    /** Construct by wrapping a BufferSink without ownership.

    /** Construct by wrapping a BufferSink without ownership.

        Wraps the given sink by pointer. The sink must remain

        Wraps the given sink by pointer. The sink must remain

        valid for the lifetime of this wrapper.

        valid for the lifetime of this wrapper. If `S` also

        satisfies @ref WriteSink, native write operations are

        forwarded through the virtual boundary.

        @param s Pointer to the sink to wrap.

        @param s Pointer to the sink to wrap.

    */

    */

    template<BufferSink S>

    template<BufferSink S>

    any_buffer_sink(S* s);

    any_buffer_sink(S* s);

    /** Check if the wrapper contains a valid sink.

    /** Check if the wrapper contains a valid sink.

        @return `true` if wrapping a sink, `false` if default-constructed

        @return `true` if wrapping a sink, `false` if default-constructed

            or moved-from.

            or moved-from.

    */

    */

    bool

    bool

    {

    {

    }

    }

    /** Check if the wrapper contains a valid sink.

    /** Check if the wrapper contains a valid sink.

        @return `true` if wrapping a sink, `false` if default-constructed

        @return `true` if wrapping a sink, `false` if default-constructed

            or moved-from.

            or moved-from.

    */

    */

    explicit

    explicit

    {

    {

    }

    }

    /** Prepare writable buffers.

    /** Prepare writable buffers.

        Fills the provided span with mutable buffer descriptors

        Fills the provided span with mutable buffer descriptors

        pointing to the underlying sink's internal storage. This

        pointing to the underlying sink's internal storage. This

        operation is synchronous.

        operation is synchronous.

        @param dest Span of mutable_buffer to fill.

        @param dest Span of mutable_buffer to fill.

        @return A span of filled buffers.

        @return A span of filled buffers.

        @par Preconditions

        @par Preconditions

        The wrapper must contain a valid sink (`has_value() == true`).

        The wrapper must contain a valid sink (`has_value() == true`).

    */

    */

    std::span<mutable_buffer>

    std::span<mutable_buffer>

    prepare(std::span<mutable_buffer> dest);

    prepare(std::span<mutable_buffer> dest);

    /** Commit bytes written to the prepared buffers.

    /** Commit bytes written to the prepared buffers.

        Commits `n` bytes written to the buffers returned by the

        Commits `n` bytes written to the buffers returned by the

        most recent call to @ref prepare. The operation may trigger

        most recent call to @ref prepare. The operation may trigger

        underlying I/O.

        underlying I/O.

        @param n The number of bytes to commit.

        @param n The number of bytes to commit.

        @return An awaitable yielding `(error_code)`.

        @return An awaitable yielding `(error_code)`.

        @par Preconditions

        @par Preconditions

        The wrapper must contain a valid sink (`has_value() == true`).

        The wrapper must contain a valid sink (`has_value() == true`).

    */

    */

    auto

    auto

    commit(std::size_t n);

    commit(std::size_t n);

    /** Commit bytes written with optional end-of-stream.

    /** Commit final bytes and signal end-of-stream.

        Commits `n` bytes written to the buffers returned by the

        Commits `n` bytes written to the buffers returned by the

        most recent call to @ref prepare. If `eof` is true, also

        most recent call to @ref prepare and finalizes the sink.

        signals end-of-stream.

        After success, no further operations are permitted.

        @param eof If true, signals end-of-stream after committing.

        @param n The number of bytes to commit.

        @param n The number of bytes to commit.

        @return An awaitable yielding `(error_code)`.

        @return An awaitable yielding `(error_code)`.

        @par Preconditions

        @par Preconditions

        The wrapper must contain a valid sink (`has_value() == true`).

        The wrapper must contain a valid sink (`has_value() == true`).

    */

    */

    auto

    auto

    commit(std::size_t n, bool eof);

    commit_eof(std::size_t n);

    /** Signal end-of-stream.

    /** Write some data from a buffer sequence.

        Indicates that no more data will be written to the sink.

        Writes one or more bytes from the buffer sequence to the

        The operation completes when the sink is finalized, or

        underlying sink. May consume less than the full sequence.

        an error occurs.

        @return An awaitable yielding `(error_code)`.

        When the wrapped type provides native @ref WriteSink support,

        the operation forwards directly. Otherwise it is synthesized

        from @ref prepare and @ref commit with a buffer copy.

        @param buffers The buffer sequence to write.

        @return An awaitable yielding `(error_code,std::size_t)`.

        @par Preconditions

        @par Preconditions

        The wrapper must contain a valid sink (`has_value() == true`).

        The wrapper must contain a valid sink (`has_value() == true`).

    */

    */

    auto

    template<ConstBufferSequence CB>

    commit_eof();

    io_task<std::size_t>

    write_some(CB buffers);

    /** Write data from a buffer sequence.

    /** Write all data from a buffer sequence.

        Writes all data from the buffer sequence to the underlying

        Writes all data from the buffer sequence to the underlying

        sink. This method satisfies the @ref WriteSink concept.

        sink. This method satisfies the @ref WriteSink concept.

        @note This operation copies data from the caller's buffers

        When the wrapped type provides native @ref WriteSink support,

        into the sink's internal buffers. For zero-copy writes,

        each window is forwarded directly. Otherwise the data is

        use @ref prepare and @ref commit directly.

        copied into the sink via @ref prepare and @ref commit.

        @param buffers The buffer sequence to write.

        @param buffers The buffer sequence to write.

        @return An awaitable yielding `(error_code,std::size_t)`.

        @return An awaitable yielding `(error_code,std::size_t)`.

        @par Preconditions

        @par Preconditions

        The wrapper must contain a valid sink (`has_value() == true`).

        The wrapper must contain a valid sink (`has_value() == true`).

    */

    */

    template<ConstBufferSequence CB>

    template<ConstBufferSequence CB>

    task<io_result<std::size_t>>

    io_task<std::size_t>

    write(CB buffers);

    write(CB buffers);

    /** Write data with optional end-of-stream.

    /** Atomically write data and signal end-of-stream.

        Writes all data from the buffer sequence to the underlying

        Writes all data from the buffer sequence to the underlying

        sink, optionally finalizing it afterwards. This method

        sink and then signals end-of-stream.

        satisfies the @ref WriteSink concept.

        @note This operation copies data from the caller's buffers

        When the wrapped type provides native @ref WriteSink support,

        into the sink's internal buffers. For zero-copy writes,

        the final window is sent atomically via the underlying

        use @ref prepare and @ref commit directly.

        `write_eof(buffers)`. Otherwise the data is synthesized

        through @ref prepare, @ref commit, and @ref commit_eof.

        @param eof If true, finalize the sink after writing.

        @param buffers The buffer sequence to write.

        @param buffers The buffer sequence to write.

        @return An awaitable yielding `(error_code,std::size_t)`.

        @return An awaitable yielding `(error_code,std::size_t)`.

        @par Preconditions

        @par Preconditions

        The wrapper must contain a valid sink (`has_value() == true`).

        The wrapper must contain a valid sink (`has_value() == true`).

    */

    */

    template<ConstBufferSequence CB>

    template<ConstBufferSequence CB>

    task<io_result<std::size_t>>

    io_task<std::size_t>

    write(CB buffers, bool eof);

    write_eof(CB buffers);

    /** Signal end-of-stream.

    /** Signal end-of-stream.

        Indicates that no more data will be written to the sink.

        Indicates that no more data will be written to the sink.

        This method satisfies the @ref WriteSink concept.

        This method satisfies the @ref WriteSink concept.

        When the wrapped type provides native @ref WriteSink support,

        the underlying `write_eof()` is called. Otherwise the

        operation is implemented as `commit_eof(0)`.

        @return An awaitable yielding `(error_code)`.

        @return An awaitable yielding `(error_code)`.

        @par Preconditions

        @par Preconditions

        The wrapper must contain a valid sink (`has_value() == true`).

        The wrapper must contain a valid sink (`has_value() == true`).

    */

    */

    auto

    auto

    write_eof();

    write_eof();

protected:

protected:

    /** Rebind to a new sink after move.

    /** Rebind to a new sink after move.

        Updates the internal pointer to reference a new sink object.

        Updates the internal pointer to reference a new sink object.

        Used by owning wrappers after move assignment when the owned

        Used by owning wrappers after move assignment when the owned

        object has moved to a new location.

        object has moved to a new location.

        @param new_sink The new sink to bind to. Must be the same

        @param new_sink The new sink to bind to. Must be the same

            type as the original sink.

            type as the original sink.

        @note Terminates if called with a sink of different type

        @note Terminates if called with a sink of different type

            than the original.

            than the original.

    */

    */

    template<BufferSink S>

    template<BufferSink S>

    void

    void

    rebind(S& new_sink) noexcept

    rebind(S& new_sink) noexcept

    {

    {

        if(vt_ != &vtable_for_impl<S>::value)

        if(vt_ != &vtable_for_impl<S>::value)

            std::terminate();

            std::terminate();

        sink_ = &new_sink;

        sink_ = &new_sink;

    }

    }

private:

    /** Forward a partial write through the vtable.

        Constructs the underlying `write_some` awaitable in

        cached storage and returns a type-erased awaitable.

    */

    auto

    write_some_(std::span<const_buffer const> buffers);

    /** Forward a complete write through the vtable.

        Constructs the underlying `write` awaitable in

        cached storage and returns a type-erased awaitable.

    */

    auto

    write_(std::span<const_buffer const> buffers);

    /** Forward an atomic write-with-EOF through the vtable.

        Constructs the underlying `write_eof(buffers)` awaitable

        in cached storage and returns a type-erased awaitable.

    */

    auto

    write_eof_buffers_(std::span<const_buffer const> buffers);

};

};

//----------------------------------------------------------

//----------------------------------------------------------

/** Type-erased ops for awaitables yielding `io_result<>`. */

struct any_buffer_sink::awaitable_ops

struct any_buffer_sink::awaitable_ops

{

{

    bool (*await_ready)(void*);

    bool (*await_ready)(void*);

    coro (*await_suspend)(void*, coro, executor_ref, std::stop_token);

    coro (*await_suspend)(void*, coro, executor_ref, std::stop_token);

    io_result<> (*await_resume)(void*);

    io_result<> (*await_resume)(void*);

    void (*destroy)(void*) noexcept;

    void (*destroy)(void*) noexcept;

};

};

/** Type-erased ops for awaitables yielding `io_result<std::size_t>`. */

struct any_buffer_sink::write_awaitable_ops

{

    bool (*await_ready)(void*);

    coro (*await_suspend)(void*, coro, executor_ref, std::stop_token);

    io_result<std::size_t> (*await_resume)(void*);

    void (*destroy)(void*) noexcept;

};

struct any_buffer_sink::vtable

struct any_buffer_sink::vtable

{

{

    void (*destroy)(void*) noexcept;

    void (*destroy)(void*) noexcept;

    std::span<mutable_buffer> (*do_prepare)(

    std::span<mutable_buffer> (*do_prepare)(

        void* sink,

        void* sink,

        std::span<mutable_buffer> dest);

        std::span<mutable_buffer> dest);

    std::size_t awaitable_size;

    std::size_t awaitable_size;

    std::size_t awaitable_align;

    std::size_t awaitable_align;

    awaitable_ops const* (*construct_commit_awaitable)(

    awaitable_ops const* (*construct_commit_awaitable)(

        void* sink,

        void* sink,

        void* storage,

        void* storage,

        std::size_t n,

        std::size_t n);

        bool eof);

    awaitable_ops const* (*construct_commit_eof_awaitable)(

    awaitable_ops const* (*construct_eof_awaitable)(

        void* sink,

        void* storage,

        std::size_t n);

    // WriteSink forwarding (null when wrapped type is BufferSink-only)

    write_awaitable_ops const* (*construct_write_some_awaitable)(

        void* sink,

        void* storage,

        std::span<const_buffer const> buffers);

    write_awaitable_ops const* (*construct_write_awaitable)(

        void* sink,

        void* storage,

        std::span<const_buffer const> buffers);

    write_awaitable_ops const* (*construct_write_eof_buffers_awaitable)(

        void* sink,

        void* storage,

        std::span<const_buffer const> buffers);

    awaitable_ops const* (*construct_write_eof_awaitable)(

        void* sink,

        void* sink,

        void* storage);

        void* storage);

};

};

template<BufferSink S>

template<BufferSink S>

struct any_buffer_sink::vtable_for_impl

struct any_buffer_sink::vtable_for_impl

{

{

    using CommitAwaitable = decltype(std::declval<S&>().commit(

    using CommitAwaitable = decltype(std::declval<S&>().commit(

        std::size_t{}, false));

        std::size_t{}));

    using EofAwaitable = decltype(std::declval<S&>().commit_eof());

    using CommitEofAwaitable = decltype(std::declval<S&>().commit_eof(

        std::size_t{}));

    static void

    static void

    {

    {

    static std::span<mutable_buffer>

    static std::span<mutable_buffer>

        void* sink,

        void* sink,

        std::span<mutable_buffer> dest)

        std::span<mutable_buffer> dest)

    {

    {

    }

    }

    static awaitable_ops const*

    static awaitable_ops const*

        void* sink,

        void* sink,

        void* storage,

        void* storage,

        std::size_t n,

        std::size_t n)

        bool eof)

    {

    {

        static constexpr awaitable_ops ops = {

        static constexpr awaitable_ops ops = {

            },

            },

            },

            },

            },

            },

            }

            }

        };

        };

    }

    }

    static awaitable_ops const*

    static awaitable_ops const*

        void* sink,

        void* storage,

        std::size_t n)

    {

        static constexpr awaitable_ops ops = {

            },

            },

            },

            }

        };

    }