Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
//
// Copyright (c) 2026 Steve Gerbino
//
// 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/corosio
//

#ifndef BOOST_COROSIO_NATIVE_DETAIL_REACTOR_REACTOR_DEFER_POLICY_HPP
#define BOOST_COROSIO_NATIVE_DETAIL_REACTOR_REACTOR_DEFER_POLICY_HPP

namespace boost::corosio::detail {

/** Decide whether the reactor sentinel waits behind queued handlers.

When the sentinel reaches the front of the queue with handlers still
queued, running those handlers first usually saves a reactor pass:
they tend to start the next I/O themselves. That bet loses when the
handlers drain the queue, so the deferred turn has no other work to
overlap with and a poll that would have found completed I/O comes too
late. The policy scores each deferral by what the deferred turn found
and stops deferring while losses are frequent.

A deferred turn that found the queue empty costs more than one that
found handlers repays, so deferring continues only while fewer than
about one deferral in `miss_cost + 1` empties the queue. Each turn
that polls instead of deferring lets the score decay, so a workload
that changes is tried again.

@par Thread Safety
Distinct objects: Safe.
Shared objects: Unsafe. The scheduler calls it under its own mutex.
*/
class reactor_defer_policy
{
int score_ = 0;

public:
/// Score added by a deferred turn that found the queue empty.
static constexpr int miss_cost = 8;

/// Score at or above which the sentinel polls instead of deferring.
static constexpr int threshold = 8;

/// Highest score, which bounds how long deferring stays off.
static constexpr int max_score = 64;

/// Check whether the sentinel may wait behind queued handlers.
bool may_defer() const noexcept
{
return score_ < threshold;
}

/** Record what a deferred turn of the sentinel found.

@param handlers_queued `true` if handlers were still queued, so
the deferral cost nothing.
*/
void on_deferred_turn(bool handlers_queued) noexcept
{
if (handlers_queued)
{
if (score_ > 0)
--score_;
}
else
{
score_ =
score_ > max_score - miss_cost ? max_score : score_ + miss_cost;
}
}

/// Record a turn that polled because deferring was off.
void on_polled_instead() noexcept
{
if (score_ > 0)
--score_;
}

/// Forget the history, as for a fresh run.
void reset() noexcept
{
score_ = 0;
}
};

} // namespace boost::corosio::detail

#endif // BOOST_COROSIO_NATIVE_DETAIL_REACTOR_REACTOR_DEFER_POLICY_HPP
32 changes: 32 additions & 0 deletions include/boost/corosio/native/detail/reactor/reactor_scheduler.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@
#include <boost/corosio/detail/scheduler_op.hpp>
#include <boost/corosio/detail/thread_local_ptr.hpp>
#include <boost/corosio/detail/timer_service.hpp>
#include <boost/corosio/native/detail/reactor/reactor_defer_policy.hpp>

#include <atomic>
#include <chrono>
Expand Down Expand Up @@ -333,6 +334,11 @@ class reactor_scheduler : public scheduler
std::atomic<bool> stopped_{false};
mutable std::atomic<bool> task_running_{false};
mutable bool task_interrupted_ = false;
// Set while the sentinel waits behind queued handlers (guarded by
// mutex_).
bool task_deferred_ = false;
// Whether waiting is paying off (guarded by mutex_).
reactor_defer_policy defer_policy_;

// Descriptors retired during the running reactor pass (guarded by
// mutex_).
Expand Down Expand Up @@ -635,6 +641,11 @@ reactor_scheduler::stopped() const noexcept
inline void
reactor_scheduler::restart()
{
// A run can end with the sentinel marked deferred; clearing the
// mark lets the next run defer it again.
lock_type lock(mutex_);
task_deferred_ = false;
defer_policy_.reset();
stopped_.store(false, std::memory_order_release);
}

