Diff coverage report for

//

//

// Copyright (c) 2026 Michael Vandeberg

// Copyright (c) 2026 Michael Vandeberg

//

//

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

#ifndef BOOST_CAPY_QUITTER_HPP

#define BOOST_CAPY_QUITTER_HPP

#define BOOST_CAPY_QUITTER_HPP

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#include <exception>

#include <exception>

#include <optional>

#include <optional>

#include <type_traits>

#include <type_traits>

#include <utility>

#include <utility>

/* Stop-aware coroutine task.

/* Stop-aware coroutine task.

   quitter<T> is identical to task<T> except that when the stop token

   quitter<T> is identical to task<T> except that when the stop token

   is triggered, the coroutine body never sees the cancellation.  The

   is triggered, the coroutine body never sees the cancellation.  The

   promise intercepts it on resume (in transform_awaiter::await_resume)

   promise intercepts it on resume (in transform_awaiter::await_resume)

   and throws a sentinel exception that unwinds through RAII destructors

   and throws a sentinel exception that unwinds through RAII destructors

   to final_suspend.  The parent sees a "stopped" completion.

   to final_suspend.  The parent sees a "stopped" completion.

   See doc/quitter.md for the full design rationale. */

   See doc/quitter.md for the full design rationale. */

namespace boost {

namespace boost {

namespace capy {

namespace capy {

namespace detail {

namespace detail {

// Reuse the same return-value storage as task<T>.

// Reuse the same return-value storage as task<T>.

// task_return_base is defined in task.hpp, but quitter needs its own

// task_return_base is defined in task.hpp, but quitter needs its own

// copy to avoid a header dependency on task.hpp.

// copy to avoid a header dependency on task.hpp.

template<typename T>

template<typename T>

struct quitter_return_base

struct quitter_return_base

{

{

    std::optional<T> result_;

    std::optional<T> result_;

    {

    {

    {

    {

    }

    }

};

};

template<>

template<>

struct quitter_return_base<void>

struct quitter_return_base<void>

{

{

    {

    {

};

};

} // namespace detail

} // namespace detail

/** Stop-aware lazy coroutine task satisfying @ref IoRunnable.

/** Stop-aware lazy coroutine task satisfying @ref IoRunnable.

    When the stop token is triggered, the next `co_await` inside the

    When the stop token is triggered, the next `co_await` inside the

    coroutine short-circuits: the body never sees the result and RAII

    coroutine short-circuits: the body never sees the result and RAII

    destructors run normally.  The parent observes a "stopped"

    destructors run normally.  The parent observes a "stopped"

    completion via @ref promise_type::stopped.

    completion via @ref promise_type::stopped.

    Everything else — frame allocation, environment propagation,

    Everything else — frame allocation, environment propagation,

    symmetric transfer, move semantics — is identical to @ref task.

    symmetric transfer, move semantics — is identical to @ref task.

    @tparam T The result type.  Use `quitter<>` for `quitter<void>`.

    @tparam T The result type.  Use `quitter<>` for `quitter<void>`.

    @see task, IoRunnable, IoAwaitable

    @see task, IoRunnable, IoAwaitable

*/

*/

template<typename T = void>

template<typename T = void>

struct [[nodiscard]] BOOST_CAPY_CORO_AWAIT_ELIDABLE

struct [[nodiscard]] BOOST_CAPY_CORO_AWAIT_ELIDABLE

    quitter

    quitter

{

{

    struct promise_type

    struct promise_type

        : io_awaitable_promise_base<promise_type>

        : io_awaitable_promise_base<promise_type>

        , detail::quitter_return_base<T>

        , detail::quitter_return_base<T>

    {

    {

    private:

    private:

        friend quitter;

        friend quitter;

        enum class completion { running, value, exception, stopped };

        enum class completion { running, value, exception, stopped };

        union { std::exception_ptr ep_; };

        union { std::exception_ptr ep_; };

        completion state_;

        completion state_;

    public:

    public:

        {

        {

        {

        {

        /// Return a non-null exception_ptr when the coroutine threw

        /// Return a non-null exception_ptr when the coroutine threw

        /// or was stopped.  Stopped quitters report the sentinel

        /// or was stopped.  Stopped quitters report the sentinel

        /// stop_requested_exception so that run_async routes to

        /// stop_requested_exception so that run_async routes to

        /// the error handler instead of accessing a non-existent

        /// the error handler instead of accessing a non-existent

        /// result.

        /// result.

        {

        {

        }

        }

        /// True when the coroutine was stopped via the stop token.

        /// True when the coroutine was stopped via the stop token.

        {

        {

        }

        }

        {

        {

            return quitter{

            return quitter{

        }

        }

        {

        {

            struct awaiter

            struct awaiter

            {

            {

                promise_type* p_;

                promise_type* p_;

                {

                {

                }

                }

                {

                {

                // Potentially-throwing: checks the stop token before

                // Potentially-throwing: checks the stop token before

                // the coroutine body executes its first statement.

                // the coroutine body executes its first statement.

                {

                {

            };

            };

        }

        }

        {

        {

            struct awaiter

            struct awaiter

            {

            {

                promise_type* p_;

                promise_type* p_;

                {

                {

                }

                }

                    std::coroutine_handle<>) const noexcept

                    std::coroutine_handle<>) const noexcept

                {

                {

                }

                }

                {

                {

            };

            };

        }

        }

        {

        {

            try

            try

            {

            {

            }

            }

            {

            {

                // Store the exception_ptr so that run_async's

                // Store the exception_ptr so that run_async's

                // invoke_impl routes to the error handler

                // invoke_impl routes to the error handler

                // instead of accessing a non-existent result.

                // instead of accessing a non-existent result.

                    std::current_exception());

                    std::current_exception());

            }

            }

            {

            {

                    std::current_exception());

                    std::current_exception());

            }

            }

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

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

        // transform_awaitable — the key difference from task<T>

        // transform_awaitable — the key difference from task<T>

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

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

        template<class Awaitable>

        template<class Awaitable>

        struct transform_awaiter

        struct transform_awaiter

        {

        {

            std::decay_t<Awaitable> a_;

            std::decay_t<Awaitable> a_;

            promise_type* p_;

            promise_type* p_;

            {

            {

            }

            }

            // Check the stop token BEFORE the coroutine body

            // Check the stop token BEFORE the coroutine body

            // sees the result of the I/O operation.

            // sees the result of the I/O operation.

            {

            {

            }

            }

            template<class Promise>

            template<class Promise>

                std::coroutine_handle<Promise> h) noexcept

                std::coroutine_handle<Promise> h) noexcept

            {

            {

                using R = decltype(

                using R = decltype(

                    a_.await_suspend(h, p_->environment()));

                    a_.await_suspend(h, p_->environment()));

                if constexpr (std::is_same_v<

                if constexpr (std::is_same_v<

                    R, std::coroutine_handle<>>)

                    R, std::coroutine_handle<>>)

                else

                else

            }

            }

        };

        };

        template<class Awaitable>

        template<class Awaitable>

        {

        {

            using A = std::decay_t<Awaitable>;

            using A = std::decay_t<Awaitable>;

            if constexpr (IoAwaitable<A>)

            if constexpr (IoAwaitable<A>)

            {

            {

                return transform_awaiter<Awaitable>{

                return transform_awaiter<Awaitable>{

            }

            }

            else

            else

            {

            {

                static_assert(sizeof(A) == 0,

                static_assert(sizeof(A) == 0,

                    "requires IoAwaitable");

                    "requires IoAwaitable");

            }

            }

    };

    };

    std::coroutine_handle<promise_type> h_;

    std::coroutine_handle<promise_type> h_;

    /// Destroy the quitter and its coroutine frame if owned.

    /// Destroy the quitter and its coroutine frame if owned.

    {

    {

    /// Return false; quitters are never immediately ready.

    /// Return false; quitters are never immediately ready.

    {

    {

    }

    }

    /** Return the result, rethrow exception, or propagate stop.

    /** Return the result, rethrow exception, or propagate stop.

        When stopped, throws stop_requested_exception so that a

        When stopped, throws stop_requested_exception so that a

        parent quitter also stops.  A parent task<T> will see this

        parent quitter also stops.  A parent task<T> will see this

        as an unhandled exception — by design.

        as an unhandled exception — by design.

    */

    */

    {

    {

        if constexpr (! std::is_void_v<T>)

        if constexpr (! std::is_void_v<T>)

        else

        else

    }

    }

    /// Start execution with the caller's context.

    /// Start execution with the caller's context.

        std::coroutine_handle<> cont,

        std::coroutine_handle<> cont,

        io_env const* env)

        io_env const* env)

    {

    {

    }

    }

    /// Return the coroutine handle.

    /// Return the coroutine handle.

    {

    {

    }

    }

    /// Release ownership of the coroutine frame.

    /// Release ownership of the coroutine frame.

    {

    {

    quitter(quitter const&) = delete;

    quitter(quitter const&) = delete;

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

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

    /// Construct by moving, transferring ownership.

    /// Construct by moving, transferring ownership.

    {

    {

    /// Assign by moving, transferring ownership.

    /// Assign by moving, transferring ownership.

    quitter& operator=(quitter&& other) noexcept

    quitter& operator=(quitter&& other) noexcept

    {

    {

        if(this != &other)

        if(this != &other)

        {

        {

            if(h_)

            if(h_)

                h_.destroy();

                h_.destroy();

            h_ = std::exchange(other.h_, nullptr);

            h_ = std::exchange(other.h_, nullptr);

        }

        }

        return *this;

        return *this;

    }

    }

private:

private:

    {

    {

};

};

} // namespace capy

} // namespace capy

} // namespace boost

} // namespace boost

#endif

#endif