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/corosio

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

//

//

#ifndef BOOST_COROSIO_IO_BUFFER_PARAM_HPP

#ifndef BOOST_COROSIO_IO_BUFFER_PARAM_HPP

#define BOOST_COROSIO_IO_BUFFER_PARAM_HPP

#define BOOST_COROSIO_IO_BUFFER_PARAM_HPP

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

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

#include <boost/capy/buffers.hpp>

#include <boost/capy/buffers.hpp>

#include <cstddef>

#include <cstddef>

namespace boost::corosio {

namespace boost::corosio {

/** A type-erased buffer sequence for I/O system call boundaries.

/** A type-erased buffer sequence for I/O system call boundaries.

    This class enables I/O objects to accept any buffer sequence type

    This class enables I/O objects to accept any buffer sequence type

    across a virtual function boundary, while preserving the caller's

    across a virtual function boundary, while preserving the caller's

    typed buffer sequence at the call site. The implementation can

    typed buffer sequence at the call site. The implementation can

    then unroll the type-erased sequence into platform-native

    then unroll the type-erased sequence into platform-native

    structures (e.g., `iovec` on POSIX, `WSABUF` on Windows) for the

    structures (e.g., `iovec` on POSIX, `WSABUF` on Windows) for the

    actual system call.

    actual system call.

    @par Purpose

    @par Purpose

    When building coroutine-based I/O abstractions, a common pattern

    When building coroutine-based I/O abstractions, a common pattern

    emerges: a templated awaitable captures the caller's buffer

    emerges: a templated awaitable captures the caller's buffer

    sequence, and at `await_suspend` time, must pass it across a

    sequence, and at `await_suspend` time, must pass it across a

    virtual interface to the I/O implementation. This class solves

    virtual interface to the I/O implementation. This class solves

    the type-erasure problem at that boundary without heap allocation.

    the type-erasure problem at that boundary without heap allocation.

    @par Restricted Use Case

    @par Restricted Use Case

    This is NOT a general-purpose composable abstraction. It exists

    This is NOT a general-purpose composable abstraction. It exists

    solely for the final step in a coroutine I/O call chain where:

    solely for the final step in a coroutine I/O call chain where:

    @li A templated awaitable captures the caller's buffer sequence

    @li A templated awaitable captures the caller's buffer sequence

    @li The awaitable's `await_suspend` passes buffers across a

    @li The awaitable's `await_suspend` passes buffers across a

        virtual interface to an I/O object implementation

        virtual interface to an I/O object implementation

    @li The implementation immediately unrolls the buffers into

    @li The implementation immediately unrolls the buffers into

        platform-native structures for the system call

        platform-native structures for the system call

    @par Lifetime Model

    @par Lifetime Model

    The safety of this class depends entirely on coroutine parameter

    The safety of this class depends entirely on coroutine parameter

    lifetime extension. When a coroutine is suspended, parameters

    lifetime extension. When a coroutine is suspended, parameters

    passed to the awaitable remain valid until the coroutine resumes

    passed to the awaitable remain valid until the coroutine resumes

    or is destroyed. This class exploits that guarantee by holding

    or is destroyed. This class exploits that guarantee by holding

    only a pointer to the caller's buffer sequence.

    only a pointer to the caller's buffer sequence.

    The referenced buffer sequence is valid ONLY while the calling

    The referenced buffer sequence is valid ONLY while the calling

    coroutine remains suspended at the exact suspension point where

    coroutine remains suspended at the exact suspension point where

    `io_buffer_param` was created. Once the coroutine resumes,

    `io_buffer_param` was created. Once the coroutine resumes,

    returns, or is destroyed, all referenced data becomes invalid.

    returns, or is destroyed, all referenced data becomes invalid.

    @par Const Buffer Handling

    @par Const Buffer Handling

    This class accepts both `ConstBufferSequence` and

    This class accepts both `ConstBufferSequence` and

    `MutableBufferSequence` types. However, `copy_to` always produces

    `MutableBufferSequence` types. However, `copy_to` always produces

    `mutable_buffer` descriptors, casting away constness for const

    `mutable_buffer` descriptors, casting away constness for const

    buffer sequences. This design matches platform I/O structures

    buffer sequences. This design matches platform I/O structures

    (`iovec`, `WSABUF`) which use non-const pointers regardless of

    (`iovec`, `WSABUF`) which use non-const pointers regardless of

    the operation direction.

    the operation direction.

    @warning The caller is responsible for ensuring the type system

    @warning The caller is responsible for ensuring the type system

    is not violated. When the original buffer sequence was const

    is not violated. When the original buffer sequence was const

    (e.g., for a write operation), the implementation MUST NOT write

    (e.g., for a write operation), the implementation MUST NOT write

    to the buffers obtained from `copy_to`. The const-cast exists

    to the buffers obtained from `copy_to`. The const-cast exists

    solely to provide a uniform interface for platform I/O calls.

    solely to provide a uniform interface for platform I/O calls.

    @code

    @code

    // For write operations (const buffers):

    // For write operations (const buffers):

    void submit_write(io_buffer_param p)

    void submit_write(io_buffer_param p)

    {

    {

        capy::mutable_buffer bufs[8];

        capy::mutable_buffer bufs[8];

        auto n = p.copy_to(bufs, 8);

        auto n = p.copy_to(bufs, 8);

        // bufs[] may reference const data - DO NOT WRITE

        // bufs[] may reference const data - DO NOT WRITE

        writev(fd, reinterpret_cast<iovec*>(bufs), n);  // OK: read-only

        writev(fd, reinterpret_cast<iovec*>(bufs), n);  // OK: read-only

    }

    }

    // For read operations (mutable buffers):

    // For read operations (mutable buffers):

    void submit_read(io_buffer_param p)

    void submit_read(io_buffer_param p)

    {

    {

        capy::mutable_buffer bufs[8];

        capy::mutable_buffer bufs[8];

        auto n = p.copy_to(bufs, 8);

        auto n = p.copy_to(bufs, 8);

        // bufs[] references mutable data - safe to write

        // bufs[] references mutable data - safe to write

        readv(fd, reinterpret_cast<iovec*>(bufs), n);  // OK: writing

        readv(fd, reinterpret_cast<iovec*>(bufs), n);  // OK: writing

    }

    }

    @endcode

    @endcode

    @par Correct Usage

    @par Correct Usage

    The implementation receiving `io_buffer_param` MUST:

    The implementation receiving `io_buffer_param` MUST:

    @li Call `copy_to` immediately upon receiving the parameter

    @li Call `copy_to` immediately upon receiving the parameter

    @li Use the unrolled buffer descriptors for the I/O operation

    @li Use the unrolled buffer descriptors for the I/O operation

    @li Never store the `io_buffer_param` object itself

    @li Never store the `io_buffer_param` object itself

    @li Never store pointers obtained from `copy_to` beyond the

    @li Never store pointers obtained from `copy_to` beyond the

        immediate I/O operation

        immediate I/O operation

    @par Example: Correct Usage

    @par Example: Correct Usage

    @code

    @code

    // Templated awaitable at the call site

    // Templated awaitable at the call site

    template<class Buffers>

    template<class Buffers>

    struct write_awaitable

    struct write_awaitable

    {

    {

        Buffers bufs;

        Buffers bufs;

        io_stream* stream;

        io_stream* stream;

        bool await_ready() { return false; }

        bool await_ready() { return false; }

        void await_suspend(std::coroutine_handle<> h)

        void await_suspend(std::coroutine_handle<> h)

        {

        {

            // CORRECT: Pass to virtual interface while suspended.

            // CORRECT: Pass to virtual interface while suspended.

            // The buffer sequence 'bufs' remains valid because

            // The buffer sequence 'bufs' remains valid because

            // coroutine parameters live until resumption.

            // coroutine parameters live until resumption.

            stream->async_write_some_impl(bufs, h);

            stream->async_write_some_impl(bufs, h);

        }

        }

        io_result await_resume() { return stream->get_result(); }

        io_result await_resume() { return stream->get_result(); }

    };

    };

    // Virtual implementation - unrolls immediately

    // Virtual implementation - unrolls immediately

    void stream_impl::async_write_some_impl(

    void stream_impl::async_write_some_impl(

        io_buffer_param p,

        io_buffer_param p,

        std::coroutine_handle<> h)

        std::coroutine_handle<> h)

    {

    {

        // CORRECT: Unroll immediately into platform structure

        // CORRECT: Unroll immediately into platform structure

        iovec vecs[16];

        iovec vecs[16];

        std::size_t n = p.copy_to(

        std::size_t n = p.copy_to(

            reinterpret_cast<capy::mutable_buffer*>(vecs), 16);

            reinterpret_cast<capy::mutable_buffer*>(vecs), 16);

        // CORRECT: Use unrolled buffers for system call now

        // CORRECT: Use unrolled buffers for system call now

        submit_to_io_uring(vecs, n, h);

        submit_to_io_uring(vecs, n, h);

        // After this function returns, 'p' must not be used again.

        // After this function returns, 'p' must not be used again.

        // The iovec array is safe because it contains copies of

        // The iovec array is safe because it contains copies of

        // the pointer/size pairs, not references to 'p'.

        // the pointer/size pairs, not references to 'p'.

    }

    }

    @endcode

    @endcode

    @par UNSAFE USAGE: Storing io_buffer_param

    @par UNSAFE USAGE: Storing io_buffer_param

    @warning Never store `io_buffer_param` for later use.

    @warning Never store `io_buffer_param` for later use.

    @code

    @code

    class broken_stream

    class broken_stream

    {

    {

        io_buffer_param saved_param_;  // UNSAFE: member storage

        io_buffer_param saved_param_;  // UNSAFE: member storage

        void async_write_impl(io_buffer_param p, ...)

        void async_write_impl(io_buffer_param p, ...)

        {

        {

            saved_param_ = p;  // UNSAFE: storing for later

            saved_param_ = p;  // UNSAFE: storing for later

            schedule_write_later();

            schedule_write_later();

        }

        }

        void do_write_later()

        void do_write_later()

        {

        {

            // UNSAFE: The calling coroutine may have resumed

            // UNSAFE: The calling coroutine may have resumed

            // or been destroyed. saved_param_ now references

            // or been destroyed. saved_param_ now references

            // invalid memory!

            // invalid memory!

            capy::mutable_buffer bufs[8];

            capy::mutable_buffer bufs[8];

            saved_param_.copy_to(bufs, 8);  // UNDEFINED BEHAVIOR

            saved_param_.copy_to(bufs, 8);  // UNDEFINED BEHAVIOR

        }

        }

    };

    };

    @endcode

    @endcode

    @par UNSAFE USAGE: Storing Unrolled Pointers

    @par UNSAFE USAGE: Storing Unrolled Pointers

    @warning The pointers obtained from `copy_to` point into the

    @warning The pointers obtained from `copy_to` point into the

    caller's buffer sequence. They become invalid when the caller

    caller's buffer sequence. They become invalid when the caller

    resumes.

    resumes.

    @code

    @code

    class broken_stream

    class broken_stream

    {

    {

        capy::mutable_buffer saved_bufs_[8];  // UNSAFE

        capy::mutable_buffer saved_bufs_[8];  // UNSAFE

        std::size_t saved_count_;

        std::size_t saved_count_;

        void async_write_impl(io_buffer_param p, ...)

        void async_write_impl(io_buffer_param p, ...)

        {

        {

            // This copies pointer/size pairs into saved_bufs_

            // This copies pointer/size pairs into saved_bufs_

            saved_count_ = p.copy_to(saved_bufs_, 8);

            saved_count_ = p.copy_to(saved_bufs_, 8);

            // UNSAFE: scheduling for later while storing the

            // UNSAFE: scheduling for later while storing the

            // buffer descriptors. The pointers in saved_bufs_

            // buffer descriptors. The pointers in saved_bufs_

            // will dangle when the caller resumes!

            // will dangle when the caller resumes!

            schedule_for_later();

            schedule_for_later();

        }

        }

        void later()

        void later()

        {

        {

            // UNSAFE: saved_bufs_ contains dangling pointers

            // UNSAFE: saved_bufs_ contains dangling pointers

            for(std::size_t i = 0; i < saved_count_; ++i)

            for(std::size_t i = 0; i < saved_count_; ++i)

                write(fd_, saved_bufs_[i].data(), ...);  // UB

                write(fd_, saved_bufs_[i].data(), ...);  // UB

        }

        }

    };

    };

    @endcode

    @endcode

    @par UNSAFE USAGE: Using Outside a Coroutine

    @par UNSAFE USAGE: Using Outside a Coroutine

    @warning This class relies on coroutine lifetime semantics.

    @warning This class relies on coroutine lifetime semantics.

    Using it with callbacks or non-coroutine async patterns is

    Using it with callbacks or non-coroutine async patterns is

    undefined behavior.

    undefined behavior.

    @code

    @code

    // UNSAFE: No coroutine lifetime guarantee

    // UNSAFE: No coroutine lifetime guarantee

    void bad_callback_pattern(std::vector<char>& data)

    void bad_callback_pattern(std::vector<char>& data)

    {

    {

        capy::mutable_buffer buf(data.data(), data.size());

        capy::mutable_buffer buf(data.data(), data.size());

        // UNSAFE: In a callback model, 'buf' may go out of scope

        // UNSAFE: In a callback model, 'buf' may go out of scope

        // before the callback fires. There is no coroutine

        // before the callback fires. There is no coroutine

        // suspension to extend the lifetime.

        // suspension to extend the lifetime.

        stream.async_write(buf, [](error_code ec) {

        stream.async_write(buf, [](error_code ec) {

            // 'buf' is already destroyed!

            // 'buf' is already destroyed!

        });

        });

    }

    }

    @endcode

    @endcode

    @par UNSAFE USAGE: Passing to Another Coroutine

    @par UNSAFE USAGE: Passing to Another Coroutine

    @warning Do not pass `io_buffer_param` to a different coroutine

    @warning Do not pass `io_buffer_param` to a different coroutine

    or spawn a new coroutine that captures it.

    or spawn a new coroutine that captures it.

    @code

    @code

    void broken_impl(io_buffer_param p, std::coroutine_handle<> h)

    void broken_impl(io_buffer_param p, std::coroutine_handle<> h)

    {

    {

        // UNSAFE: Spawning a new coroutine that captures 'p'.

        // UNSAFE: Spawning a new coroutine that captures 'p'.

        // The original coroutine may resume before this new

        // The original coroutine may resume before this new

        // coroutine uses 'p'.

        // coroutine uses 'p'.

        co_spawn([p]() -> task<void> {

        co_spawn([p]() -> task<void> {

            capy::mutable_buffer bufs[8];

            capy::mutable_buffer bufs[8];

            p.copy_to(bufs, 8);  // UNSAFE: original caller may

            p.copy_to(bufs, 8);  // UNSAFE: original caller may

                                 // have resumed already!

                                 // have resumed already!

            co_return;

            co_return;

        });

        });

    }

    }

    @endcode

    @endcode

    @par UNSAFE USAGE: Multiple Virtual Hops

    @par UNSAFE USAGE: Multiple Virtual Hops

    @warning Minimize indirection. Each virtual call that passes

    @warning Minimize indirection. Each virtual call that passes

    `io_buffer_param` without immediately unrolling it increases

    `io_buffer_param` without immediately unrolling it increases

    the risk of misuse.

    the risk of misuse.

    @code

    @code

    // Risky: multiple hops before unrolling

    // Risky: multiple hops before unrolling

    void layer1(io_buffer_param p) {

    void layer1(io_buffer_param p) {

        layer2(p);  // Still haven't unrolled...

        layer2(p);  // Still haven't unrolled...

    }

    }

    void layer2(io_buffer_param p) {

    void layer2(io_buffer_param p) {

        layer3(p);  // Still haven't unrolled...

        layer3(p);  // Still haven't unrolled...

    }

    }

    void layer3(io_buffer_param p) {

    void layer3(io_buffer_param p) {

        // Finally unrolling, but the chain is fragile.

        // Finally unrolling, but the chain is fragile.

        // Any intermediate layer storing 'p' breaks everything.

        // Any intermediate layer storing 'p' breaks everything.

    }

    }

    @endcode

    @endcode

    @par UNSAFE USAGE: Fire-and-Forget Operations

    @par UNSAFE USAGE: Fire-and-Forget Operations

    @warning Do not use with detached or fire-and-forget async

    @warning Do not use with detached or fire-and-forget async

    operations where there is no guarantee the caller remains

    operations where there is no guarantee the caller remains

    suspended.

    suspended.

    @code

    @code

    task<void> caller()

    task<void> caller()

    {

    {

        char buf[1024];

        char buf[1024];

        // UNSAFE: If async_write is fire-and-forget (doesn't

        // UNSAFE: If async_write is fire-and-forget (doesn't

        // actually suspend the caller), 'buf' may be destroyed

        // actually suspend the caller), 'buf' may be destroyed

        // before the I/O completes.

        // before the I/O completes.

        stream.async_write_detached(capy::mutable_buffer(buf, 1024));

        stream.async_write_detached(capy::mutable_buffer(buf, 1024));

        // Returns immediately - 'buf' goes out of scope!

        // Returns immediately - 'buf' goes out of scope!

    }

    }

    @endcode

    @endcode

    @par Passing Convention

    @par Passing Convention

    Pass by value. The class contains only two pointers (16 bytes

    Pass by value. The class contains only two pointers (16 bytes

    on 64-bit systems), making copies trivial and clearly

    on 64-bit systems), making copies trivial and clearly

    communicating the lightweight, transient nature of this type.

    communicating the lightweight, transient nature of this type.

    @code

    @code

    // Preferred: pass by value

    // Preferred: pass by value

    void process(io_buffer_param buffers);

    void process(io_buffer_param buffers);

    // Also acceptable: pass by const reference

    // Also acceptable: pass by const reference

    void process(io_buffer_param const& buffers);

    void process(io_buffer_param const& buffers);

    @endcode

    @endcode

    @see capy::ConstBufferSequence, capy::MutableBufferSequence

    @see capy::ConstBufferSequence, capy::MutableBufferSequence

*/

*/

class io_buffer_param

class io_buffer_param

{

{

public:

public:

    /** Construct from a const buffer sequence.

    /** Construct from a const buffer sequence.

        @param bs The buffer sequence to adapt.

        @param bs The buffer sequence to adapt.

    */

    */

    template<capy::ConstBufferSequence BS>

    template<capy::ConstBufferSequence BS>

    {

    {

    /** Fill an array with buffers from the sequence.

    /** Fill an array with buffers from the sequence.

        Copies buffer descriptors from the sequence into the

        Copies buffer descriptors from the sequence into the

        destination array, skipping any zero-size buffers.

        destination array, skipping any zero-size buffers.

        This ensures the output contains only buffers with

        This ensures the output contains only buffers with

        actual data, suitable for direct use with system calls.

        actual data, suitable for direct use with system calls.

        @param dest Pointer to array of mutable buffer descriptors.

        @param dest Pointer to array of mutable buffer descriptors.

        @param n Maximum number of buffers to copy.

        @param n Maximum number of buffers to copy.

        @return The number of non-zero buffers copied.

        @return The number of non-zero buffers copied.

    */

    */

    std::size_t

    std::size_t

        capy::mutable_buffer* dest,

        capy::mutable_buffer* dest,

        std::size_t n) const noexcept

        std::size_t n) const noexcept

    {

    {

    }

    }

private:

private:

    template<capy::ConstBufferSequence BS>

    template<capy::ConstBufferSequence BS>

    static std::size_t

    static std::size_t

        void const* p,

        void const* p,

        capy::mutable_buffer* dest,

        capy::mutable_buffer* dest,

        std::size_t n)

        std::size_t n)

    {

    {

        if constexpr (capy::MutableBufferSequence<BS>)

        if constexpr (capy::MutableBufferSequence<BS>)

        {

        {

            {

            {

            }

            }

        }

        }

        else

        else

        {

        {

            {

            {

                    const_cast<char*>(

                    const_cast<char*>(

                    buf.size());

                    buf.size());

            }

            }

        }

        }

    }

    }

    using fn_t = std::size_t(*)(void const*,

    using fn_t = std::size_t(*)(void const*,

        capy::mutable_buffer*, std::size_t);

        capy::mutable_buffer*, std::size_t);

    void const* bs_;

    void const* bs_;

    fn_t fn_;

    fn_t fn_;

};

};

} // namespace boost::corosio

} // namespace boost::corosio

#endif

#endif