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/task.hpp>

#include <concepts>

#include <concepts>

#include <coroutine>

#include <coroutine>

#include <cstddef>

#include <cstddef>

#include <exception>

#include <exception>

#include <new>

#include <new>

#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 also satisfies @ref WriteSink through templated

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

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

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

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

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

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

    directly.

    directly.

    The wrapper supports two 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);

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

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

    template<BufferSink S>

    template<BufferSink S>

    struct vtable_for_impl;

    struct vtable_for_impl;

    void* sink_ = nullptr;

    void* sink_ = nullptr;

    vtable const* vt_ = nullptr;

    vtable const* vt_ = nullptr;

    void* cached_awaitable_ = nullptr;

    void* cached_awaitable_ = nullptr;

    void* storage_ = nullptr;

    void* storage_ = nullptr;

    awaitable_ops const* active_ops_ = nullptr;

    awaitable_ops const* active_ops_ = 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.

        @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.

        @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 bytes written with optional 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. If `eof` is true, also

        signals end-of-stream.

        signals end-of-stream.

        @param n The number of bytes to commit.

        @param n The number of bytes to commit.

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

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

        @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(std::size_t n, bool eof);

    /** 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.

        The operation completes when the sink is finalized, or

        The operation completes when the sink is finalized, or

        an error occurs.

        an error occurs.

        @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_eof();

    commit_eof();

    /** Write data from a buffer sequence.

    /** Write 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

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

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

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

        use @ref prepare and @ref commit directly.

        use @ref prepare and @ref commit directly.

        @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>>

    task<io_result<std::size_t>>

    write(CB buffers);

    write(CB buffers);

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

    /** Write data with optional 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, optionally finalizing it afterwards. This method

        satisfies the @ref WriteSink concept.

        satisfies the @ref WriteSink concept.

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

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

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

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

        use @ref prepare and @ref commit directly.

        use @ref prepare and @ref commit directly.

        @param buffers The buffer sequence to write.

        @param buffers The buffer sequence to write.

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

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

        @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>>

    task<io_result<std::size_t>>

    write(CB buffers, bool eof);

    write(CB buffers, bool eof);

    /** 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.

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

    }

    }

};

};

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

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

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;

};

};

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

        bool eof);

    awaitable_ops const* (*construct_eof_awaitable)(

    awaitable_ops const* (*construct_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{}, false));

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

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

    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)

        bool eof)

    {

    {

        static constexpr awaitable_ops ops = {

        static constexpr awaitable_ops ops = {

            },

            },

            },

            },

            },

            },

            }

            }

        };

        };

    }

    }

    static awaitable_ops const*

    static awaitable_ops const*

        void* sink,

        void* sink,

        void* storage)

        void* storage)

    {

    {

        static constexpr awaitable_ops ops = {

        static constexpr awaitable_ops ops = {

            },

            },

            },

            },

            },

            },

            }

            }

        };

        };

    }

    }

    static constexpr std::size_t max_awaitable_size =

    static constexpr std::size_t max_awaitable_size =

        sizeof(CommitAwaitable) > sizeof(EofAwaitable)

        sizeof(CommitAwaitable) > sizeof(EofAwaitable)

            ? sizeof(CommitAwaitable)

            ? sizeof(CommitAwaitable)

            : sizeof(EofAwaitable);

            : sizeof(EofAwaitable);

    static constexpr std::size_t max_awaitable_align =

    static constexpr std::size_t max_awaitable_align =

        alignof(CommitAwaitable) > alignof(EofAwaitable)

        alignof(CommitAwaitable) > alignof(EofAwaitable)

            ? alignof(CommitAwaitable)

            ? alignof(CommitAwaitable)

            : alignof(EofAwaitable);

            : alignof(EofAwaitable);

    static constexpr vtable value = {

    static constexpr vtable value = {

        &do_destroy_impl,

        &do_destroy_impl,

        &do_prepare_impl,

        &do_prepare_impl,

        max_awaitable_size,

        max_awaitable_size,

        max_awaitable_align,

        max_awaitable_align,

        &construct_commit_awaitable_impl,

        &construct_commit_awaitable_impl,

        &construct_eof_awaitable_impl

        &construct_eof_awaitable_impl

    };

    };

};

};

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

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

inline

inline

{

{

    {

    {

    }

    }

inline any_buffer_sink&

inline any_buffer_sink&

{

{

    {

    {

        {

        {

        }

        }

    }

    }

}

}

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::any_buffer_sink(S s)

any_buffer_sink::any_buffer_sink(S s)

    : vt_(&vtable_for_impl<S>::value)

    : vt_(&vtable_for_impl<S>::value)

{

{

    struct guard {

    struct guard {

        any_buffer_sink* self;

        any_buffer_sink* self;

        bool committed = false;

        bool committed = false;

        ~guard() {

        ~guard() {

            if(!committed && self->storage_) {

            if(!committed && self->storage_) {

                self->vt_->destroy(self->sink_);

                self->vt_->destroy(self->sink_);

                ::operator delete(self->storage_);

                ::operator delete(self->storage_);

                self->storage_ = nullptr;

                self->storage_ = nullptr;

                self->sink_ = nullptr;

                self->sink_ = nullptr;

            }

            }

        }

        }

    } g{this};

    } g{this};

    storage_ = ::operator new(sizeof(S));

    storage_ = ::operator new(sizeof(S));

    sink_ = ::new(storage_) S(std::move(s));

    sink_ = ::new(storage_) S(std::move(s));

    // Preallocate the awaitable storage (sized for max of commit/eof)

    // Preallocate the awaitable storage (sized for max of commit/eof)

    cached_awaitable_ = ::operator new(vt_->awaitable_size);

    cached_awaitable_ = ::operator new(vt_->awaitable_size);

    g.committed = true;

    g.committed = true;

}

}

template<BufferSink S>

template<BufferSink S>

{

{

    // Preallocate the awaitable storage (sized for max of commit/eof)

    // Preallocate the awaitable storage (sized for max of commit/eof)

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

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

inline std::span<mutable_buffer>

inline std::span<mutable_buffer>

{

{