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_READ_SOURCE_HPP

#ifndef BOOST_CAPY_IO_ANY_READ_SOURCE_HPP

#define BOOST_CAPY_IO_ANY_READ_SOURCE_HPP

#define BOOST_CAPY_IO_ANY_READ_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_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/read_source.hpp>

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

#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 ReadSource.

/** Type-erased wrapper for any ReadSource.

    This class provides type erasure for any type satisfying the

    This class provides type erasure for any type satisfying the

    @ref ReadSource concept, enabling runtime polymorphism for

    @ref ReadSource concept, enabling runtime polymorphism for

    source read operations. It uses cached awaitable storage to achieve

    source read 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 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 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 source's

    buffer sequence is empty, or when the underlying source'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 source

    // Owning - takes ownership of the source

    any_read_source rs(some_source{args...});

    any_read_source rs(some_source{args...});

    // Reference - wraps without ownership

    // Reference - wraps without ownership

    some_source source;

    some_source source;

    any_read_source rs(&source);

    any_read_source rs(&source);

    mutable_buffer buf(data, size);

    mutable_buffer buf(data, size);

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

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

    @endcode

    @endcode

    @see any_read_stream, ReadSource

    @see any_read_stream, ReadSource

*/

*/

class any_read_source

class any_read_source

{

{

    struct vtable;

    struct vtable;

    struct awaitable_ops;

    struct awaitable_ops;

    template<ReadSource S>

    template<ReadSource 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_read_source();

    ~any_read_source();

    /** Construct a default instance.

    /** Construct a default instance.

        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_read_source() = default;

    any_read_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_read_source(any_read_source const&) = delete;

    any_read_source(any_read_source const&) = delete;

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

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

    /** Construct by moving.

    /** Construct by moving.

        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.

    */

    */

    {

    {

    /** Assign by moving.

    /** Assign by moving.

        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_read_source&

    any_read_source&

    operator=(any_read_source&& other) noexcept;

    operator=(any_read_source&& other) noexcept;

    /** Construct by taking ownership of a ReadSource.

    /** Construct by taking ownership of a ReadSource.

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

    template<ReadSource S>

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

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

    any_read_source(S s);

    any_read_source(S s);

    /** Construct by wrapping a ReadSource without ownership.

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

    template<ReadSource S>

    any_read_source(S* s);

    any_read_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

    {

    {

    }

    }

    /** Initiate a partial read operation.

    /** Initiate a partial read operation.

        Attempt to read up to `buffer_size( buffers )` bytes into

        Attempt to read up to `buffer_size( buffers )` bytes into

        the provided buffer sequence. May fill less than the

        the provided buffer sequence. May fill less than the

        full sequence.

        full sequence.

        @param buffers The buffer sequence to read into.

        @param buffers The buffer sequence to read into.

        @return An awaitable that await-returns `(error_code,std::size_t)`.

        @return An awaitable that await-returns `(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 source's awaitable reports immediate

        @li The underlying source'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 read for guaranteed

        entire buffer sequence. Use @ref read for guaranteed

        complete transfer.

        complete transfer.

        @par Preconditions

        @par Preconditions

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

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

        The caller must not call this function again after a prior

        The caller must not call this function again after a prior

        call returned an error (including EOF).

        call returned an error (including EOF).

    */

    */

    template<MutableBufferSequence MB>

    template<MutableBufferSequence MB>

    auto

    auto

    read_some(MB buffers);

    read_some(MB buffers);

    /** Initiate a complete read operation.

    /** Initiate a complete read operation.

        Reads data into the provided buffer sequence by forwarding

        Reads data into the provided buffer sequence by forwarding

        to the underlying source's `read` operation. Large buffer

        to the underlying source's `read` operation. Large buffer

        sequences are processed in windows, with each window

        sequences are processed in windows, with each window

        forwarded as a separate `read` call to the underlying source.

        forwarded as a separate `read` call to the underlying source.

        The operation completes when the entire buffer sequence is

        The operation completes when the entire buffer sequence is

        filled, end-of-file is reached, or an error occurs.

        filled, end-of-file is reached, or an error occurs.

        @param buffers The buffer sequence to read into.

        @param buffers The buffer sequence to read into.

        @return An awaitable that await-returns `(error_code,std::size_t)`.

        @return An awaitable that await-returns `(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 source's `read` awaitable reports

        @li The underlying source's `read` awaitable reports

            immediate readiness via `await_ready`.

            immediate readiness via `await_ready`.

        @par Postconditions

        @par Postconditions

        Exactly one of the following is true on return:

        Exactly one of the following is true on return:

        @li **Success**: `!ec` and `n == buffer_size(buffers)`.

        @li **Success**: `!ec` and `n == buffer_size(buffers)`.

            The entire buffer was filled.

            The entire buffer was filled.

        @li **End-of-stream or Error**: `ec` and `n` indicates

        @li **End-of-stream or Error**: `ec` and `n` indicates

            the number of bytes transferred before the failure.

            the number of bytes transferred before the failure.

        @par Preconditions

        @par Preconditions

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

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

        The caller must not call this function again after a prior

        The caller must not call this function again after a prior

        call returned an error (including EOF).

        call returned an error (including EOF).

    */

    */

    template<MutableBufferSequence MB>

    template<MutableBufferSequence MB>

    io_task<std::size_t>

    io_task<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<ReadSource S>

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

    }

    }

private:

private:

    auto

    auto

    read_(std::span<mutable_buffer const> buffers);

    read_(std::span<mutable_buffer const> buffers);

};

};

