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_EX_IMMEDIATE_HPP

#ifndef BOOST_CAPY_EX_IMMEDIATE_HPP

#define BOOST_CAPY_EX_IMMEDIATE_HPP

#define BOOST_CAPY_EX_IMMEDIATE_HPP

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

#include <boost/capy/detail/config.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 <coroutine>

#include <coroutine>

#include <stop_token>

#include <stop_token>

#include <utility>

#include <utility>

namespace boost {

namespace boost {

namespace capy {

namespace capy {

/** An awaitable that completes immediately with a value.

/** An awaitable that completes immediately with a value.

    This awaitable wraps a synchronous result so it can be used in

    This awaitable wraps a synchronous result so it can be used in

    contexts that require an awaitable type. It never suspends - 

    contexts that require an awaitable type. It never suspends - 

    `await_ready()` always returns `true`, so the coroutine machinery

    `await_ready()` always returns `true`, so the coroutine machinery

    is optimized away by the compiler.

    is optimized away by the compiler.

    Use this to adapt synchronous operations to satisfy async concepts

    Use this to adapt synchronous operations to satisfy async concepts

    like @ref IoAwaitable without the overhead of a full coroutine frame.

    like @ref IoAwaitable without the overhead of a full coroutine frame.

    @tparam T The result type to wrap.

    @tparam T The result type to wrap.

    @par Example

    @par Example

    @code

    @code

    // Wrap a sync operation as an awaitable

    // Wrap a sync operation as an awaitable

    immediate<int> get_value()

    immediate<int> get_value()

    {

    {

        return {42};

        return {42};

    }

    }

    task<void> example()

    task<void> example()

    {

    {

        int x = co_await get_value();  // No suspension, returns 42

        int x = co_await get_value();  // No suspension, returns 42

    }

    }

    @endcode

    @endcode

    @par Satisfying WriteSink with sync operations

    @par Satisfying WriteSink with sync operations

    @code

    @code

    struct my_sync_sink

    struct my_sync_sink

    {

    {

        template<ConstBufferSequence CB>

        template<ConstBufferSequence CB>

        immediate<io_result<std::size_t>>

        immediate<io_result<std::size_t>>

        write(CB buffers)

        write(CB buffers)

        {

        {

            auto n = process_sync(buffers);

            auto n = process_sync(buffers);

            return {{{}, n}};

            return {{{}, n}};

        }

        }

        immediate<io_result<>>

        immediate<io_result<>>

        write_eof()

        write_eof()

        {

        {

            return {{}};

            return {{}};

        }

        }

    };

    };

    @endcode

    @endcode

    @see ready, io_result

    @see ready, io_result

*/

*/

template<class T>

template<class T>

struct immediate

struct immediate

{

{

    /** The wrapped value. */

    /** The wrapped value. */

    T value_;

    T value_;

    /** Always returns true - this awaitable never suspends. */

    /** Always returns true - this awaitable never suspends. */

    constexpr bool

    constexpr bool

    {

    {

    }

    }

    /** IoAwaitable protocol overload.

    /** IoAwaitable protocol overload.

        This overload allows `immediate` to satisfy the @ref IoAwaitable

        This overload allows `immediate` to satisfy the @ref IoAwaitable

        concept. Since the result is already available, the environment

        concept. Since the result is already available, the environment

        is unused.

        is unused.

        @param h The coroutine handle (unused).

        @param h The coroutine handle (unused).

        @param env The execution environment (unused).

        @param env The execution environment (unused).

        @return `std::noop_coroutine()` to indicate no suspension.

        @return `std::noop_coroutine()` to indicate no suspension.

    */

    */

    std::coroutine_handle<>

    std::coroutine_handle<>

        std::coroutine_handle<> h,

        std::coroutine_handle<> h,

        io_env const* env) const noexcept

        io_env const* env) const noexcept

    {

    {

        (void)h;

        (void)h;

        (void)env;

        (void)env;

    }

    }

    /** Returns the wrapped value.

    /** Returns the wrapped value.

        @return The stored value, moved if non-const.

        @return The stored value, moved if non-const.

    */

    */

    constexpr T

    constexpr T

    {

    {

    }

    }

    /** Returns the wrapped value (const overload). */

    /** Returns the wrapped value (const overload). */

    constexpr T const&

    constexpr T const&

    await_resume() const noexcept

    await_resume() const noexcept

