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.
 
24 +
 
25 + 
    Concrete backends (epoll, IOCP, kqueue, select) derive from
 
26 + 
    this to implement the reactor/proactor event loop. The
 
27 + 
    @ref io_context delegates all scheduling operations here.
 
28 +
 
29 + 
    @see io_context, native_scheduler
 
30 + 
*/
23   
struct BOOST_COROSIO_DECL scheduler
31   
struct BOOST_COROSIO_DECL scheduler
24   
{
32   
{
25 - 
    virtual ~scheduler()                             = default;
33 + 
    virtual ~scheduler() = default;
 
34 +
 
35 + 
    /// Post a coroutine handle for deferred execution.
26 - 
    virtual void post(scheduler_op*) const           = 0;
 
27   
    virtual void post(std::coroutine_handle<>) const = 0;
36   
    virtual void post(std::coroutine_handle<>) const = 0;
28  
37  
29 - 
    virtual void work_started() noexcept  = 0;
38 + 
    /// Post a scheduler operation for deferred execution.
 
39 + 
    virtual void post(scheduler_op*) const = 0;
 
40 +
 
41 + 
    /// Increment the outstanding work count.
 
42 + 
    virtual void work_started() noexcept = 0;
 
43 +
 
44 + 
    /// Decrement the outstanding work count.
30   
    virtual void work_finished() noexcept = 0;
45   
    virtual void work_finished() noexcept = 0;
31  
46  
 
47 + 
    /// Check if the calling thread is running the event loop.
32   
    virtual bool running_in_this_thread() const noexcept = 0;
48   
    virtual bool running_in_this_thread() const noexcept = 0;
33 - 
    virtual void stop()                                  = 0;
49 +
34 - 
    virtual bool stopped() const noexcept                = 0;
50 + 
    /// Signal the event loop to stop.
35 - 
    virtual void restart()                               = 0;
51 + 
    virtual void stop() = 0;
36 - 
    virtual std::size_t run()                            = 0;
52 +
37 - 
    virtual std::size_t run_one()                        = 0;
53 + 
    /// Check if the event loop has been stopped.
38 - 
    virtual std::size_t wait_one(long usec)              = 0;
54 + 
    virtual bool stopped() const noexcept = 0;
39 - 
    virtual std::size_t poll()                           = 0;
55 +
40 - 
    virtual std::size_t poll_one()                       = 0;
56 + 
    /// Reset the stopped state so `run()` can be called again.
 
57 + 
    virtual void restart() = 0;
 
58 +
 
59 + 
    /// Run the event loop, blocking until all work completes.
 
60 + 
    virtual std::size_t run() = 0;
 
61 +
 
62 + 
    /// Run one handler, blocking until one completes.
 
63 + 
    virtual std::size_t run_one() = 0;
 
64 +
 
65 + 
    /** Run one handler, blocking up to @p usec microseconds.
 
66 +
 
67 + 
        @param usec Maximum wait time in microseconds.
 
68 +
 
69 + 
        @return The number of handlers executed (0 or 1).
 
70 + 
    */
 
71 + 
    virtual std::size_t wait_one(long usec) = 0;
 
72 +
 
73 + 
    /// Run all ready handlers without blocking.
 
74 + 
    virtual std::size_t poll() = 0;
 
75 +
 
76 + 
    /// Run at most one ready handler without blocking.
 
77 + 
    virtual std::size_t poll_one() = 0;
41   
};
78   
};
42  
79  
43   
} // namespace boost::corosio::detail
80   
} // namespace boost::corosio::detail
44  
81  
45   
#endif
82   
#endif