Diff coverage report for

//

// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)

//

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

//

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

//

#ifndef BOOST_CAPY_EXECUTOR_WORK_GUARD_HPP

#define BOOST_CAPY_EXECUTOR_WORK_GUARD_HPP

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

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

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

#include <utility>

namespace boost {

namespace capy {

/** RAII guard that keeps an executor's context from completing.

    This class holds "work" on an executor, preventing the associated

    execution context's `run()` function from returning due to lack of

    work. It calls `on_work_started()` on construction and

    `on_work_finished()` on destruction, ensuring proper work tracking.

    The guard is useful when you need to keep an execution context

    running while waiting for external events or when work will be

    posted later.

    @par RAII Semantics

    @li Construction calls `ex.on_work_started()`.

    @li Destruction calls `ex.on_work_finished()` if `owns_work()`.

    @li Copy construction creates a new work reference (calls

        `on_work_started()` again).

    @li Move construction transfers ownership without additional calls.

    @par Thread Safety

    Distinct objects may be accessed concurrently. Access to a single

    object requires external synchronization.

    @par Example

    @code

    io_context ctx;

    // Keep context running while we set things up

    auto guard = make_work_guard(ctx);

    std::thread t([&ctx]{ ctx.run(); });

    // ... post work to ctx ...

    // Allow context to complete when work is done

    guard.reset();

    t.join();

    @endcode

    @tparam Ex A type satisfying the Executor concept.

    @see make_work_guard, Executor

*/

template<Executor Ex>

class executor_work_guard

{

    Ex ex_;

    bool owns_;

public:

    /** The underlying executor type. */

    using executor_type = Ex;

    /** Construct a work guard.

        Calls `ex.on_work_started()` to inform the executor that

        work is outstanding.

        @par Exception Safety

        No-throw guarantee.

        @par Postconditions

        @li `owns_work() == true`

        @li `get_executor() == ex`

        @param ex The executor to hold work on. Moved into the guard.

    */

    explicit

    {

    /** Copy constructor.

        Creates a new work guard holding work on the same executor.

        Calls `on_work_started()` on the executor.

        @par Exception Safety

        No-throw guarantee.

        @par Postconditions

        @li `owns_work() == other.owns_work()`

        @li `get_executor() == other.get_executor()`

        @param other The work guard to copy from.

    */

    {

    /** Move constructor.

        Transfers work ownership from `other` to `*this`. Does not

        call `on_work_started()` or `on_work_finished()`.

        @par Exception Safety

        No-throw guarantee.

        @par Postconditions

        @li `owns_work()` equals the prior value of `other.owns_work()`

        @li `other.owns_work() == false`

        @param other The work guard to move from.

    */

    {

    /** Destructor.

        If `owns_work()` is `true`, calls `on_work_finished()` on

        the executor.

        @par Exception Safety

        No-throw guarantee.

    */

    {

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

    /** Return the underlying executor.

        @par Exception Safety

        No-throw guarantee.

        @return A copy of the stored executor.

    */

    executor_type

    {

    }

    /** Return whether the guard owns work.

        @par Exception Safety

        No-throw guarantee.

        @return `true` if this guard will call `on_work_finished()`

            on destruction, `false` otherwise.

    */

    bool

    {

    }

    /** Release ownership of the work.

        If `owns_work()` is `true`, calls `on_work_finished()` on

        the executor and sets ownership to `false`. Otherwise, has

        no effect.

        @par Exception Safety

        No-throw guarantee.

        @par Postconditions

        @li `owns_work() == false`

    */

    void

    {

        {

        }

};

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

/** Create a work guard from an executor.

    @par Exception Safety

    No-throw guarantee.

    @param ex The executor to create the guard for.

    @return An `executor_work_guard` holding work on `ex`.

    @see executor_work_guard

*/

template<Executor Ex>

executor_work_guard<Ex>

{

}

} // capy

} // boost

#endif