// ordered by call sequence for cache line coherence

// ordered by call sequence for cache line coherence

struct any_read_source::awaitable_ops

struct any_read_source::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;

};

};

// ordered by call frequency for cache line coherence

// ordered by call frequency for cache line coherence

struct any_read_source::vtable

struct any_read_source::vtable

{

{

    awaitable_ops const* (*construct_read_some_awaitable)(

    awaitable_ops const* (*construct_read_some_awaitable)(

        void* source,

        void* source,

        void* storage,

        void* storage,

        std::span<mutable_buffer const> buffers);

        std::span<mutable_buffer const> buffers);

    awaitable_ops const* (*construct_read_awaitable)(

    awaitable_ops const* (*construct_read_awaitable)(

        void* source,

        void* source,

        void* storage,

        void* storage,

        std::span<mutable_buffer const> buffers);

        std::span<mutable_buffer const> buffers);

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

template<ReadSource S>

struct any_read_source::vtable_for_impl

struct any_read_source::vtable_for_impl

{

{

    using ReadSomeAwaitable = decltype(std::declval<S&>().read_some(

    using ReadSomeAwaitable = decltype(std::declval<S&>().read_some(

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

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

    using ReadAwaitable = decltype(std::declval<S&>().read(

    using ReadAwaitable = decltype(std::declval<S&>().read(

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

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

    static void

    static void

    {

    {

    static awaitable_ops const*

    static awaitable_ops const*

        void* source,

        void* source,

        void* storage,

        void* storage,

        std::span<mutable_buffer const> buffers)

        std::span<mutable_buffer const> buffers)

    {

    {

        static constexpr awaitable_ops ops = {

        static constexpr awaitable_ops ops = {

            },

            },

            },

            },

            },

            },

            }

            }

        };

        };

    }

    }

    static awaitable_ops const*

    static awaitable_ops const*

        void* source,

        void* source,

        void* storage,

        void* storage,

        std::span<mutable_buffer const> buffers)

        std::span<mutable_buffer const> buffers)

    {

    {

        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(ReadSomeAwaitable) > sizeof(ReadAwaitable)

        sizeof(ReadSomeAwaitable) > sizeof(ReadAwaitable)

            ? sizeof(ReadSomeAwaitable)

            ? sizeof(ReadSomeAwaitable)

            : sizeof(ReadAwaitable);

            : sizeof(ReadAwaitable);

    static constexpr std::size_t max_awaitable_align =

    static constexpr std::size_t max_awaitable_align =

        alignof(ReadSomeAwaitable) > alignof(ReadAwaitable)

        alignof(ReadSomeAwaitable) > alignof(ReadAwaitable)

            ? alignof(ReadSomeAwaitable)

            ? alignof(ReadSomeAwaitable)

            : alignof(ReadAwaitable);

            : alignof(ReadAwaitable);

    static constexpr vtable value = {

    static constexpr vtable value = {

        &construct_read_some_awaitable_impl,

        &construct_read_some_awaitable_impl,

        &construct_read_awaitable_impl,

        &construct_read_awaitable_impl,

        max_awaitable_size,

        max_awaitable_size,

        max_awaitable_align,

        max_awaitable_align,

        &do_destroy_impl

        &do_destroy_impl

    };

    };

};

};

inline

inline

{

{

    {

    {

    }

    }

    {

    {

    }

    }

inline any_read_source&

inline any_read_source&

{

{

    {

    {

        {

        {

        }

        }

        {

        {

        }

        }

    }

    }

}

}

template<ReadSource S>

template<ReadSource S>

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

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

{

{

    struct guard {

    struct guard {

        any_read_source* self;

        any_read_source* self;

        bool committed = false;

        bool committed = false;

            }

            }

    // Preallocate the awaitable storage

    // Preallocate the awaitable storage

template<ReadSource S>

template<ReadSource S>

{

{

    // Preallocate the awaitable storage

    // Preallocate the awaitable storage

template<MutableBufferSequence MB>

template<MutableBufferSequence MB>

auto

auto

{

{

    struct awaitable

    struct awaitable

    {

    {

        any_read_source* self_;

        any_read_source* self_;

        mutable_buffer_array<detail::max_iovec_> ba_;

        mutable_buffer_array<detail::max_iovec_> ba_;

        {

        {

        bool

        bool

        {

        {

        }

        }

        std::coroutine_handle<>

        std::coroutine_handle<>

        {

        {

        }

        }

        io_result<std::size_t>

        io_result<std::size_t>

        {

        {

            struct guard {

            struct guard {

                any_read_source* self;

                any_read_source* self;

    };

    };

}

}

inline auto

inline auto

{

{

    struct awaitable

    struct awaitable

    {

    {

        any_read_source* self_;

        any_read_source* self_;

        std::span<mutable_buffer const> buffers_;

        std::span<mutable_buffer const> buffers_;

        bool

        bool