Add io_context_options for runtime scheduler and service tuning

Introduce io_context_options with seven configurable knobs:
max_events_per_poll, inline_budget_initial/max, unassisted_budget,
gqcs_timeout_ms, thread_pool_size, and single_threaded.

The single_threaded option disables all scheduler and descriptor
mutex/condvar operations via conditionally_enabled_mutex/event
wrappers, following Asio's model. Cross-thread post is UB when
enabled; DNS and file I/O return operation_not_supported.
Benchmarks show 2x throughput on the single-threaded post path
with zero regression on multi-threaded paths.

Add lockless benchmark variants across all single-threaded suites:
io_context, socket_throughput, socket_latency, http_server, timer,
accept_churn, and fan_out. Add Asio lockless benchmarks for
comparison (concurrency_hint=1).

Author: mvandeberg

doc/modules/ROOT/nav.adoc

@@ -23,6 +23,7 @@
 ** xref:4.guide/4a.tcp-networking.adoc[TCP/IP Networking]
 ** xref:4.guide/4b.concurrent-programming.adoc[Concurrent Programming]
 ** xref:4.guide/4c.io-context.adoc[I/O Context]
+*** xref:4.guide/4c2.configuration.adoc[Configuration]
 ** xref:4.guide/4d.sockets.adoc[Sockets]
 ** xref:4.guide/4e.tcp-acceptor.adoc[Acceptors]
 ** xref:4.guide/4f.endpoints.adoc[Endpoints]

doc/modules/ROOT/pages/4.guide/4c2.configuration.adoc

