Diff coverage report for

//

//

// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)

// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.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_WRITE_SINK_HPP

#ifndef BOOST_CAPY_IO_ANY_WRITE_SINK_HPP

#define BOOST_CAPY_IO_ANY_WRITE_SINK_HPP

#define BOOST_CAPY_IO_ANY_WRITE_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_array.hpp>

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

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

#include <boost/capy/buffers/buffer_param.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 <coroutine>

#include <coroutine>

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

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

#include <boost/capy/io_result.hpp>

#include <boost/capy/io_result.hpp>

#include <boost/capy/io_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 <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 WriteSink.

/** Type-erased wrapper for any WriteSink.

    This class provides type erasure for any type satisfying the

    This class provides type erasure for any type satisfying the

    @ref WriteSink concept, enabling runtime polymorphism for

    @ref WriteSink concept, enabling runtime polymorphism for

    sink write operations. It uses cached awaitable storage to achieve

    sink write operations. It uses cached awaitable storage to achieve

    zero steady-state allocation after construction.

    zero steady-state allocation after construction.

    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 Immediate Completion

    @par Immediate Completion

    Operations complete immediately without suspending when the

    Operations complete immediately without suspending when the

    buffer sequence is empty, or when the underlying sink's

    buffer sequence is empty, or when the underlying sink's

    awaitable reports readiness via `await_ready`.

    awaitable reports readiness via `await_ready`.

    @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_write_sink ws(some_sink{args...});

    any_write_sink ws(some_sink{args...});

    // Reference - wraps without ownership

    // Reference - wraps without ownership

    some_sink sink;

    some_sink sink;

    any_write_sink ws(&sink);

    any_write_sink ws(&sink);

    const_buffer buf(data, size);

    const_buffer buf(data, size);

    auto [ec, n] = co_await ws.write(std::span(&buf, 1));

    auto [ec, n] = co_await ws.write(std::span(&buf, 1));

    auto [ec2] = co_await ws.write_eof();

    auto [ec2] = co_await ws.write_eof();

    @endcode

    @endcode

    @see any_write_stream, WriteSink

    @see any_write_stream, WriteSink

*/

*/

class any_write_sink

class any_write_sink