    {

    {

        return value_;

        return value_;

    }

    }

};

};

/** Create an immediate awaitable for a successful io_result.

/** Create an immediate awaitable for a successful io_result.

    This helper creates an @ref immediate wrapping an @ref io_result

    This helper creates an @ref immediate wrapping an @ref io_result

    with no error and the provided values.

    with no error and the provided values.

    @par Example

    @par Example

    @code

    @code

    immediate<io_result<std::size_t>>

    immediate<io_result<std::size_t>>

    write(const_buffer buf)

    write(const_buffer buf)

    {

    {

        auto n = write_sync(buf);

        auto n = write_sync(buf);

        return ready(n);  // success with n bytes

        return ready(n);  // success with n bytes

    }

    }

    immediate<io_result<>>

    immediate<io_result<>>

    connect()

    connect()

    {

    {

        connect_sync();

        connect_sync();

        return ready();  // void success

        return ready();  // void success

    }

    }

    @endcode

    @endcode

    @return An immediate awaitable containing a successful io_result.

    @return An immediate awaitable containing a successful io_result.

    @see immediate, io_result

    @see immediate, io_result

*/

*/

inline

inline

immediate<io_result<>>

immediate<io_result<>>

{

{

}

}

/** Create an immediate awaitable for a successful io_result with one value.

/** Create an immediate awaitable for a successful io_result with one value.

    @param t1 The result value.

    @param t1 The result value.

    @return An immediate awaitable containing `io_result<T1>{{}, t1}`.

    @return An immediate awaitable containing `io_result<T1>{{}, t1}`.

*/

*/

template<class T1>

template<class T1>

immediate<io_result<T1>>

immediate<io_result<T1>>

{

{

}

}

/** Create an immediate awaitable for a successful io_result with two values.

/** Create an immediate awaitable for a successful io_result with two values.

    @param t1 The first result value.

    @param t1 The first result value.

    @param t2 The second result value.

    @param t2 The second result value.

    @return An immediate awaitable containing `io_result<T1,T2>{{}, t1, t2}`.

    @return An immediate awaitable containing `io_result<T1,T2>{{}, t1, t2}`.

*/

*/

template<class T1, class T2>

template<class T1, class T2>

immediate<io_result<T1, T2>>

immediate<io_result<T1, T2>>

{

{

}

}

/** Create an immediate awaitable for a successful io_result with three values.

/** Create an immediate awaitable for a successful io_result with three values.

    @param t1 The first result value.

    @param t1 The first result value.

    @param t2 The second result value.

    @param t2 The second result value.

    @param t3 The third result value.

    @param t3 The third result value.

    @return An immediate awaitable containing `io_result<T1,T2,T3>{{}, t1, t2, t3}`.

    @return An immediate awaitable containing `io_result<T1,T2,T3>{{}, t1, t2, t3}`.

*/

*/

template<class T1, class T2, class T3>

template<class T1, class T2, class T3>

immediate<io_result<T1, T2, T3>>

immediate<io_result<T1, T2, T3>>

{

{

}

}

/** Create an immediate awaitable for a failed io_result.

/** Create an immediate awaitable for a failed io_result.

    This helper creates an @ref immediate wrapping an @ref io_result

    This helper creates an @ref immediate wrapping an @ref io_result

    with an error code.

    with an error code.

    @par Example

    @par Example

    @code

    @code

    immediate<io_result<std::size_t>>

    immediate<io_result<std::size_t>>

    write(const_buffer buf)

    write(const_buffer buf)

    {

    {

        auto ec = write_sync(buf);

        auto ec = write_sync(buf);

        if(ec)

        if(ec)

            return ready(ec, std::size_t{0});

            return ready(ec, std::size_t{0});

        return ready(buffer_size(buf));

        return ready(buffer_size(buf));

    }

    }

    @endcode

    @endcode

    @param ec The error code.

    @param ec The error code.

    @return An immediate awaitable containing a failed io_result.

    @return An immediate awaitable containing a failed io_result.

    @see immediate, io_result

    @see immediate, io_result

*/

*/

inline

inline

immediate<io_result<>>

immediate<io_result<>>

{

{

}

}

/** Create an immediate awaitable for an io_result with error and one value.

/** Create an immediate awaitable for an io_result with error and one value.

    @param ec The error code.

    @param ec The error code.

    @param t1 The result value.

    @param t1 The result value.

    @return An immediate awaitable containing `io_result<T1>{ec, t1}`.

    @return An immediate awaitable containing `io_result<T1>{ec, t1}`.

*/

*/

template<class T1>

template<class T1>

immediate<io_result<T1>>

immediate<io_result<T1>>

{

{

}

}

/** Create an immediate awaitable for an io_result with error and two values.

/** Create an immediate awaitable for an io_result with error and two values.

    @param ec The error code.

    @param ec The error code.

    @param t1 The first result value.

    @param t1 The first result value.

    @param t2 The second result value.

    @param t2 The second result value.

    @return An immediate awaitable containing `io_result<T1,T2>{ec, t1, t2}`.

    @return An immediate awaitable containing `io_result<T1,T2>{ec, t1, t2}`.

*/

*/

template<class T1, class T2>

template<class T1, class T2>

immediate<io_result<T1, T2>>

immediate<io_result<T1, T2>>

{

{

}

}

/** Create an immediate awaitable for an io_result with error and three values.

/** Create an immediate awaitable for an io_result with error and three values.

    @param ec The error code.

    @param ec The error code.

    @param t1 The first result value.

    @param t1 The first result value.

    @param t2 The second result value.

    @param t2 The second result value.

    @param t3 The third result value.

    @param t3 The third result value.

    @return An immediate awaitable containing `io_result<T1,T2,T3>{ec, t1, t2, t3}`.

    @return An immediate awaitable containing `io_result<T1,T2,T3>{ec, t1, t2, t3}`.

*/

*/

template<class T1, class T2, class T3>

template<class T1, class T2, class T3>

immediate<io_result<T1, T2, T3>>

immediate<io_result<T1, T2, T3>>

{

{

}

}

} // namespace capy

} // namespace capy

} // namespace boost

} // namespace boost

#endif

#endif