@@ -0,0 +1,157 @@
+= Configuration
+:navtitle: Configuration
+
+The `io_context_options` struct provides runtime tuning knobs for the
+I/O context and its backend scheduler.  All defaults match the
+library's built-in values, so an unconfigured context behaves
+identically to previous releases.
+
+[source,cpp]
+----
+#include <boost/corosio/io_context.hpp>
+
+corosio::io_context_options opts;
+opts.max_events_per_poll = 256;
+opts.inline_budget_max   = 32;
+
+corosio::io_context ioc(opts);
+----
+
+Both `io_context` and `native_io_context` accept options:
+
+[source,cpp]
+----
+#include <boost/corosio/native/native_io_context.hpp>
+
+corosio::io_context_options opts;
+opts.max_events_per_poll = 512;
+
+corosio::native_io_context<corosio::epoll> ioc(opts);
+----
+
+== Available Options
+
+[cols="1,1,1,3"]
+|===
+| Option | Default | Backends | Description
+
+| `max_events_per_poll`
+| 128
+| epoll, kqueue
+| Number of events fetched per reactor poll call.  Larger values
+  reduce syscall frequency under high load; smaller values improve
+  fairness between connections.
+
+| `inline_budget_initial`
+| 2
+| epoll, kqueue, select
+| Starting inline completion budget per handler chain.  After a
+  posted handler executes, the reactor grants this many speculative
+  inline completions before forcing a re-queue.
+
+| `inline_budget_max`
+| 16
+| epoll, kqueue, select
+| Hard ceiling on adaptive inline budget ramp-up.  The budget
+  doubles each cycle it is fully consumed, up to this limit.
+
+| `unassisted_budget`
+| 4
+| epoll, kqueue, select
+| Inline budget when no other thread is running the event loop.
+  Prevents a single-threaded context from starving connections.
+
+| `gqcs_timeout_ms`
+| 500
+| IOCP
+| Maximum `GetQueuedCompletionStatus` blocking time in
+  milliseconds.  Lower values improve timer responsiveness at the
+  cost of more syscalls.
+
+| `thread_pool_size`
+| 1
+| POSIX (epoll, kqueue, select)
+| Number of worker threads in the shared thread pool used for
+  blocking file I/O and DNS resolution.  Ignored on IOCP where
+  file I/O uses native overlapped I/O.
+
+| `single_threaded`
+| false
+| all
+| Disable all scheduler mutex and condition variable operations.
+  Eliminates synchronization overhead when only one thread calls
+  `run()`.  See <<single-threaded-mode>> for restrictions.
+|===
+
+Options that do not apply to the active backend are silently ignored.
+
+== Tuning Guidelines
+
+=== Event Buffer Size (`max_events_per_poll`)
+
+The event buffer controls how many I/O events are fetched in a single
+`epoll_wait()` or `kevent()` call.
+
+* *High-throughput streaming* (few connections, high bandwidth):
+  increase to 256-512 to reduce syscall overhead.
+* *Many idle connections* (chat servers, WebSocket hubs):
+  keep at 128 or lower for better fairness.
+
+=== Inline Completion Budget
+
+The inline budget controls how many I/O completions the reactor
+completes speculatively within a single handler chain before forcing
+a re-queue through the scheduler.
+
+* *Streaming workloads* (file transfer, video):
+  `inline_budget_max = 32` or higher reduces context switches.
+* *Request-response workloads* (HTTP, RPC):
+  keep at 16 to prevent one connection from monopolizing a thread.
+* *Single-threaded contexts*:
+  `unassisted_budget` caps the budget when only one thread is
+  running the event loop, preserving fairness.
+
+=== IOCP Timeout (`gqcs_timeout_ms`)
+
+On Windows, the IOCP scheduler periodically wakes to recheck timers.
+The default 500ms balances responsiveness with efficiency.
+
+* *Sub-second timer precision*: reduce to 50-100ms.
+* *Minimal syscall overhead*: increase to 1000ms or higher.
+
+=== Thread Pool Size (`thread_pool_size`)
+
+On POSIX platforms, file I/O (`stream_file`, `random_access_file`)
+and DNS resolution use a shared thread pool.
+
+* *Concurrent file operations*: increase to match expected
+  parallelism (e.g. 4 for four concurrent file reads).
+* *No file I/O*: leave at 1 (the pool is created lazily).
+
+[#single-threaded-mode]
+=== Single-Threaded Mode (`single_threaded`)
+
+Disables all mutex and condition variable operations inside the
+scheduler and per-socket descriptor states.  This eliminates
+15-25% of overhead on the post-and-dispatch hot path.
+
+[source,cpp]
+----
+corosio::io_context_options opts;
+opts.single_threaded = true;
+
+corosio::io_context ioc(opts);
+ioc.run();  // only one thread may call this
+----
+
+WARNING: Single-threaded mode imposes hard restrictions.
+Violating them is undefined behavior.
+
+* Only **one thread** may call `run()` (or any run/poll variant).
+* **Posting work from another thread** is undefined behavior.
+* **DNS resolution** returns `operation_not_supported`.
+* **POSIX file I/O** (`stream_file`, `random_access_file`) returns
+  `operation_not_supported` on `open()`.
+* **Signal sets** should not be shared across contexts.
+* **Timer cancellation via `stop_token`** from another thread
+  remains safe (the timer service retains its own mutex).

include/boost/corosio/detail/conditionally_enabled_event.hpp

@@ -0,0 +1,77 @@
+//
+// Copyright (c) 2026 Michael Vandeberg
+//
+// 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_DETAIL_CONDITIONALLY_ENABLED_EVENT_HPP
+#define BOOST_COROSIO_DETAIL_CONDITIONALLY_ENABLED_EVENT_HPP
+
+#include <boost/corosio/detail/conditionally_enabled_mutex.hpp>
+
+#include <chrono>
+#include <condition_variable>
+
+namespace boost::corosio::detail {
+
+/* Condition variable wrapper that becomes a no-op when disabled.
+
+   When enabled, notify/wait delegate to an underlying
+   std::condition_variable. When disabled, all operations
+   are no-ops. The wait paths are unreachable in
+   single-threaded mode because the task sentinel prevents
+   the empty-queue state in do_one().
+*/
+class conditionally_enabled_event
+{
+    std::condition_variable cond_;
+    bool enabled_;
+
+public:
+    explicit conditionally_enabled_event(bool enabled = true) noexcept
+        : enabled_(enabled)
+    {
+    }
+
+    conditionally_enabled_event(conditionally_enabled_event const&)            = delete;
+    conditionally_enabled_event& operator=(conditionally_enabled_event const&) = delete;
+
+    void set_enabled(bool v) noexcept
+    {
+        enabled_ = v;
+    }
+
+    void notify_one()
+    {
+        if (enabled_)
+            cond_.notify_one();
+    }
+
+    void notify_all()
+    {
+        if (enabled_)
+            cond_.notify_all();
+    }
+
+    void wait(conditionally_enabled_mutex::scoped_lock& lock)
+    {
+        if (enabled_)
+            cond_.wait(lock.underlying());
+    }
+
+    template<class Rep, class Period>
+    void wait_for(
+        conditionally_enabled_mutex::scoped_lock& lock,
+        std::chrono::duration<Rep, Period> const& d)
+    {
+        if (enabled_)
+            cond_.wait_for(lock.underlying(), d);
+    }
+};
+
+} // namespace boost::corosio::detail
+
+#endif // BOOST_COROSIO_DETAIL_CONDITIONALLY_ENABLED_EVENT_HPP

include/boost/corosio/detail/conditionally_enabled_mutex.hpp

@@ -0,0 +1,101 @@
+//
+// Copyright (c) 2026 Michael Vandeberg
+//
+// 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_DETAIL_CONDITIONALLY_ENABLED_MUTEX_HPP
+#define BOOST_COROSIO_DETAIL_CONDITIONALLY_ENABLED_MUTEX_HPP
+
+#include <mutex>
+
+namespace boost::corosio::detail {
+
+/* Mutex wrapper that becomes a no-op when disabled.
+
+   When enabled (the default), lock/unlock delegate to an
+   underlying std::mutex. When disabled, all operations are
+   no-ops. The enabled flag is fixed after construction.
+
+   scoped_lock wraps std::unique_lock<std::mutex> internally
+   so that condvar wait paths (which require the real lock
+   type) compile and work in multi-threaded mode.
+*/
+class conditionally_enabled_mutex
+{
+    std::mutex mutex_;
+    bool enabled_;
+
+public:
+    explicit conditionally_enabled_mutex(bool enabled = true) noexcept
+        : enabled_(enabled)
+    {
+    }
+
+    conditionally_enabled_mutex(conditionally_enabled_mutex const&)            = delete;
+    conditionally_enabled_mutex& operator=(conditionally_enabled_mutex const&) = delete;
+
+    bool enabled() const noexcept
+    {
+        return enabled_;
+    }
+
+    void set_enabled(bool v) noexcept
+    {
+        enabled_ = v;
+    }
+
+    // Lockable interface — allows std::lock_guard<conditionally_enabled_mutex>
+    void lock() { if (enabled_) mutex_.lock(); }
+    void unlock() { if (enabled_) mutex_.unlock(); }
+    bool try_lock() { return !enabled_ || mutex_.try_lock(); }
+
+    class scoped_lock
+    {
+        std::unique_lock<std::mutex> lock_;
+        bool enabled_;
+
+    public:
+        explicit scoped_lock(conditionally_enabled_mutex& m)
+            : lock_(m.mutex_, std::defer_lock)
+            , enabled_(m.enabled_)
+        {
+            if (enabled_)
+                lock_.lock();
+        }
+
+        scoped_lock(scoped_lock const&)            = delete;
+        scoped_lock& operator=(scoped_lock const&) = delete;
+
+        void lock()
+        {
+            if (enabled_)
+                lock_.lock();
+        }
+
+        void unlock()
+        {
+            if (enabled_)
+                lock_.unlock();
+        }
+
+        bool owns_lock() const noexcept
+        {
+            return enabled_ && lock_.owns_lock();
+        }
+
+        // Access the underlying unique_lock for condvar wait().
+        // Only called when locking is enabled.
+        std::unique_lock<std::mutex>& underlying() noexcept
+        {
+            return lock_;
+        }
+    };
+};
+
+} // namespace boost::corosio::detail
+
+#endif // BOOST_COROSIO_DETAIL_CONDITIONALLY_ENABLED_MUTEX_HPP