Add runtime io_context_options for scheduler and service tuning

Introduce io_context_options struct with six configurable knobs:
max_events_per_poll, inline_budget_initial/max, unassisted_budget,
gqcs_timeout_ms, and thread_pool_size. All defaults match existing
hardcoded values for zero behavior change on unconfigured contexts.

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,122 @@
+= 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.
+|===
+
+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).

include/boost/corosio/io_context.hpp

@@ -27,6 +27,79 @@
 
 namespace boost::corosio {
 
+/** Runtime tuning options for @ref io_context.
+
+    All fields have defaults that match the library's built-in
+    values, so constructing a default `io_context_options` produces
+    identical behavior to an unconfigured context.
+
+    Options that apply only to a specific backend family are
+    silently ignored when the active backend does not support them.
+
+    @par Example
+    @code
+    io_context_options opts;
+    opts.max_events_per_poll  = 256;   // larger batch per syscall
+    opts.inline_budget_max    = 32;    // more speculative completions
+    opts.thread_pool_size     = 4;     // more file-I/O workers
+
+    io_context ioc(opts);
+    @endcode
+
+    @see io_context, native_io_context
+*/
+struct io_context_options
+{
+    /** Maximum events fetched per reactor poll call.
+
+        Controls the buffer size passed to `epoll_wait()` or
+        `kevent()`. Larger values reduce syscall frequency under
+        high load; smaller values improve fairness between
+        connections. Ignored on IOCP and select backends.
+    */
+    unsigned max_events_per_poll = 128;
+
+    /** 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. Applies to reactor backends only.
+    */
+    unsigned inline_budget_initial = 2;
+
+    /** Hard ceiling on adaptive inline budget ramp-up.
+
+        The budget doubles each cycle it is fully consumed, up to
+        this limit. Applies to reactor backends only.
+    */
+    unsigned inline_budget_max = 16;
+
+    /** Inline budget when no other thread assists the reactor.
+
+        When only one thread is running the event loop, this
+        value caps the inline budget to preserve fairness.
+        Applies to reactor backends only.
+    */
+    unsigned unassisted_budget = 4;
+
+    /** Maximum `GetQueuedCompletionStatus` timeout in milliseconds.
+
+        Bounds how long the IOCP scheduler blocks between timer
+        rechecks. Lower values improve timer responsiveness at the
+        cost of more syscalls. Applies to IOCP only.
+    */
+    unsigned gqcs_timeout_ms = 500;
+
+    /** Thread pool size for blocking I/O (file I/O, DNS resolution).
+
+        Sets the number of worker threads in the shared thread pool
+        used by POSIX file services and DNS resolution. Must be at
+        least 1. Applies to POSIX backends only; ignored on IOCP
+        where file I/O uses native overlapped I/O.
+    */
+    unsigned thread_pool_size = 1;
+};
+
 namespace detail {
 struct timer_service_access;
 } // namespace detail
@@ -64,6 +137,12 @@ class BOOST_COROSIO_DECL io_context : public capy::execution_context
 {
     friend struct detail::timer_service_access;
 
+    /// Pre-create services that depend on options (before construct).
+    void apply_options_pre_(io_context_options const& opts);
+
+    /// Apply runtime tuning to the scheduler (after construct).
+    void apply_options_post_(io_context_options const& opts);
+
 protected:
     detail::scheduler* sched_;
 
@@ -81,6 +160,17 @@ class BOOST_COROSIO_DECL io_context : public capy::execution_context
     */
     explicit io_context(unsigned concurrency_hint);
 
+    /** Construct with runtime tuning options and platform backend.
+
+        @param opts Runtime options controlling scheduler and
+            service behavior.
+        @param concurrency_hint Hint for the number of threads
+            that will call `run()`.
+    */
+    explicit io_context(
+        io_context_options const& opts,
+        unsigned concurrency_hint = std::thread::hardware_concurrency());
+
     /** Construct with an explicit backend tag.
 
         @param backend The backend tag value selecting the I/O
@@ -100,6 +190,30 @@ class BOOST_COROSIO_DECL io_context : public capy::execution_context
         sched_ = &Backend::construct(*this, concurrency_hint);
     }
 
+    /** Construct with an explicit backend tag and runtime options.
+
+        @param backend The backend tag value selecting the I/O
+            multiplexer (e.g. `corosio::epoll`).
+        @param opts Runtime options controlling scheduler and
+            service behavior.
+        @param concurrency_hint Hint for the number of threads
+            that will call `run()`.
+    */
+    template<class Backend>
+        requires requires { Backend::construct; }
+    explicit io_context(
+        Backend backend,
+        io_context_options const& opts,
+        unsigned concurrency_hint = std::thread::hardware_concurrency())
+        : capy::execution_context(this)
+        , sched_(nullptr)
+    {
+        (void)backend;
+        apply_options_pre_(opts);
+        sched_ = &Backend::construct(*this, concurrency_hint);
+        apply_options_post_(opts);
+    }
+
     ~io_context();
 
     io_context(io_context const&)            = delete;

include/boost/corosio/native/detail/epoll/epoll_scheduler.hpp

@@ -33,6 +33,7 @@
 #include <chrono>
 #include <cstdint>
 #include <mutex>
+#include <vector>
 
 #include <errno.h>
 #include <sys/epoll.h>
@@ -86,6 +87,13 @@ class BOOST_COROSIO_DECL epoll_scheduler final : public reactor_scheduler_base
     /// Shut down the scheduler, draining pending operations.
     void shutdown() override;
 
+    /// Apply runtime configuration, resizing the event buffer.
+    void configure_reactor(
+        unsigned max_events,
+        unsigned budget_init,
+        unsigned budget_max,
+        unsigned unassisted) noexcept override;
+
     /** Return the epoll file descriptor.
 
         Used by socket services to register file descriptors
@@ -130,12 +138,17 @@ class BOOST_COROSIO_DECL epoll_scheduler final : public reactor_scheduler_base
 
     // Set when the earliest timer changes; flushed before epoll_wait
     mutable std::atomic<bool> timerfd_stale_{false};
+
+    // Event buffer sized from max_events_per_poll_ (set at construction,
+    // resized by configure_reactor via io_context_options).
+    std::vector<epoll_event> event_buffer_;
 };
 
 inline epoll_scheduler::epoll_scheduler(capy::execution_context& ctx, int)
     : epoll_fd_(-1)
     , event_fd_(-1)
     , timer_fd_(-1)
+    , event_buffer_(max_events_per_poll_)
 {
     epoll_fd_ = ::epoll_create1(EPOLL_CLOEXEC);
     if (epoll_fd_ < 0)
@@ -217,6 +230,18 @@ epoll_scheduler::shutdown()
         interrupt_reactor();
 }
 
+inline void
+epoll_scheduler::configure_reactor(
+    unsigned max_events,
+    unsigned budget_init,
+    unsigned budget_max,
+    unsigned unassisted) noexcept
+{
+    reactor_scheduler_base::configure_reactor(
+        max_events, budget_init, budget_max, unassisted);
+    event_buffer_.resize(max_events_per_poll_);
+}
+
 inline void
 epoll_scheduler::register_descriptor(int fd, descriptor_state* desc) const
 {
@@ -307,8 +332,9 @@ epoll_scheduler::run_task(std::unique_lock<std::mutex>& lock, context_type* ctx)
     if (timerfd_stale_.exchange(false, std::memory_order_acquire))
         update_timerfd();
 
-    epoll_event events[128];
-    int nfds = ::epoll_wait(epoll_fd_, events, 128, timeout_ms);
+    int nfds = ::epoll_wait(
+        epoll_fd_, event_buffer_.data(),
+        static_cast<int>(event_buffer_.size()), timeout_ms);
 
     if (nfds < 0 && errno != EINTR)
         detail::throw_system_error(make_err(errno), "epoll_wait");
@@ -318,7 +344,7 @@ epoll_scheduler::run_task(std::unique_lock<std::mutex>& lock, context_type* ctx)
 
     for (int i = 0; i < nfds; ++i)
     {
-        if (events[i].data.ptr == nullptr)
+        if (event_buffer_[i].data.ptr == nullptr)
         {
             std::uint64_t val;
             // NOLINTNEXTLINE(clang-analyzer-unix.BlockInCriticalSection)
@@ -327,7 +353,7 @@ epoll_scheduler::run_task(std::unique_lock<std::mutex>& lock, context_type* ctx)
             continue;
         }
 
-        if (events[i].data.ptr == &timer_fd_)
+        if (event_buffer_[i].data.ptr == &timer_fd_)
         {
             std::uint64_t expirations;
             // NOLINTNEXTLINE(clang-analyzer-unix.BlockInCriticalSection)
@@ -337,8 +363,9 @@ epoll_scheduler::run_task(std::unique_lock<std::mutex>& lock, context_type* ctx)
             continue;
         }
 
-        auto* desc = static_cast<descriptor_state*>(events[i].data.ptr);
-        desc->add_ready_events(events[i].events);
+        auto* desc =
+            static_cast<descriptor_state*>(event_buffer_[i].data.ptr);
+        desc->add_ready_events(event_buffer_[i].events);
 
         bool expected = false;
         if (desc->is_enqueued_.compare_exchange_strong(