1   
//
1   
//
2   
// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
2   
// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
3   
// Copyright (c) 2026 Steve Gerbino
3   
// Copyright (c) 2026 Steve Gerbino
4   
//
4   
//
5   
// Distributed under the Boost Software License, Version 1.0. (See accompanying
5   
// Distributed under the Boost Software License, Version 1.0. (See accompanying
6   
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6   
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7   
//
7   
//
8   
// Official repository: https://github.com/cppalliance/corosio
8   
// Official repository: https://github.com/cppalliance/corosio
9   
//
9   
//
10  
10  
11   
#ifndef BOOST_COROSIO_DETAIL_SCHEDULER_HPP
11   
#ifndef BOOST_COROSIO_DETAIL_SCHEDULER_HPP
12   
#define BOOST_COROSIO_DETAIL_SCHEDULER_HPP
12   
#define BOOST_COROSIO_DETAIL_SCHEDULER_HPP
13  
13  
14   
#include <boost/corosio/detail/config.hpp>
14   
#include <boost/corosio/detail/config.hpp>
15   
#include <coroutine>
15   
#include <coroutine>
16  
16  
17   
#include <cstddef>
17   
#include <cstddef>
18  
18  
19   
namespace boost::corosio::detail {
19   
namespace boost::corosio::detail {
20  
20  
21   
class scheduler_op;
21   
class scheduler_op;
22  
22  
23   
/** Define the abstract interface for the event loop scheduler.
23   
/** Define the abstract interface for the event loop scheduler.
24  
24  
25   
    Concrete backends (epoll, IOCP, kqueue, select) derive from
25   
    Concrete backends (epoll, IOCP, kqueue, select) derive from
26   
    this to implement the reactor/proactor event loop. The
26   
    this to implement the reactor/proactor event loop. The
27   
    @ref io_context delegates all scheduling operations here.
27   
    @ref io_context delegates all scheduling operations here.
28  
28  
29   
    @see io_context, native_scheduler
29   
    @see io_context, native_scheduler
30   
*/
30   
*/
31   
struct BOOST_COROSIO_DECL scheduler
31   
struct BOOST_COROSIO_DECL scheduler
32   
{
32   
{
33   
    virtual ~scheduler() = default;
33   
    virtual ~scheduler() = default;
34  
34  
35   
    /// Post a coroutine handle for deferred execution.
35   
    /// Post a coroutine handle for deferred execution.
36   
    virtual void post(std::coroutine_handle<>) const = 0;
36   
    virtual void post(std::coroutine_handle<>) const = 0;
37  
37  
38   
    /// Post a scheduler operation for deferred execution.
38   
    /// Post a scheduler operation for deferred execution.
39   
    virtual void post(scheduler_op*) const = 0;
39   
    virtual void post(scheduler_op*) const = 0;
40  
40  
41   
    /// Increment the outstanding work count.
41   
    /// Increment the outstanding work count.
42   
    virtual void work_started() noexcept = 0;
42   
    virtual void work_started() noexcept = 0;
43  
43  
44   
    /// Decrement the outstanding work count.
44   
    /// Decrement the outstanding work count.
45   
    virtual void work_finished() noexcept = 0;
45   
    virtual void work_finished() noexcept = 0;
46  
46  
47   
    /// Check if the calling thread is running the event loop.
47   
    /// Check if the calling thread is running the event loop.
48   
    virtual bool running_in_this_thread() const noexcept = 0;
48   
    virtual bool running_in_this_thread() const noexcept = 0;
49  
49  
50   
    /// Signal the event loop to stop.
50   
    /// Signal the event loop to stop.
51   
    virtual void stop() = 0;
51   
    virtual void stop() = 0;
52  
52  
53   
    /// Check if the event loop has been stopped.
53   
    /// Check if the event loop has been stopped.
54   
    virtual bool stopped() const noexcept = 0;
54   
    virtual bool stopped() const noexcept = 0;
55  
55  
56   
    /// Reset the stopped state so `run()` can be called again.
56   
    /// Reset the stopped state so `run()` can be called again.
57   
    virtual void restart() = 0;
57   
    virtual void restart() = 0;
58  
58  
59   
    /// Run the event loop, blocking until all work completes.
59   
    /// Run the event loop, blocking until all work completes.
60   
    virtual std::size_t run() = 0;
60   
    virtual std::size_t run() = 0;
61  
61  
62   
    /// Run one handler, blocking until one completes.
62   
    /// Run one handler, blocking until one completes.
63   
    virtual std::size_t run_one() = 0;
63   
    virtual std::size_t run_one() = 0;
64  
64  
65   
    /** Run one handler, blocking up to @p usec microseconds.
65   
    /** Run one handler, blocking up to @p usec microseconds.
66  
66  
67   
        @param usec Maximum wait time in microseconds.
67   
        @param usec Maximum wait time in microseconds.
68  
68  
69   
        @return The number of handlers executed (0 or 1).
69   
        @return The number of handlers executed (0 or 1).
70   
    */
70   
    */
71   
    virtual std::size_t wait_one(long usec) = 0;
71   
    virtual std::size_t wait_one(long usec) = 0;
72  
72  
73   
    /// Run all ready handlers without blocking.
73   
    /// Run all ready handlers without blocking.
74   
    virtual std::size_t poll() = 0;
74   
    virtual std::size_t poll() = 0;
75  
75  
76   
    /// Run at most one ready handler without blocking.
76   
    /// Run at most one ready handler without blocking.
77   
    virtual std::size_t poll_one() = 0;
77   
    virtual std::size_t poll_one() = 0;
78   
};
78   
};
79  
79  
80   
} // namespace boost::corosio::detail
80   
} // namespace boost::corosio::detail
81  
81  
82   
#endif
82   
#endif