{

{

    struct vtable;

    struct vtable;

    struct write_awaitable_ops;

    struct write_awaitable_ops;

    struct eof_awaitable_ops;

    struct eof_awaitable_ops;

    template<WriteSink S>

    template<WriteSink 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;

    write_awaitable_ops const* active_write_ops_ = nullptr;

    write_awaitable_ops const* active_write_ops_ = nullptr;

    eof_awaitable_ops const* active_eof_ops_ = nullptr;

    eof_awaitable_ops const* active_eof_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_write_sink();

    ~any_write_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_write_sink() = default;

    any_write_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_write_sink(any_write_sink const&) = delete;

    any_write_sink(any_write_sink const&) = delete;

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

    any_write_sink& operator=(any_write_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_write_sink&

    any_write_sink&

    operator=(any_write_sink&& other) noexcept;

    operator=(any_write_sink&& other) noexcept;

    /** Construct by taking ownership of a WriteSink.

    /** Construct by taking ownership of a WriteSink.

        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<WriteSink S>

    template<WriteSink S>

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

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

    any_write_sink(S s);

    any_write_sink(S s);

    /** Construct by wrapping a WriteSink without ownership.

    /** Construct by wrapping a WriteSink 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<WriteSink S>

    template<WriteSink S>

    any_write_sink(S* s);

    any_write_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

    {

    {

    }

    }

    /** Initiate a partial write operation.

    /** Initiate a partial write operation.

        Writes one or more bytes from the provided buffer sequence.

        Writes one or more bytes from the provided buffer sequence.

        May consume less than the full sequence.

        May consume less than the full sequence.

        @param buffers The buffer sequence containing data to write.

        @param buffers The buffer sequence containing data to write.

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

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

        @par Immediate Completion

        @par Immediate Completion

        The operation completes immediately without suspending

        The operation completes immediately without suspending

        the calling coroutine when:

        the calling coroutine when:

        @li The buffer sequence is empty, returning `{error_code{}, 0}`.

        @li The buffer sequence is empty, returning `{error_code{}, 0}`.

        @li The underlying sink's awaitable reports immediate

        @li The underlying sink's awaitable reports immediate

            readiness via `await_ready`.

            readiness via `await_ready`.

        @note This is a partial operation and may not process the

        @note This is a partial operation and may not process the

        entire buffer sequence. Use @ref write for guaranteed

        entire buffer sequence. Use @ref write for guaranteed

        complete transfer.

        complete transfer.

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

    auto

    auto

    write_some(CB buffers);

    write_some(CB buffers);

    /** Initiate a complete write operation.

    /** Initiate a complete write operation.

        Writes data from the provided buffer sequence. The operation

        Writes data from the provided buffer sequence. The operation

        completes when all bytes have been consumed, or an error

        completes when all bytes have been consumed, or an error

        occurs. Forwards to the underlying sink's `write` operation,

        occurs. Forwards to the underlying sink's `write` operation,

        windowed through @ref buffer_param when the sequence exceeds

        windowed through @ref buffer_param when the sequence exceeds

        the per-call buffer limit.

        the per-call buffer limit.

        @param buffers The buffer sequence containing data to write.

        @param buffers The buffer sequence containing data to write.

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

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

        @par Immediate Completion

        @par Immediate Completion

        The operation completes immediately without suspending

        The operation completes immediately without suspending

        the calling coroutine when:

        the calling coroutine when:

        @li The buffer sequence is empty, returning `{error_code{}, 0}`.

        @li The buffer sequence is empty, returning `{error_code{}, 0}`.

        @li Every underlying `write` call completes

        @li Every underlying `write` call completes

            immediately (the wrapped sink reports readiness

            immediately (the wrapped sink reports readiness

            via `await_ready` on each iteration).

            via `await_ready` on each iteration).

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

    io_task<std::size_t>

    io_task<std::size_t>

    write(CB buffers);

    write(CB buffers);

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

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

        Writes all data from the buffer sequence and then signals

        Writes all data from the buffer sequence and then signals

        end-of-stream. The implementation decides how to partition

        end-of-stream. The implementation decides how to partition

        the data across calls to the underlying sink's @ref write

        the data across calls to the underlying sink's @ref write

        and `write_eof`. When the caller's buffer sequence is

        and `write_eof`. When the caller's buffer sequence is

        non-empty, the final call to the underlying sink is always

        non-empty, the final call to the underlying sink is always

        `write_eof` with a non-empty buffer sequence. When the

        `write_eof` with a non-empty buffer sequence. When the

        caller's buffer sequence is empty, only `write_eof()` with

        caller's buffer sequence is empty, only `write_eof()` with

        no data is called.

        no data is called.

        @param buffers The buffer sequence containing data to write.

        @param buffers The buffer sequence containing data to write.

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

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

        @par Immediate Completion

        @par Immediate Completion

        The operation completes immediately without suspending

        The operation completes immediately without suspending

        the calling coroutine when:

        the calling coroutine when:

        @li The buffer sequence is empty. Only the @ref write_eof()

        @li The buffer sequence is empty. Only the @ref write_eof()

            call is performed.

            call is performed.

        @li All underlying operations complete immediately (the

        @li All underlying operations complete immediately (the

            wrapped sink reports readiness via `await_ready`).

            wrapped sink reports readiness via `await_ready`).

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

    io_task<std::size_t>

    io_task<std::size_t>

    write_eof(CB buffers);

    write_eof(CB buffers);

    /** Signal end of data.

    /** Signal end of data.

        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 Immediate Completion

        @par Immediate Completion

        The operation completes immediately without suspending

        The operation completes immediately without suspending

        the calling coroutine when the underlying sink's awaitable

        the calling coroutine when the underlying sink's awaitable

        reports immediate readiness via `await_ready`.

        reports immediate readiness via `await_ready`.

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

    template<WriteSink 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:

private:

    auto

    auto

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

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

    auto

    auto

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

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

    auto

    auto

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

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

};

};

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

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

struct any_write_sink::write_awaitable_ops

struct any_write_sink::write_awaitable_ops

{

{

    bool (*await_ready)(void*);

    bool (*await_ready)(void*);

    std::coroutine_handle<> (*await_suspend)(void*, std::coroutine_handle<>, io_env const*);

    std::coroutine_handle<> (*await_suspend)(void*, std::coroutine_handle<>, io_env const*);

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

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

    void (*destroy)(void*) noexcept;

    void (*destroy)(void*) noexcept;

};

};

struct any_write_sink::eof_awaitable_ops

struct any_write_sink::eof_awaitable_ops

{

{

    bool (*await_ready)(void*);

    bool (*await_ready)(void*);

    std::coroutine_handle<> (*await_suspend)(void*, std::coroutine_handle<>, io_env const*);

    std::coroutine_handle<> (*await_suspend)(void*, std::coroutine_handle<>, io_env const*);

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

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

    void (*destroy)(void*) noexcept;

    void (*destroy)(void*) noexcept;

};

};

struct any_write_sink::vtable

struct any_write_sink::vtable

{

{

    write_awaitable_ops const* (*construct_write_some_awaitable)(

    write_awaitable_ops const* (*construct_write_some_awaitable)(

        void* sink,

        void* sink,

        void* storage,

        void* storage,

        std::span<const_buffer const> buffers);

        std::span<const_buffer const> buffers);

    write_awaitable_ops const* (*construct_write_awaitable)(

    write_awaitable_ops const* (*construct_write_awaitable)(

        void* sink,

        void* sink,

        void* storage,

        void* storage,

        std::span<const_buffer const> buffers);

        std::span<const_buffer const> buffers);

    write_awaitable_ops const* (*construct_write_eof_buffers_awaitable)(

    write_awaitable_ops const* (*construct_write_eof_buffers_awaitable)(

        void* sink,

        void* sink,

        void* storage,

        void* storage,

        std::span<const_buffer const> buffers);

        std::span<const_buffer const> buffers);

    eof_awaitable_ops const* (*construct_eof_awaitable)(

    eof_awaitable_ops const* (*construct_eof_awaitable)(

        void* sink,

        void* sink,

        void* storage);

        void* storage);

    std::size_t awaitable_size;

    std::size_t awaitable_size;

    std::size_t awaitable_align;

    std::size_t awaitable_align;

    void (*destroy)(void*) noexcept;

    void (*destroy)(void*) noexcept;

};

};

template<WriteSink S>

template<WriteSink S>

struct any_write_sink::vtable_for_impl

struct any_write_sink::vtable_for_impl

{

{

    using WriteSomeAwaitable = decltype(std::declval<S&>().write_some(

    using WriteSomeAwaitable = decltype(std::declval<S&>().write_some(

        std::span<const_buffer const>{}));

        std::span<const_buffer const>{}));

    using WriteAwaitable = decltype(std::declval<S&>().write(

    using WriteAwaitable = decltype(std::declval<S&>().write(

        std::span<const_buffer const>{}));

        std::span<const_buffer const>{}));

    using WriteEofBuffersAwaitable = decltype(std::declval<S&>().write_eof(

    using WriteEofBuffersAwaitable = decltype(std::declval<S&>().write_eof(

        std::span<const_buffer const>{}));

        std::span<const_buffer const>{}));

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

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

    static void

    static void

    {

    {

    static write_awaitable_ops const*

    static write_awaitable_ops const*

        void* sink,

        void* sink,

        void* storage,

        void* storage,

        std::span<const_buffer const> buffers)

        std::span<const_buffer const> buffers)

    {

    {

        static constexpr write_awaitable_ops ops = {

        static constexpr write_awaitable_ops ops = {

            },

            },

            },

            },

            },

            },

            }

            }

        };

        };

    }

    }

    static write_awaitable_ops const*

    static write_awaitable_ops const*

        void* sink,

        void* sink,

        void* storage,

        void* storage,

        std::span<const_buffer const> buffers)

        std::span<const_buffer const> buffers)

    {

    {

        static constexpr write_awaitable_ops ops = {

        static constexpr write_awaitable_ops ops = {

            },

            },

            },

            },

            },

            },

            }

            }

        };

        };

    }

    }

    static write_awaitable_ops const*

    static write_awaitable_ops const*

        void* sink,

        void* sink,

        void* storage,

        void* storage,

        std::span<const_buffer const> buffers)

        std::span<const_buffer const> buffers)

    {

    {

        static constexpr write_awaitable_ops ops = {

        static constexpr write_awaitable_ops ops = {

            },

            },

            },

            },

            },

            },

            }

            }

        };

        };

    }

    }

    static eof_awaitable_ops const*

    static eof_awaitable_ops const*

        void* sink,

        void* sink,

        void* storage)

        void* storage)

    {

    {

        static constexpr eof_awaitable_ops ops = {

        static constexpr eof_awaitable_ops ops = {

            },

            },

            },

            },

            },

            },

            }

            }

        };

        };

    }

    }

    static constexpr std::size_t max4(

    static constexpr std::size_t max4(

        std::size_t a, std::size_t b,

        std::size_t a, std::size_t b,

        std::size_t c, std::size_t d) noexcept

        std::size_t c, std::size_t d) noexcept

    {

    {

        std::size_t ab = a > b ? a : b;

        std::size_t ab = a > b ? a : b;

        std::size_t cd = c > d ? c : d;

        std::size_t cd = c > d ? c : d;

        return ab > cd ? ab : cd;

        return ab > cd ? ab : cd;

    }

    }

    static constexpr std::size_t max_awaitable_size =

    static constexpr std::size_t max_awaitable_size =

        max4(sizeof(WriteSomeAwaitable),

        max4(sizeof(WriteSomeAwaitable),

             sizeof(WriteAwaitable),

             sizeof(WriteAwaitable),

             sizeof(WriteEofBuffersAwaitable),

             sizeof(WriteEofBuffersAwaitable),

             sizeof(EofAwaitable));

             sizeof(EofAwaitable));

    static constexpr std::size_t max_awaitable_align =

    static constexpr std::size_t max_awaitable_align =

        max4(alignof(WriteSomeAwaitable),

        max4(alignof(WriteSomeAwaitable),

             alignof(WriteAwaitable),

             alignof(WriteAwaitable),

             alignof(WriteEofBuffersAwaitable),

             alignof(WriteEofBuffersAwaitable),

             alignof(EofAwaitable));

             alignof(EofAwaitable));

    static constexpr vtable value = {

    static constexpr vtable value = {

        &construct_write_some_awaitable_impl,

        &construct_write_some_awaitable_impl,

        &construct_write_awaitable_impl,

        &construct_write_awaitable_impl,

        &construct_write_eof_buffers_awaitable_impl,

        &construct_write_eof_buffers_awaitable_impl,

        &construct_eof_awaitable_impl,

        &construct_eof_awaitable_impl,

        max_awaitable_size,

        max_awaitable_size,

        max_awaitable_align,

        max_awaitable_align,

        &do_destroy_impl

        &do_destroy_impl

    };

    };

};

};

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

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

inline

inline

{

{

    {

    {

    }

    }