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_SOURCE_HPP

#ifndef BOOST_CAPY_IO_ANY_BUFFER_SOURCE_HPP

#define BOOST_CAPY_IO_ANY_BUFFER_SOURCE_HPP

#define BOOST_CAPY_IO_ANY_BUFFER_SOURCE_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/slice.hpp>

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

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

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

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

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

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

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

#include <boost/capy/coro.hpp>

#include <boost/capy/coro.hpp>

#include <boost/capy/error.hpp>

#include <boost/capy/error.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 <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 BufferSource.

/** Type-erased wrapper for any BufferSource.

    This class provides type erasure for any type satisfying the

    This class provides type erasure for any type satisfying the

    @ref BufferSource concept, enabling runtime polymorphism for

    @ref BufferSource concept, enabling runtime polymorphism for

    buffer pull operations. The wrapper also satisfies @ref ReadSource,

    buffer pull operations. The wrapper also satisfies @ref ReadSource,

    allowing it to be used with code expecting either interface.

    allowing it to be used with code expecting either interface.

    It uses cached awaitable storage to achieve zero steady-state

    It uses cached awaitable storage to achieve zero steady-state

    allocation after construction.

    allocation after construction.

    The wrapper also satisfies @ref ReadSource through the templated

    The wrapper also satisfies @ref ReadSource through the templated

    @ref read method. This method copies data from the source's

    @ref read method. This method copies data from the source's

    internal buffers into the caller's buffers, incurring one extra

    internal buffers into the caller's buffers, incurring one extra

    buffer copy compared to using @ref pull and @ref consume directly.

    buffer copy compared to using @ref pull and @ref consume 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 source.

      allocates storage and owns the source.

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

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

      pointed-to source must outlive this wrapper.

      pointed-to source 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 source

    // Owning - takes ownership of the source

    any_buffer_source abs(some_buffer_source{args...});

    any_buffer_source abs(some_buffer_source{args...});

    // Reference - wraps without ownership

    // Reference - wraps without ownership

    some_buffer_source src;

    some_buffer_source src;

    any_buffer_source abs(&src);

    any_buffer_source abs(&src);

    const_buffer arr[16];

    const_buffer arr[16];

    auto [ec, bufs] = co_await abs.pull(arr);

    auto [ec, bufs] = co_await abs.pull(arr);

    @endcode

    @endcode

    @see any_buffer_sink, BufferSource, ReadSource

    @see any_buffer_sink, BufferSource, ReadSource

*/

*/

class any_buffer_source

class any_buffer_source

