LCOV - code coverage report
Current view: top level - corosio - io_context.hpp (source / functions) Coverage Total Hit
Test: coverage_remapped.info Lines: 100.0 % 95 95
Test Date: 2026-11-16 20:48:52 Functions: 100.0 % 31 31

           TLA  Line data    Source code
       1                 : //
       2                 : // Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
       3                 : // Copyright (c) 2026 Steve Gerbino
       4                 : // Copyright (c) 2026 Michael Vandeberg
       5                 : //
       6                 : // Distributed under the Boost Software License, Version 1.0. (See accompanying
       7                 : // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
       8                 : //
       9                 : // Official repository: https://github.com/cppalliance/corosio
      10                 : //
      11                 : 
      12                 : #ifndef BOOST_COROSIO_IO_CONTEXT_HPP
      13                 : #define BOOST_COROSIO_IO_CONTEXT_HPP
      14                 : 
      15                 : #include <boost/corosio/detail/config.hpp>
      16                 : #include <boost/corosio/detail/platform.hpp>
      17                 : #include <boost/corosio/detail/scheduler.hpp>
      18                 : #include <boost/capy/continuation.hpp>
      19                 : #include <boost/capy/ex/execution_context.hpp>
      20                 : #include <boost/capy/ex/frame_allocator.hpp>
      21                 : 
      22                 : #include <chrono>
      23                 : #include <coroutine>
      24                 : #include <cstddef>
      25                 : #include <limits>
      26                 : #include <thread>
      27                 : 
      28                 : namespace boost::corosio {
      29                 : 
      30                 : /** Selects which internal locks the scheduler and reactor elide,
      31                 :     trading thread-safety guarantees for reduced synchronization
      32                 :     overhead.
      33                 : 
      34                 :     This is the analog of Boost.Asio's `SAFE` / `UNSAFE_IO` / `UNSAFE`
      35                 :     concurrency hint constants. The tier is chosen explicitly, not derived
      36                 :     from the `concurrency_hint`. (The reverse does apply: a lockless tier
      37                 :     reduces the effective hint used for performance tuning to 1.)
      38                 : 
      39                 :     @see @ref io_context_options::locking
      40                 : */
      41                 : enum class locking_mode
      42                 : {
      43                 :     /** Full thread safety (default). All locks enabled; equivalent to
      44                 :         Boost.Asio's `SAFE`/`DEFAULT`. Any thread may use the context. */
      45                 :     safe,
      46                 : 
      47                 :     /** Disable only the per-descriptor I/O locks; keep scheduler locking.
      48                 :         Equivalent to Boost.Asio's `UNSAFE_IO`. A single thread must run
      49                 :         and drive the context. Resolver and POSIX file services remain
      50                 :         available, because they rely on scheduler locking, which stays
      51                 :         on. */
      52                 :     unsafe_io,
      53                 : 
      54                 :     /** Disable all locking (fully lockless). Equivalent to Boost.Asio's
      55                 :         `UNSAFE`.
      56                 : 
      57                 :         @par Restrictions
      58                 :         - Only one thread may call `run()` (or any run variant).
      59                 :         - Posting work from another thread is undefined behavior.
      60                 :         - DNS resolution returns `operation_not_supported`, except on
      61                 :           IOCP, whose resolver does not use the thread pool.
      62                 :         - POSIX file I/O returns `operation_not_supported`.
      63                 :         - `win_object_handle::assign()` returns `operation_not_supported`.
      64                 :         - Signal sets should not be shared across contexts. */
      65                 :     unsafe
      66                 : };
      67                 : 
      68                 : /** Configures scheduler and reactor tuning for an @ref io_context.
      69                 : 
      70                 :     All fields have defaults that match the library's built-in
      71                 :     values, so constructing a default `io_context_options` produces
      72                 :     identical behavior to an unconfigured context.
      73                 : 
      74                 :     Options that apply only to a specific backend family are ignored
      75                 :     when the active backend does not use them. The exceptions are
      76                 :     `max_events_per_poll` and `inline_budget_max`, which are
      77                 :     range-checked on every platform with a reactor backend.
      78                 : 
      79                 :     @par Example
      80                 :     @par !example configure
      81                 : 
      82                 :     @see @ref io_context, @ref native_io_context
      83                 : */
      84                 : struct io_context_options
      85                 : {
      86                 :     /** Maximum events fetched per reactor poll call.
      87                 : 
      88                 :         Controls the buffer size passed to `epoll_wait()` or
      89                 :         `kevent()`. Larger values reduce syscall frequency under
      90                 :         high load. Smaller values improve fairness between
      91                 :         connections. Must be in [ 1, `INT_MAX` ]. Where epoll is
      92                 :         available, it must also not exceed
      93                 :         `INT_MAX / sizeof(epoll_event)`, the most events one epoll wait
      94                 :         accepts. Validated on platforms with a reactor backend,
      95                 :         whichever backend is active, but only the epoll and kqueue
      96                 :         backends use it.
      97                 :     */
      98                 :     unsigned max_events_per_poll = 128;
      99                 : 
     100                 :     /** Starting inline completion budget per handler chain.
     101                 : 
     102                 :         After a posted handler executes, the reactor grants this
     103                 :         many speculative inline completions before forcing a
     104                 :         re-queue. Applies to reactor backends only.
     105                 : 
     106                 :         @note Constructing an `io_context` with `concurrency_hint > 1`
     107                 :         and all three budget fields at their defaults overrides them to
     108                 :         disable inline completion, giving post-everything mode.
     109                 :         Multi-thread workloads benefit from cross-thread work-stealing.
     110                 :         Setting any budget field to a non-default
     111                 :             value disables the override.
     112                 :     */
     113                 :     unsigned inline_budget_initial = 2;
     114                 : 
     115                 :     /** Hard ceiling on adaptive inline budget ramp-up.
     116                 : 
     117                 :         The budget doubles each cycle it is fully consumed, up to
     118                 :         this limit. Must be in [ 0, `INT_MAX` ]; validated on
     119                 :         platforms with a reactor backend, whichever backend is
     120                 :         active. Applies to reactor backends only.
     121                 :     */
     122                 :     unsigned inline_budget_max = 16;
     123                 : 
     124                 :     /** Inline budget when no other thread assists the reactor.
     125                 : 
     126                 :         When only one thread is running the event loop, this
     127                 :         value caps the inline budget to preserve fairness.
     128                 :         Applies to reactor backends only.
     129                 :     */
     130                 :     unsigned unassisted_budget = 4;
     131                 : 
     132                 :     /** Thread pool size for blocking I/O (file I/O, DNS resolution).
     133                 : 
     134                 :         Sets the number of worker threads in the shared thread pool
     135                 :         used by POSIX file services and DNS resolution. Must be at
     136                 :         least 1. Applies to POSIX backends only; ignored on IOCP
     137                 :         where file I/O uses native overlapped I/O.
     138                 :     */
     139                 :     unsigned thread_pool_size = 1;
     140                 : 
     141                 :     /** Thread-safety tier. See @ref locking_mode for the tiers and their
     142                 :         restrictions.
     143                 :     */
     144                 :     locking_mode locking = locking_mode::safe;
     145                 : 
     146                 :     /** Enable IORING_SETUP_SQPOLL on the io_uring backend.
     147                 : 
     148                 :         With SQPOLL, the kernel forks a thread that busy-polls the
     149                 :         submission ring. Submission becomes a userspace-only memory
     150                 :         store, which eliminates the `io_uring_enter` syscall on the submit
     151                 :         path. Most useful for sustained traffic. Idle thread parks
     152                 :         after `sq_thread_idle_ms` of no activity.
     153                 : 
     154                 :         Independent of `locking`. Default: off.
     155                 : 
     156                 :         Ignored on non-io_uring backends.
     157                 :     */
     158                 :     bool enable_sqpoll = false;
     159                 : 
     160                 :     /** SQ-poll idle timeout in milliseconds.
     161                 : 
     162                 :         After this many ms of no submissions, the kernel polling
     163                 :         thread sleeps. The next submit re-wakes it via SQ_WAKEUP. 0
     164                 :         means use the kernel default (1ms). Recommended for bursty
     165                 :         workloads: 100-1000ms (avoids park/unpark thrash).
     166                 : 
     167                 :         Ignored unless `enable_sqpoll` is true. Ignored on
     168                 :         non-io_uring backends.
     169                 :     */
     170                 :     unsigned sq_thread_idle_ms = 0;
     171                 : 
     172                 :     /** Pin the SQ-poll kernel thread to this CPU.
     173                 : 
     174                 :         -1 means do not pin (kernel scheduler picks). Pinning off
     175                 :         the dispatch core is recommended on latency-sensitive
     176                 :         deployments to avoid cache contention.
     177                 : 
     178                 :         Ignored unless `enable_sqpoll` is true. Ignored on
     179                 :         non-io_uring backends.
     180                 :     */
     181                 :     int sq_thread_cpu = -1;
     182                 : };
     183                 : 
     184                 : namespace detail {
     185                 : class timer_service;
     186                 : 
     187                 : /** Return the hint used for performance tuning: the lockless tiers are
     188                 :     single-threaded, so their effective hint is 1 whatever the caller passed.
     189                 : */
     190                 : inline unsigned
     191 HIT          58 : effective_concurrency_hint(
     192                 :     io_context_options const& opts, unsigned hint) noexcept
     193                 : {
     194              58 :     return opts.locking == locking_mode::safe ? hint : 1u;
     195                 : }
     196                 : } // namespace detail
     197                 : 
     198                 : /** Runs asynchronous operations and owns the I/O backend that drives them.
     199                 : 
     200                 :     The `io_context` provides an execution environment for async
     201                 :     operations. It maintains a queue of pending work items and
     202                 :     processes them when `run()` is called.
     203                 : 
     204                 :     The default and unsigned constructors select the platform's
     205                 :     native backend:
     206                 :     - Windows: IOCP
     207                 :     - Linux: epoll
     208                 :     - BSD/macOS: kqueue
     209                 :     - Other POSIX: select
     210                 : 
     211                 :     The template constructor accepts a backend tag value to
     212                 :     choose a specific backend at compile time:
     213                 : 
     214                 :     @par Example
     215                 :     @par !example construct
     216                 : 
     217                 :     @pre The context must outlive every operation posted or dispatched
     218                 :     through its executor. No thread may be executing a run variant when
     219                 :     the context is destroyed. Posting to the context
     220                 :         concurrently with, or after, its destruction is undefined
     221                 :         behavior. For a safe teardown, first stop submitting new work.
     222                 :         Then let every `run()` call return; each returns once no
     223                 :         outstanding work remains. Finally join the threads that ran the
     224                 :         loop. Only then destroy the context. Work started with
     225                 :         `capy::run` / `capy::run_async` is work-tracked, so a normal
     226                 :         `run()` completion already waits for it. Destroying the context
     227                 :         abandons every coroutine still suspended in it (see
     228                 :         @ref ~io_context).
     229                 : 
     230                 :     @par Exception Safety
     231                 :     A context that constructs is usable. The infrastructure its backend
     232                 :     needs — the completion port, the ring, the reactor's wakeup channel
     233                 :     — is created during construction. A system that refuses it therefore
     234                 :     throws from the constructor rather than from the first operation.
     235                 :     The failed construction leaves nothing open.
     236                 : 
     237                 :     An operation that completes resumes its coroutine through the
     238                 :     executor the coroutine awaited it on. If that executor's `post` or
     239                 :     `dispatch` throws, `std::terminate` is called.
     240                 : 
     241                 :     @par Thread Safety
     242                 :     Distinct objects: Safe.@n
     243                 :     Shared objects: Safe, unless the context was constructed with a
     244                 :     lockless @ref io_context_options::locking tier (`unsafe_io` or
     245                 :     `unsafe`), in which case a single thread must drive it.
     246                 : 
     247                 :     @see @ref epoll_t, @ref select_t, @ref kqueue_t, @ref iocp_t
     248                 : */
     249                 : class BOOST_COROSIO_DECL io_context : public capy::execution_context
     250                 : {
     251                 :     /// Reject invalid options before the backend is constructed.
     252                 :     void apply_options_pre_(io_context_options const& opts);
     253                 : 
     254                 :     /** Create the blocking-I/O thread pool, apply runtime tuning to the
     255                 :         scheduler and finish bringing the backend up. The tail of every
     256                 :         options constructor. The backend infrastructure whose setup reads
     257                 :         these options is created here, so a failure to create it throws
     258                 :         from the constructor. */
     259                 :     void apply_options_post_(
     260                 :         io_context_options const& opts, unsigned concurrency_hint);
     261                 : 
     262                 :     /** Create the blocking-I/O thread pool and apply only the decomposed
     263                 :         threading configuration (locking tiers), then finish bringing the
     264                 :         backend up. The tail of every plain constructor. Unlike the
     265                 :         options constructors, it deliberately leaves the reactor budget
     266                 :         at its defaults rather than engaging the multi-thread
     267                 :         post-everything heuristic. */
     268                 :     void apply_threading_(io_context_options const& opts);
     269                 : 
     270                 : protected:
     271                 :     detail::scheduler* sched_;
     272                 : 
     273                 :     // Resuming a chain installs its frame allocator on the running
     274                 :     // thread; a run call puts back what it found, so a coroutine created
     275                 :     // afterwards never reaches a resource that died with those frames.
     276                 :     struct frame_allocator_restore
     277                 :     {
     278                 :         std::pmr::memory_resource* saved =
     279                 :             capy::get_current_frame_allocator();
     280                 : 
     281           12322 :         frame_allocator_restore() = default;
     282                 :         frame_allocator_restore(frame_allocator_restore const&) = delete;
     283                 :         frame_allocator_restore&
     284                 :         operator=(frame_allocator_restore const&) = delete;
     285                 : 
     286           12322 :         ~frame_allocator_restore()
     287                 :         {
     288           12322 :             capy::set_current_frame_allocator(saved);
     289           12322 :         }
     290                 :     };
     291                 : 
     292                 : public:
     293                 :     /** Dispatches and posts work to this context; see the
     294                 :         executor_type definition below. */
     295                 :     class executor_type;
     296                 : 
     297                 :     /** Construct with default concurrency and platform backend.
     298                 : 
     299                 :         Uses `std::thread::hardware_concurrency()` (floored to 1, in
     300                 :         case it reports 0) as the concurrency hint, and the default
     301                 :         @ref locking_mode::safe tier. Select a lockless tier via
     302                 :         @ref io_context_options::locking.
     303                 : 
     304                 :         @throws std::system_error If the backend's infrastructure
     305                 :             could not be created.
     306                 :     */
     307                 :     io_context();
     308                 : 
     309                 :     /** Construct with a concurrency hint and platform backend.
     310                 : 
     311                 :         @param concurrency_hint Hint for the number of threads
     312                 :             that calls `run()`.
     313                 : 
     314                 :         @throws std::system_error If the backend's infrastructure
     315                 :             could not be created.
     316                 :     */
     317                 :     explicit io_context(unsigned concurrency_hint);
     318                 : 
     319                 :     /** Construct with runtime tuning options and platform backend.
     320                 : 
     321                 :         @param opts Runtime options controlling scheduler and
     322                 :             service behavior.
     323                 :         @param concurrency_hint Hint for the number of threads
     324                 :             that calls `run()`.
     325                 : 
     326                 :         @throws std::invalid_argument If `opts.thread_pool_size` is
     327                 :             less than 1 (POSIX), `opts.max_events_per_poll` is outside
     328                 :             the range its member documents, or `opts.inline_budget_max`
     329                 :             exceeds `INT_MAX` (platforms with a reactor backend).
     330                 : 
     331                 :         @throws std::system_error If the backend's infrastructure
     332                 :             could not be created.
     333                 :     */
     334                 :     explicit io_context(
     335                 :         io_context_options const& opts,
     336                 :         unsigned concurrency_hint = std::thread::hardware_concurrency());
     337                 : 
     338                 :     /** Construct with an explicit backend tag.
     339                 : 
     340                 :         @tparam Backend A backend tag type that provides a static
     341                 :             `construct(capy::execution_context&, unsigned)` factory
     342                 :             used to build the scheduler.
     343                 : 
     344                 :         @param backend The backend tag value selecting the I/O
     345                 :             multiplexer (e.g. `corosio::epoll`).
     346                 :         @param concurrency_hint Hint for the number of threads
     347                 :             that calls `run()`.
     348                 : 
     349                 :         @throws std::system_error If the backend's infrastructure
     350                 :             could not be created.
     351                 :     */
     352                 :     template<class Backend>
     353                 :         requires requires { Backend::construct; }
     354            4110 :     explicit io_context(
     355                 :         [[maybe_unused]] Backend backend,
     356                 :         unsigned concurrency_hint = std::thread::hardware_concurrency())
     357                 :         : capy::execution_context(this)
     358            4110 :         , sched_(nullptr)
     359                 :     {
     360            4110 :         sched_ = &Backend::construct(*this, concurrency_hint);
     361                 :         // Apply threading config only (locking tier). Unlike the options
     362                 :         // ctor, the plain path leaves the reactor budget at its defaults.
     363            4094 :         apply_threading_(io_context_options{});
     364            4110 :     }
     365                 : 
     366                 :     /** Construct with an explicit backend tag and runtime options.
     367                 : 
     368                 :         @tparam Backend A backend tag type that provides a static
     369                 :             `construct(capy::execution_context&, unsigned)` factory
     370                 :             used to build the scheduler.
     371                 : 
     372                 :         @param backend The backend tag value selecting the I/O
     373                 :             multiplexer (e.g. `corosio::epoll`).
     374                 :         @param opts Runtime options controlling scheduler and
     375                 :             service behavior.
     376                 :         @param concurrency_hint Hint for the number of threads
     377                 :             that calls `run()`.
     378                 : 
     379                 :         @throws std::invalid_argument If `opts.thread_pool_size` is
     380                 :             less than 1 (POSIX), `opts.max_events_per_poll` is outside
     381                 :             the range its member documents, or `opts.inline_budget_max`
     382                 :             exceeds `INT_MAX` (platforms with a reactor backend).
     383                 : 
     384                 :         @throws std::system_error If the backend's infrastructure
     385                 :             could not be created.
     386                 :     */
     387                 :     template<class Backend>
     388                 :         requires requires { Backend::construct; }
     389              53 :     explicit io_context(
     390                 :         [[maybe_unused]] Backend backend,
     391                 :         io_context_options const& opts,
     392                 :         unsigned concurrency_hint = std::thread::hardware_concurrency())
     393                 :         : capy::execution_context(this)
     394              53 :         , sched_(nullptr)
     395                 :     {
     396              53 :         apply_options_pre_(opts);
     397                 :         // Effective hint (1 for lockless tiers); see effective_concurrency_hint.
     398                 :         unsigned const eff =
     399              41 :             detail::effective_concurrency_hint(opts, concurrency_hint);
     400              41 :         sched_ = &Backend::construct(*this, eff);
     401              41 :         apply_options_post_(opts, eff);
     402              53 :     }
     403                 : 
     404                 :     /** Destroy the context, its services and the coroutines it holds.
     405                 : 
     406                 :         The destructor stops the loop and destroys every service. Each
     407                 :         coroutine suspended in an operation of this context, or posted to
     408                 :         it and not yet resumed, is abandoned. Its chain is unwound from
     409                 :         the top, on the executor of the chain's owner (see
     410                 :         `capy::abandon`). The precondition below makes that executor this
     411                 :         context's, so the unwind runs during this destruction.
     412                 : 
     413                 :         @pre No thread is executing a run variant.
     414                 : 
     415                 :         @pre No work crosses into another execution context. A chain
     416                 :             held here must be owned on this context. No frame of a chain
     417                 :             owned elsewhere may own I/O objects of this context, or wait
     418                 :             on a primitive that a chain held here owns. Such a chain's
     419                 :             unwind would run on the other context after this one is gone,
     420                 :             whatever the order of destruction. Stop such work and run both
     421                 :             contexts until it ends before destroying either.
     422                 : 
     423                 :         @note Every service gives up its work while the services shut
     424                 :             down, so nothing is left when they are destroyed. Work posted
     425                 :             after that anyway, for example from a service's destructor, is
     426                 :             abandoned while the services are being destroyed. Its
     427                 :             destructors must not use any service.
     428                 :     */
     429                 :     ~io_context();
     430                 : 
     431                 :     /// Copy construction is disabled; the context owns its services.
     432                 :     io_context(io_context const&) = delete;
     433                 :     /// Copy assignment is disabled; the context owns its services.
     434                 :     io_context& operator=(io_context const&) = delete;
     435                 : 
     436                 :     /** Return an executor for this context.
     437                 : 
     438                 :         The returned executor can be used to dispatch coroutines
     439                 :         and post work items to this context.
     440                 : 
     441                 :         @return An executor associated with this context.
     442                 :     */
     443                 :     executor_type get_executor() const noexcept;
     444                 : 
     445                 :     /** Signal the context to stop processing.
     446                 : 
     447                 :         This causes `run()` to return as soon as possible. Any pending
     448                 :         work items remain queued.
     449                 : 
     450                 :         On Windows, queued work may still run after `stop()`: each
     451                 :         `run()` call sees the stop only when it reaches the stop's wakeup.
     452                 : 
     453                 :         @throws std::system_error on Windows if the wakeup cannot be
     454                 :             queued, which leaves blocked `run()` callers unable to wake
     455                 :             until a later call succeeds.
     456                 :     */
     457              95 :     void stop()
     458                 :     {
     459              95 :         sched_->stop();
     460              95 :     }
     461                 : 
     462                 :     /** Return whether the context stopped.
     463                 : 
     464                 :         @return `true` after a call to `stop()` with no later
     465                 :             call to `restart()`.
     466                 :     */
     467            1274 :     bool stopped() const noexcept
     468                 :     {
     469            1274 :         return sched_->stopped();
     470                 :     }
     471                 : 
     472                 :     /** Restart the context after being stopped.
     473                 : 
     474                 :         This function must be called before `run()` can be called
     475                 :         again after a call to `stop()`.
     476                 :     */
     477            6111 :     void restart()
     478                 :     {
     479            6111 :         sched_->restart();
     480            6111 :     }
     481                 : 
     482                 :     /** Process all pending work items.
     483                 : 
     484                 :         This function blocks until it executes all pending work items,
     485                 :         or until `stop()` is called. The context is stopped
     486                 :         when there is no more outstanding work.
     487                 : 
     488                 :         @throws std::system_error if waiting on the operating system's
     489                 :             event demultiplexer fails other than by interruption or
     490                 :             another transient condition; the context can no longer
     491                 :             dispatch work. On Windows, also if a wakeup needed to
     492                 :             stop the context cannot be queued.
     493                 : 
     494                 :         @note The context must be restarted with `restart()` before
     495                 :             calling this function again after it returns.
     496                 : 
     497                 :         @return The number of handlers executed.
     498                 :     */
     499            6815 :     std::size_t run()
     500                 :     {
     501            6815 :         frame_allocator_restore restore;
     502           13625 :         return sched_->run();
     503            6815 :     }
     504                 : 
     505                 :     /** Process at most one pending work item.
     506                 : 
     507                 :         This function blocks until it executes one work item
     508                 :         or `stop()` is called. The context is stopped when there
     509                 :         is no more outstanding work.
     510                 : 
     511                 :         @throws std::system_error if waiting on the operating system's
     512                 :             event demultiplexer fails other than by interruption or
     513                 :             another transient condition; the context can no longer
     514                 :             dispatch work. On Windows, also if a wakeup needed to
     515                 :             stop the context cannot be queued.
     516                 : 
     517                 :         @note The context must be restarted with `restart()` before
     518                 :             calling this function again after it returns.
     519                 : 
     520                 :         @return The number of handlers executed (0 or 1).
     521                 :     */
     522             144 :     std::size_t run_one()
     523                 :     {
     524             144 :         frame_allocator_restore restore;
     525             286 :         return sched_->run_one();
     526             144 :     }
     527                 : 
     528                 :     /** Process work items for the specified duration.
     529                 : 
     530                 :         This function blocks until it has executed work items for the
     531                 :         specified duration, or until `stop()` is called. The context
     532                 :         is stopped when there is no more outstanding work.
     533                 : 
     534                 :         A duration of zero or less returns 0 at once, without running
     535                 :         any work or stopping the context.
     536                 : 
     537                 :         @throws std::system_error if waiting on the operating system's
     538                 :             event demultiplexer fails other than by interruption or
     539                 :             another transient condition; the context can no longer
     540                 :             dispatch work. On Windows, also if a wakeup needed to
     541                 :             stop the context cannot be queued.
     542                 : 
     543                 :         @note The context must be restarted with `restart()` before
     544                 :             calling this function again after it returns.
     545                 : 
     546                 :         @param rel_time The duration for which to process work.
     547                 : 
     548                 :         @return The number of handlers executed.
     549                 :     */
     550                 :     template<class Rep, class Period>
     551             849 :     std::size_t run_for(std::chrono::duration<Rep, Period> const& rel_time)
     552                 :     {
     553             849 :         return run_until(std::chrono::steady_clock::now() + rel_time);
     554                 :     }
     555                 : 
     556                 :     /** Process work items until the specified time.
     557                 : 
     558                 :         This function blocks until the specified time is reached
     559                 :         or `stop()` is called. The context is stopped when there
     560                 :         is no more outstanding work.
     561                 : 
     562                 :         A time that has already passed returns 0 at once, without
     563                 :         running any work or stopping the context.
     564                 : 
     565                 :         @throws std::system_error if waiting on the operating system's
     566                 :             event demultiplexer fails other than by interruption or
     567                 :             another transient condition; the context can no longer
     568                 :             dispatch work. On Windows, also if a wakeup needed to
     569                 :             stop the context cannot be queued.
     570                 : 
     571                 :         @note The context must be restarted with `restart()` before
     572                 :             calling this function again after it returns.
     573                 : 
     574                 :         @param abs_time The time point until which to process work.
     575                 : 
     576                 :         @return The number of handlers executed.
     577                 :     */
     578                 :     template<class Clock, class Duration>
     579                 :     std::size_t
     580             874 :     run_until(std::chrono::time_point<Clock, Duration> const& abs_time)
     581                 :     {
     582             874 :         std::size_t n = 0;
     583            2505 :         while (run_one_until(abs_time))
     584            1631 :             if (n != (std::numeric_limits<std::size_t>::max)())
     585            1631 :                 ++n;
     586             870 :         return n;
     587                 :     }
     588                 : 
     589                 :     /** Process at most one work item for the specified duration.
     590                 : 
     591                 :         This function blocks until it executes one work item,
     592                 :         the specified duration has elapsed, or `stop()` is called.
     593                 :         The context is stopped when there is no more outstanding work.
     594                 : 
     595                 :         A duration of zero or less returns 0 at once, without running
     596                 :         any work or stopping the context.
     597                 : 
     598                 :         @throws std::system_error if waiting on the operating system's
     599                 :             event demultiplexer fails other than by interruption or
     600                 :             another transient condition; the context can no longer
     601                 :             dispatch work. On Windows, also if a wakeup needed to
     602                 :             stop the context cannot be queued.
     603                 : 
     604                 :         @note The context must be restarted with `restart()` before
     605                 :             calling this function again after it returns.
     606                 : 
     607                 :         @param rel_time The duration for which the call may block.
     608                 : 
     609                 :         @return The number of handlers executed (0 or 1).
     610                 :     */
     611                 :     template<class Rep, class Period>
     612            1092 :     std::size_t run_one_for(std::chrono::duration<Rep, Period> const& rel_time)
     613                 :     {
     614            1092 :         return run_one_until(std::chrono::steady_clock::now() + rel_time);
     615                 :     }
     616                 : 
     617                 :     /** Process at most one work item until the specified time.
     618                 : 
     619                 :         This function blocks until it executes one work item,
     620                 :         the specified time is reached, or `stop()` is called.
     621                 :         The context is stopped when there is no more outstanding work.
     622                 : 
     623                 :         A time that has already passed returns 0 at once, without
     624                 :         running any work or stopping the context.
     625                 : 
     626                 :         @throws std::system_error if waiting on the operating system's
     627                 :             event demultiplexer fails other than by interruption or
     628                 :             another transient condition; the context can no longer
     629                 :             dispatch work. On Windows, also if a wakeup needed to
     630                 :             stop the context cannot be queued.
     631                 : 
     632                 :         @note The context must be restarted with `restart()` before
     633                 :             calling this function again after it returns.
     634                 : 
     635                 :         @param abs_time The time point until which the call may block.
     636                 : 
     637                 :         @return The number of handlers executed (0 or 1).
     638                 :     */
     639                 :     template<class Clock, class Duration>
     640                 :     std::size_t
     641            3627 :     run_one_until(std::chrono::time_point<Clock, Duration> const& abs_time)
     642                 :     {
     643            3627 :         frame_allocator_restore restore;
     644            3627 :         typename Clock::time_point now = Clock::now();
     645            3814 :         while (now < abs_time)
     646                 :         {
     647            3742 :             auto rel_time = abs_time - now;
     648            3742 :             if (rel_time > std::chrono::seconds(1))
     649            3594 :                 rel_time = std::chrono::seconds(1);
     650                 : 
     651            3742 :             std::size_t s = sched_->wait_one(
     652                 :                 static_cast<long>(
     653            3750 :                     std::chrono::duration_cast<std::chrono::microseconds>(
     654                 :                         rel_time)
     655            3742 :                         .count()));
     656                 : 
     657            3734 :             if (s || stopped())
     658            3547 :                 return s;
     659                 : 
     660             187 :             now = Clock::now();
     661                 :         }
     662              72 :         return 0;
     663            3627 :     }
     664                 : 
     665                 :     /** Process all ready work items without blocking.
     666                 : 
     667                 :         This function executes all work items that are ready to run
     668                 :         without blocking for more work. The context is stopped
     669                 :         when there is no more outstanding work.
     670                 : 
     671                 :         @throws std::system_error if waiting on the operating system's
     672                 :             event demultiplexer fails other than by interruption or
     673                 :             another transient condition; the context can no longer
     674                 :             dispatch work. On Windows, also if a wakeup needed to
     675                 :             stop the context cannot be queued.
     676                 : 
     677                 :         @note The context must be restarted with `restart()` before
     678                 :             calling this function again after it returns.
     679                 : 
     680                 :         @return The number of handlers executed.
     681                 :     */
     682            1465 :     std::size_t poll()
     683                 :     {
     684            1465 :         frame_allocator_restore restore;
     685            2928 :         return sched_->poll();
     686            1465 :     }
     687                 : 
     688                 :     /** Process at most one ready work item without blocking.
     689                 : 
     690                 :         This function executes at most one work item that is ready
     691                 :         to run without blocking for more work. The context is
     692                 :         stopped when there is no more outstanding work.
     693                 : 
     694                 :         @throws std::system_error if waiting on the operating system's
     695                 :             event demultiplexer fails other than by interruption or
     696                 :             another transient condition; the context can no longer
     697                 :             dispatch work. On Windows, also if a wakeup needed to
     698                 :             stop the context cannot be queued.
     699                 : 
     700                 :         @note The context must be restarted with `restart()` before
     701                 :             calling this function again after it returns.
     702                 : 
     703                 :         @return The number of handlers executed (0 or 1).
     704                 :     */
     705              84 :     std::size_t poll_one()
     706                 :     {
     707              84 :         frame_allocator_restore restore;
     708             166 :         return sched_->poll_one();
     709              84 :     }
     710                 : };
     711                 : 
     712                 : /** Dispatches and posts work to an I/O context.
     713                 : 
     714                 :     The executor provides the interface for posting work items and
     715                 :     dispatching coroutines to the associated context. It satisfies
     716                 :     the `capy::Executor` concept.
     717                 : 
     718                 :     Executors are lightweight handles that can be copied and compared
     719                 :     for equality. Two executors compare equal if they refer to the
     720                 :     same context.
     721                 : 
     722                 :     @par Thread Safety
     723                 :     Distinct objects: Safe.@n
     724                 :     Shared objects: Safe.
     725                 : */
     726                 : class io_context::executor_type
     727                 : {
     728                 :     io_context* ctx_ = nullptr;
     729                 : 
     730                 : public:
     731                 :     /** Constructs an executor not associated with any context. */
     732            2057 :     executor_type() = default;
     733                 : 
     734                 :     /** Construct an executor from a context.
     735                 : 
     736                 :         @param ctx The context to associate with this executor.
     737                 :     */
     738           18817 :     explicit executor_type(io_context& ctx) noexcept : ctx_(&ctx) {}
     739                 : 
     740                 :     /** Return a reference to the associated execution context.
     741                 : 
     742                 :         @return Reference to the context.
     743                 :     */
     744           46173 :     io_context& context() const noexcept
     745                 :     {
     746           46173 :         return *ctx_;
     747                 :     }
     748                 : 
     749                 :     /** Check if the current thread is running this executor's context.
     750                 : 
     751                 :         @return `true` if `run()` is being called on this thread.
     752                 :     */
     753          468497 :     bool running_in_this_thread() const noexcept
     754                 :     {
     755                 :         // The innermost scheduler answers the common case without a
     756                 :         // virtual call or a frame walk.
     757          492794 :         return detail::running_scheduler.get() == ctx_->sched_ ||
     758          492794 :             ctx_->sched_->running_in_this_thread();
     759                 :     }
     760                 : 
     761                 :     /** Informs the executor that work is beginning.
     762                 : 
     763                 :         Must be paired with `on_work_finished()`.
     764                 :     */
     765           25595 :     void on_work_started() const noexcept
     766                 :     {
     767           25595 :         ctx_->sched_->work_started();
     768           25595 :     }
     769                 : 
     770                 :     /** Informs the executor that work has completed.
     771                 : 
     772                 :         @pre A preceding call to `on_work_started()` on an equal executor.
     773                 :     */
     774           25595 :     void on_work_finished() const noexcept
     775                 :     {
     776           25595 :         ctx_->sched_->work_finished();
     777           25595 :     }
     778                 : 
     779                 :     /** Dispatch a continuation.
     780                 : 
     781                 :         Returns a handle for symmetric transfer. If called from
     782                 :         within `run()`, returns `c.h`. Otherwise posts `c` for
     783                 :         later execution and returns `std::noop_coroutine()`.
     784                 : 
     785                 :         @param c The continuation to dispatch.
     786                 : 
     787                 :         @return A handle for symmetric transfer or `std::noop_coroutine()`.
     788                 : 
     789                 :         @pre The associated context must outlive this call. Dispatching
     790                 :             concurrently with, or after, the context's destruction is
     791                 :             undefined behavior.
     792                 :     */
     793          468490 :     std::coroutine_handle<> dispatch(capy::continuation& c) const
     794                 :     {
     795          468490 :         if (running_in_this_thread())
     796          444196 :             return c.h;
     797           24294 :         post(c);
     798           24294 :         return std::noop_coroutine();
     799                 :     }
     800                 : 
     801                 :     /** Post a continuation for deferred execution.
     802                 : 
     803                 :         Enqueues `c` directly on the scheduler's ready queue.
     804                 :         No heap allocation occurs.
     805                 : 
     806                 :         @param c The continuation to enqueue.
     807                 : 
     808                 :         @pre The associated context must outlive this call. Posting
     809                 :             concurrently with, or after, the context's destruction is
     810                 :             undefined behavior.
     811                 :     */
     812          236933 :     void post(capy::continuation& c) const
     813                 :     {
     814          236933 :         ctx_->sched_->post(c);
     815          236933 :     }
     816                 : 
     817                 :     /** Post a bare coroutine handle for deferred execution.
     818                 : 
     819                 :         Heap-allocates a `scheduler_op` to wrap the handle. A caller
     820                 :         that already owns a `capy::continuation` can post it directly
     821                 :         via the `post(capy::continuation&)` overload to avoid the
     822                 :         allocation.
     823                 : 
     824                 :         A handle still queued when the context is torn down is
     825                 :         destroyed alone, since it carries no owner to unwind its chain
     826                 :         from. Post a coroutine that another frame awaits through the
     827                 :         `post(capy::continuation&)` overload, with its owner set.
     828                 : 
     829                 :         @param h The coroutine handle to post.
     830                 : 
     831                 :         @pre The associated context must outlive this call. Posting
     832                 :             concurrently with, or after, the context's destruction is
     833                 :             undefined behavior.
     834                 : 
     835                 :         @pre Nothing awaits `h`.
     836                 :     */
     837            3862 :     void post(std::coroutine_handle<> h) const
     838                 :     {
     839            3862 :         ctx_->sched_->post(h);
     840            3862 :     }
     841                 : 
     842                 :     /** Compare two executors for equality.
     843                 : 
     844                 :         @return `true` if both executors refer to the same context.
     845                 :     */
     846               2 :     bool operator==(executor_type const& other) const noexcept
     847                 :     {
     848               2 :         return ctx_ == other.ctx_;
     849                 :     }
     850                 : 
     851                 :     /** Compare two executors for inequality.
     852                 : 
     853                 :         @return `true` if the executors refer to different contexts.
     854                 :     */
     855                 :     bool operator!=(executor_type const& other) const noexcept
     856                 :     {
     857                 :         return ctx_ != other.ctx_;
     858                 :     }
     859                 : };
     860                 : 
     861                 : inline io_context::executor_type
     862           18817 : io_context::get_executor() const noexcept
     863                 : {
     864           18817 :     return executor_type(const_cast<io_context&>(*this));
     865                 : }
     866                 : 
     867                 : } // namespace boost::corosio
     868                 : 
     869                 : #endif // BOOST_COROSIO_IO_CONTEXT_HPP
        

Generated by: LCOV version 2.3