Expand Down Expand Up @@ -1042,6 +1053,27 @@ reactor_scheduler::do_one(lock_type& lock, long timeout_us, context_type& ctx)
{
bool more_handlers = !completed_ops_.empty();

// Handlers queued here usually start the next I/O
// themselves, so running them first can save a reactor pass.
// Defer at most once in a row so reposting work cannot
// starve I/O. poll() and poll_one() don't defer: the reactor
// turn they would skip may be their last before returning.
if (task_deferred_)
{
task_deferred_ = false;
defer_policy_.on_deferred_turn(more_handlers);
}
else if (more_handlers && timeout_us != 0)
{
if (defer_policy_.may_defer())
{
task_deferred_ = true;
completed_ops_.push(&task_op_);
continue;
}
defer_policy_.on_polled_instead();
}

if (!more_handlers &&
outstanding_work_.load(std::memory_order_acquire) == 0)
{
Expand Down
19 changes: 8 additions & 11 deletions test/unit/fault/kqueue_faults.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -329,14 +329,12 @@ struct kqueue_faults

void testRunLoopFaults()
{
// Nothing calls kevent between the constructor and the run
// loop's first wait: posting the task does not interrupt a
// reactor that is not running yet
// (reactor_scheduler::wake_one_thread_and_unlock), so nth 1 is
// that wait.
// The run loop runs the posted task before its first wait, and
// arming the delay triggers the user event, so nth 1 is that
// trigger and nth 2 is the wait.
{
io_context ioc(kqueue);
fault_scope f(sys::kevent, EINTR);
fault_scope f(sys::kevent, EINTR, 2);
bool done = false;
auto body = [&]() -> capy::task<> {
std::ignore =
Expand All @@ -352,7 +350,7 @@ struct kqueue_faults
// Any other errno leaves run() through an exception
// (kqueue_scheduler::run_task).
io_context ioc(kqueue);
fault_scope f(sys::kevent, EBADF);
fault_scope f(sys::kevent, EBADF, 2);
auto body = [&]() -> capy::task<> {
std::ignore =
co_await corosio::delay(std::chrono::milliseconds(1));
Expand All @@ -377,10 +375,9 @@ struct kqueue_faults
{
io_context ioc(kqueue);
{
// stop() is the one path that reaches NOTE_TRIGGER without
// a reactor thread (reactor_scheduler::stop), and it
// interrupts only on the transition, so each stop below is
// one kevent.
// stop() reaches NOTE_TRIGGER with no other kevent call in
// between, and it interrupts only on the transition, so each
// stop below is one kevent.
fault_scope first(sys::kevent, EIO, 1);
fault_scope second(sys::kevent, EIO, 2);
ioc.stop();
Expand Down
73 changes: 73 additions & 0 deletions test/unit/fault/reactor_faults.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@
#include <boost/corosio/test/socket_pair.hpp>
#include <boost/corosio/udp_socket.hpp>
#include <boost/corosio/wait_type.hpp>
#include <boost/capy/ex/async_waker.hpp>
#include <boost/capy/ex/run_async.hpp>
#include <boost/capy/task.hpp>

Expand Down Expand Up @@ -84,6 +85,9 @@ struct reactor_common_faults
static constexpr sys spec_write = sys::write;
#endif
static constexpr sys vec_write = is_kqueue ? sys::writev : sys::sendmsg;
static constexpr sys wait_sys = is_select ? sys::select
: is_kqueue ? sys::kevent
: sys::epoll_wait;

static endpoint loopback()
{
Expand Down Expand Up @@ -1034,6 +1038,73 @@ struct reactor_common_faults
#endif
}

// A handler that an I/O completion posts runs before the reactor is
// polled again, since that handler may start the next I/O itself.
void testPostedWakeRunsBeforeNextPoll()
{
io_context ioc(Backend);
auto [a, b] = test::must(test::make_socket_pair(ioc));
capy::async_waker waker;
unsigned at_read = 0;
unsigned at_wake = 0;
// Counts this thread's calls to the wait symbol (every kevent on
// kqueue); the one it would fail is never reached.
fault_scope f(wait_sys, EINTR, 1u << 30);

auto waiter = [&]() -> capy::task<> {
auto [ec] = co_await waker.wait();
BOOST_TEST(!ec);
at_wake = f.count();
};
auto reader = [&]() -> capy::task<> {
char buf[1];
auto [ec, n] = co_await b.read_some(capy::mutable_buffer(buf, 1));
BOOST_TEST(!ec);
at_read = f.count();
waker.wake();
};
auto writer = [&]() -> capy::task<> {
char const c = 'x';
auto [ec, n] = co_await a.write_some(capy::const_buffer(&c, 1));
BOOST_TEST(!ec);
};
capy::run_async(ioc.get_executor())(waiter());
capy::run_async(ioc.get_executor())(reader());
capy::run_async(ioc.get_executor())(writer());
ioc.run();

// The read parked, so a poll completed it.
BOOST_TEST(at_read > 0);
BOOST_TEST_EQ(at_wake, at_read);
}

// A run stopped while the sentinel was deferred leaves the next run
// its own deferral, so a posted handler still runs before a poll.
void testRestartRenewsDeferral()
{
io_context ioc(Backend);
auto stopper = [&]() -> capy::task<> {
ioc.stop();
co_return;
};
capy::run_async(ioc.get_executor())(stopper());
ioc.run();
ioc.restart();

// Counts this thread's calls to the wait symbol (every kevent on
// kqueue); the one it would fail is never reached.
fault_scope f(wait_sys, EINTR, 1u << 30);
unsigned at_run = 1;
auto probe = [&]() -> capy::task<> {
at_run = f.count();
co_return;
};
capy::run_async(ioc.get_executor())(probe());
ioc.run();

BOOST_TEST_EQ(at_run, 0u);
}

// Accepted and assigned sockets learn their family from the
// addresses the library already reads, so option calls never ask.
void testAdoptedSocketsKnowFamily()
Expand Down Expand Up @@ -1352,6 +1423,8 @@ struct reactor_common_faults
testSocketFamilyProbeFails();
testOpenedSocketKnowsFamily();
testAdoptedSocketsKnowFamily();
testPostedWakeRunsBeforeNextPoll();
testRestartRenewsDeferral();
testDatagramFails();
}
};
Expand Down
Loading
Loading