{

{

    struct vtable;

    struct vtable;

    struct awaitable_ops;

    struct awaitable_ops;

    template<BufferSource S>

    template<BufferSource S>

    struct vtable_for_impl;

    struct vtable_for_impl;

    void* source_ = nullptr;

    void* source_ = 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 source (if any) and releases the cached

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

        awaitable storage.

        awaitable storage.

    */

    */

    ~any_buffer_source();

    ~any_buffer_source();

    /** 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_source() = default;

    any_buffer_source() = 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_source(any_buffer_source const&) = delete;

    any_buffer_source(any_buffer_source const&) = delete;

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

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

    /** Move constructor.

    /** Move constructor.

        Transfers ownership of the wrapped source (if owned) and

        Transfers ownership of the wrapped source (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 source and releases existing resources,

        Destroys any owned source 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_source&

    any_buffer_source&

    operator=(any_buffer_source&& other) noexcept;

    operator=(any_buffer_source&& other) noexcept;

    /** Construct by taking ownership of a BufferSource.

    /** Construct by taking ownership of a BufferSource.

        Allocates storage and moves the source into this wrapper.

        Allocates storage and moves the source into this wrapper.

        The wrapper owns the source and will destroy it.

        The wrapper owns the source and will destroy it.

        @param s The source to take ownership of.

        @param s The source to take ownership of.

    */

    */

    template<BufferSource S>

    template<BufferSource S>

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

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

    any_buffer_source(S s);

    any_buffer_source(S s);

    /** Construct by wrapping a BufferSource without ownership.

    /** Construct by wrapping a BufferSource without ownership.

        Wraps the given source by pointer. The source must remain

        Wraps the given source by pointer. The source must remain

        valid for the lifetime of this wrapper.

        valid for the lifetime of this wrapper.

        @param s Pointer to the source to wrap.

        @param s Pointer to the source to wrap.

    */

    */

    template<BufferSource S>

    template<BufferSource S>

    any_buffer_source(S* s);

    any_buffer_source(S* s);

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

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

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

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

            or moved-from.

            or moved-from.

    */

    */

    bool

    bool

    {

    {

    }

    }

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

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

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

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

            or moved-from.

            or moved-from.

    */

    */

    explicit

    explicit

    {

    {

    }

    }

    /** Consume bytes from the source.

    /** Consume bytes from the source.

        Advances the internal read position of the underlying source

        Advances the internal read position of the underlying source

        by the specified number of bytes. The next call to @ref pull

        by the specified number of bytes. The next call to @ref pull

        returns data starting after the consumed bytes.

        returns data starting after the consumed bytes.

        @param n The number of bytes to consume. Must not exceed the

        @param n The number of bytes to consume. Must not exceed the

        total size of buffers returned by the previous @ref pull.

        total size of buffers returned by the previous @ref pull.

        @par Preconditions

        @par Preconditions

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

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

    */

    */

    void

    void

    consume(std::size_t n) noexcept;

    consume(std::size_t n) noexcept;

    /** Pull buffer data from the source.

    /** Pull buffer data from the source.

        Fills the provided span with buffer descriptors from the

        Fills the provided span with buffer descriptors from the

        underlying source. The operation completes when data is

        underlying source. The operation completes when data is

        available, the source is exhausted, or an error occurs.

        available, the source is exhausted, or an error occurs.

        @param dest Span of const_buffer to fill.

        @param dest Span of const_buffer to fill.

        @return An awaitable yielding `(error_code,std::span<const_buffer>)`.

        @return An awaitable yielding `(error_code,std::span<const_buffer>)`.

            On success with data, a non-empty span of filled buffers.

            On success with data, a non-empty span of filled buffers.

            On success with empty span, source is exhausted.

            On success with empty span, source is exhausted.

        @par Preconditions

        @par Preconditions

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

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

    */

    */

    auto

    auto

    pull(std::span<const_buffer> dest);

    pull(std::span<const_buffer> dest);

    /** Read data into a mutable buffer sequence.

    /** Read data into a mutable buffer sequence.

        Fills the provided buffer sequence by pulling data from the

        Fills the provided buffer sequence by pulling data from the

        underlying source and copying it into the caller's buffers.

        underlying source and copying it into the caller's buffers.

        This satisfies @ref ReadSource but incurs a copy; for zero-copy

        This satisfies @ref ReadSource but incurs a copy; for zero-copy

        access, use @ref pull and @ref consume instead.

        access, use @ref pull and @ref consume instead.

        @note This operation copies data from the source's internal

        @note This operation copies data from the source's internal

        buffers into the caller's buffers. For zero-copy reads,

        buffers into the caller's buffers. For zero-copy reads,

        use @ref pull and @ref consume directly.

        use @ref pull and @ref consume directly.

        @param buffers The buffer sequence to fill.

        @param buffers The buffer sequence to fill.

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

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

            On success, `n == buffer_size(buffers)`.

            On success, `n == buffer_size(buffers)`.

            On EOF, `ec == error::eof` and `n` is bytes transferred.

            On EOF, `ec == error::eof` and `n` is bytes transferred.

        @par Preconditions

        @par Preconditions

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

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

        @see pull, consume

        @see pull, consume

    */

    */

    template<MutableBufferSequence MB>

    template<MutableBufferSequence MB>

    task<io_result<std::size_t>>

    task<io_result<std::size_t>>

    read(MB buffers);

    read(MB buffers);

protected:

protected:

    /** Rebind to a new source after move.

    /** Rebind to a new source after move.

        Updates the internal pointer to reference a new source object.

        Updates the internal pointer to reference a new source 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_source The new source to bind to. Must be the same

        @param new_source The new source to bind to. Must be the same

            type as the original source.

            type as the original source.

        @note Terminates if called with a source of different type

        @note Terminates if called with a source of different type

            than the original.

            than the original.

    */

    */

    template<BufferSource S>

    template<BufferSource S>

    void

    void

    rebind(S& new_source) noexcept

    rebind(S& new_source) noexcept

    {

    {

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

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

            std::terminate();

            std::terminate();

        source_ = &new_source;

        source_ = &new_source;

    }

    }

};

};

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

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

struct any_buffer_source::awaitable_ops

struct any_buffer_source::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<std::span<const_buffer>> (*await_resume)(void*);

    io_result<std::span<const_buffer>> (*await_resume)(void*);

    void (*destroy)(void*) noexcept;

    void (*destroy)(void*) noexcept;

};

};

struct any_buffer_source::vtable

struct any_buffer_source::vtable

{

{

    void (*destroy)(void*) noexcept;

    void (*destroy)(void*) noexcept;

    void (*do_consume)(void* source, std::size_t n) noexcept;

    void (*do_consume)(void* source, std::size_t n) noexcept;

    std::size_t awaitable_size;

    std::size_t awaitable_size;

    std::size_t awaitable_align;

    std::size_t awaitable_align;

    awaitable_ops const* (*construct_awaitable)(

    awaitable_ops const* (*construct_awaitable)(

        void* source,

        void* source,

        void* storage,

        void* storage,

        std::span<const_buffer> dest);

        std::span<const_buffer> dest);

};

};

