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.

Author: mvandeberg

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

@@ -74,6 +74,13 @@ corosio::native_io_context<corosio::epoll> ioc(opts);
 | 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.
@@ -120,3 +127,31 @@ 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

include/boost/corosio/io_context.hpp

@@ -98,6 +98,22 @@ struct io_context_options
         where file I/O uses native overlapped I/O.
     */
     unsigned thread_pool_size = 1;
+
+    /** Enable single-threaded mode (disable scheduler locking).
+
+        When true, the scheduler skips all mutex lock/unlock and
+        condition variable operations on the hot path. This
+        eliminates synchronization overhead when only one thread
+        calls `run()`.
+
+        @par Restrictions
+        - Only one thread may call `run()` (or any run variant).
+        - Posting work from another thread is undefined behavior.
+        - DNS resolution returns `operation_not_supported`.
+        - POSIX file I/O returns `operation_not_supported`.
+        - Signal sets should not be shared across contexts.
+    */
+    bool single_threaded = false;
 };
 
 namespace detail {

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

@@ -125,7 +125,7 @@ class BOOST_COROSIO_DECL epoll_scheduler final : public reactor_scheduler_base
 
 private:
     void
-    run_task(std::unique_lock<std::mutex>& lock, context_type* ctx) override;
+    run_task(lock_type& lock, context_type* ctx) override;
     void interrupt_reactor() const override;
     void update_timerfd() const;
 
@@ -255,9 +255,10 @@ epoll_scheduler::register_descriptor(int fd, descriptor_state* desc) const
     desc->registered_events = ev.events;
     desc->fd                = fd;
     desc->scheduler_        = this;
+    desc->mutex.set_enabled(!single_threaded_);
     desc->ready_events_.store(0, std::memory_order_relaxed);
 
-    std::lock_guard lock(desc->mutex);
+    conditionally_enabled_mutex::scoped_lock lock(desc->mutex);
     desc->impl_ref_.reset();
     desc->read_ready  = false;
     desc->write_ready = false;
@@ -319,7 +320,7 @@ epoll_scheduler::update_timerfd() const
 }
 
 inline void
-epoll_scheduler::run_task(std::unique_lock<std::mutex>& lock, context_type* ctx)
+epoll_scheduler::run_task(lock_type& lock, context_type* ctx)
 {
     int timeout_ms = task_interrupted_ ? 0 : -1;
 

include/boost/corosio/native/detail/kqueue/kqueue_scheduler.hpp

@@ -147,7 +147,7 @@ class BOOST_COROSIO_DECL kqueue_scheduler final : public reactor_scheduler_base
 
 private:
     void
-    run_task(std::unique_lock<std::mutex>& lock, context_type* ctx) override;
+    run_task(lock_type& lock, context_type* ctx) override;
     void interrupt_reactor() const override;
     long calculate_timeout(long requested_timeout_us) const;
 
@@ -242,9 +242,10 @@ kqueue_scheduler::register_descriptor(int fd, descriptor_state* desc) const
     desc->registered_events = kqueue_event_read | kqueue_event_write;
     desc->fd                = fd;
     desc->scheduler_        = this;
+    desc->mutex.set_enabled(!single_threaded_);
     desc->ready_events_.store(0, std::memory_order_relaxed);
 
-    std::lock_guard lock(desc->mutex);
+    conditionally_enabled_mutex::scoped_lock lock(desc->mutex);
     desc->impl_ref_.reset();
     desc->read_ready  = false;
     desc->write_ready = false;
@@ -309,7 +310,7 @@ kqueue_scheduler::calculate_timeout(long requested_timeout_us) const
 
 inline void
 kqueue_scheduler::run_task(
-    std::unique_lock<std::mutex>& lock, context_type* ctx)
+    lock_type& lock, context_type* ctx)
 {
     long effective_timeout_us = task_interrupted_ ? 0 : calculate_timeout(-1);
 

include/boost/corosio/native/detail/posix/posix_random_access_file_service.hpp

@@ -15,6 +15,7 @@
 #if BOOST_COROSIO_POSIX
 
 #include <boost/corosio/native/detail/posix/posix_random_access_file.hpp>
+#include <boost/corosio/native/native_scheduler.hpp>
 #include <boost/corosio/detail/random_access_file_service.hpp>
 #include <boost/corosio/detail/thread_pool.hpp>
 
@@ -33,6 +34,8 @@ class BOOST_COROSIO_DECL posix_random_access_file_service final
         capy::execution_context& ctx, scheduler& sched)
         : sched_(&sched)
         , pool_(get_or_create_pool(ctx))
+        , single_threaded_(
+              static_cast<native_scheduler&>(sched).single_threaded_)
     {
     }
 
@@ -80,6 +83,8 @@ class BOOST_COROSIO_DECL posix_random_access_file_service final
         std::filesystem::path const& path,
         file_base::flags mode) override
     {
+        if (single_threaded_)
+            return std::make_error_code(std::errc::operation_not_supported);
         return static_cast<posix_random_access_file&>(impl).open_file(
             path, mode);
     }
@@ -134,6 +139,7 @@ class BOOST_COROSIO_DECL posix_random_access_file_service final
 
     scheduler* sched_;
     thread_pool& pool_;
+    bool single_threaded_;
     std::mutex mutex_;
     intrusive_list<posix_random_access_file> file_list_;
     std::unordered_map<