template<BufferSource S>

template<BufferSource S>

struct any_buffer_source::vtable_for_impl

struct any_buffer_source::vtable_for_impl

{

{

    using Awaitable = decltype(std::declval<S&>().pull(

    using Awaitable = decltype(std::declval<S&>().pull(

        std::declval<std::span<const_buffer>>()));

        std::declval<std::span<const_buffer>>()));

    static void

    static void

    {

    {

    static void

    static void

    {

    {

    static awaitable_ops const*

    static awaitable_ops const*

        void* source,

        void* source,

        void* storage,

        void* storage,

        std::span<const_buffer> dest)

        std::span<const_buffer> dest)

    {

    {

        static constexpr awaitable_ops ops = {

        static constexpr awaitable_ops ops = {

            },

            },

            },

            },

            },

            },

            }

            }

        };

        };

    }

    }

    static constexpr vtable value = {

    static constexpr vtable value = {

        &do_destroy_impl,

        &do_destroy_impl,

        &do_consume_impl,

        &do_consume_impl,

        sizeof(Awaitable),

        sizeof(Awaitable),

        alignof(Awaitable),

        alignof(Awaitable),

        &construct_awaitable_impl

        &construct_awaitable_impl

    };

    };

};

};

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

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

inline

inline

{

{

    {

    {

    }

    }

inline any_buffer_source&

inline any_buffer_source&

{

{

    {

    {

        {

        {

        }

        }

    }

    }

}

}

template<BufferSource S>

template<BufferSource S>

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

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

any_buffer_source::any_buffer_source(S s)

any_buffer_source::any_buffer_source(S s)

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

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

{

{

    struct guard {

    struct guard {

        any_buffer_source* self;

        any_buffer_source* self;

        bool committed = false;

        bool committed = false;

        ~guard() {

        ~guard() {

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

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

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

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

                ::operator delete(self->storage_);

                ::operator delete(self->storage_);

                self->storage_ = nullptr;

                self->storage_ = nullptr;

                self->source_ = nullptr;

                self->source_ = nullptr;

            }

            }

        }

        }

    } g{this};

    } g{this};

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

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

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

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

    // Preallocate the awaitable storage

    // Preallocate the awaitable storage

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

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

    g.committed = true;

    g.committed = true;

}

}

template<BufferSource S>

template<BufferSource S>

{

{

    // Preallocate the awaitable storage

    // Preallocate the awaitable storage

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

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

inline void

inline void

{

{

inline auto

inline auto

{

{

    struct awaitable

    struct awaitable

    {

    {

        any_buffer_source* self_;

        any_buffer_source* self_;

        std::span<const_buffer> dest_;

        std::span<const_buffer> dest_;

        bool

        bool

        {

        {

        }

        }

        coro

        coro

        {

        {

            // Construct the underlying awaitable into cached storage

            // Construct the underlying awaitable into cached storage

                dest_);

                dest_);

            // Check if underlying is immediately ready

            // Check if underlying is immediately ready

            // Forward to underlying awaitable

            // Forward to underlying awaitable

        }

        }

        io_result<std::span<const_buffer>>

        io_result<std::span<const_buffer>>

        {

        {

            struct guard {

            struct guard {

                any_buffer_source* self;

                any_buffer_source* self;

    };

    };

}

}

template<MutableBufferSequence MB>

template<MutableBufferSequence MB>

task<io_result<std::size_t>>

task<io_result<std::size_t>>

any_buffer_source::read(MB buffers)

any_buffer_source::read(MB buffers)

{

{

    std::size_t total = 0;

    std::size_t total = 0;

    auto dest = sans_prefix(buffers, 0);

    auto dest = sans_prefix(buffers, 0);

    while(!buffer_empty(dest))

    while(!buffer_empty(dest))

    {

    {

        const_buffer arr[detail::max_iovec_];

        const_buffer arr[detail::max_iovec_];

        auto [ec, bufs] = co_await pull(arr);

        auto [ec, bufs] = co_await pull(arr);

        if(ec)

        if(ec)

            co_return {ec, total};

            co_return {ec, total};

        if(bufs.empty())

        if(bufs.empty())

            co_return {error::eof, total};

            co_return {error::eof, total};

        auto n = buffer_copy(dest, bufs);

        auto n = buffer_copy(dest, bufs);

        consume(n);

        consume(n);

        total += n;

        total += n;

        dest = sans_prefix(dest, n);

        dest = sans_prefix(dest, n);

    }

    }

    co_return {{}, total};

    co_return {{}, total};

}

}

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

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

static_assert(BufferSource<any_buffer_source>);

static_assert(BufferSource<any_buffer_source>);

static_assert(ReadSource<any_buffer_source>);

static_assert(ReadSource<any_buffer_source>);

} // namespace capy

} // namespace capy

} // namespace boost

} // namespace boost

#endif

#endif