Add timeout combinator, delay awaitable, and timer_service (#63)

Introduce a first-class timeout(awaitable, duration) function that
races an IoAwaitable against a deadline, built on when_any + delay.

Components:

- timer_service: execution_context::service with a background jthread
  managing a min-heap of deadlines. Lazy-created via use_service.
  cancel() blocks until any in-progress callback completes.

- delay: standalone IoAwaitable that suspends for a duration using
  timer_service. Follows the claimed_/stop_callback pattern from
  async_event for safe cancellation. Destructor cleans up both the
  stop callback and timer to prevent use-after-free if a coroutine
  is destroyed while suspended.

- timeout: coroutine wrapper that returns the task result on success,
  or produces error::timeout on deadline expiry. For io_result types,
  the error code is set directly; for other types, a system_error is
  thrown.

- error::timeout and cond::timeout added to error/condition enums.

Author: mvandeberg

include/boost/capy.hpp

@@ -25,8 +25,10 @@
 #include <boost/capy/task.hpp>
 
 // Algorithms
+#include <boost/capy/delay.hpp>
 #include <boost/capy/read.hpp>
 #include <boost/capy/read_until.hpp>
+#include <boost/capy/timeout.hpp>
 #include <boost/capy/when_all.hpp>
 #include <boost/capy/when_any.hpp>
 #include <boost/capy/write.hpp>

include/boost/capy/cond.hpp

@@ -69,7 +69,14 @@ enum class cond
         An `error_code` compares equal to `not_found` when a
         lookup operation failed to find the requested item.
     */
-    not_found = 4
+    not_found = 4,
+
+    /** Operation timed out condition.
+
+        An `error_code` compares equal to `timeout` when an
+        operation exceeded its allowed duration.
+    */
+    timeout = 5
 };
 
 } // capy

include/boost/capy/delay.hpp

@@ -0,0 +1,222 @@
+//
+// 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/capy
+//
+
+#ifndef BOOST_CAPY_DELAY_HPP
+#define BOOST_CAPY_DELAY_HPP
+
+#include <boost/capy/detail/config.hpp>
+#include <boost/capy/ex/executor_ref.hpp>
+#include <boost/capy/ex/io_env.hpp>
+#include <boost/capy/ex/detail/timer_service.hpp>
+
+#include <atomic>
+#include <chrono>
+#include <coroutine>
+#include <new>
+#include <stop_token>
+#include <utility>
+
+namespace boost {
+namespace capy {
+
+/** IoAwaitable returned by @ref delay.
+
+    Suspends the calling coroutine until the deadline elapses
+    or the environment's stop token is activated, whichever
+    comes first. Resumption is always posted through the
+    executor, never inline on the timer thread.
+
+    Not intended to be named directly; use the @ref delay
+    factory function instead.
+
+    @par Cancellation
+
+    If `stop_requested()` is true before suspension, the
+    coroutine resumes immediately without scheduling a timer.
+    If stop is requested while suspended, the stop callback
+    claims the resume and posts it through the executor; the
+    pending timer is cancelled on the next `await_resume` or
+    destructor call.
+
+    @par Thread Safety
+
+    A single `delay_awaitable` must not be awaited concurrently.
+    Multiple independent `delay()` calls on the same
+    execution_context are safe and share one timer thread.
+
+    @see delay, timeout
+*/
+class delay_awaitable
+{
+    std::chrono::nanoseconds dur_;
+
+    detail::timer_service* ts_ = nullptr;
+    detail::timer_service::timer_id tid_ = 0;
+
+    // Declared before stop_cb_buf_: the callback
+    // accesses these members, so they must still be
+    // alive if the stop_cb_ destructor blocks.
+    std::atomic<bool> claimed_{false};
+    bool canceled_ = false;
+    bool stop_cb_active_ = false;
+
+    struct cancel_fn
+    {
+        delay_awaitable* self_;
+        executor_ref ex_;
+        std::coroutine_handle<> h_;
+
+        void operator()() const noexcept
+        {
+            if(!self_->claimed_.exchange(
+                true, std::memory_order_acq_rel))
+            {
+                self_->canceled_ = true;
+                ex_.post(h_);
+            }
+        }
+    };
+
+    using stop_cb_t = std::stop_callback<cancel_fn>;
+
+    // Aligned storage for the stop callback.
+    // Declared last: its destructor may block while
+    // the callback accesses the members above.
+#ifdef _MSC_VER
+# pragma warning(push)
+# pragma warning(disable: 4324)
+#endif
+    alignas(stop_cb_t)
+        unsigned char stop_cb_buf_[sizeof(stop_cb_t)];
+#ifdef _MSC_VER
+# pragma warning(pop)
+#endif
+
+    stop_cb_t& stop_cb_() noexcept
+    {
+        return *reinterpret_cast<stop_cb_t*>(stop_cb_buf_);
+    }
+
+public:
+    explicit delay_awaitable(std::chrono::nanoseconds dur) noexcept
+        : dur_(dur)
+    {
+    }
+
+    /// @pre The stop callback must not be active
+    ///      (i.e. the object has not yet been awaited).
+    delay_awaitable(delay_awaitable&& o) noexcept
+        : dur_(o.dur_)
+        , ts_(o.ts_)
+        , tid_(o.tid_)
+        , claimed_(o.claimed_.load(std::memory_order_relaxed))
+        , canceled_(o.canceled_)
+        , stop_cb_active_(std::exchange(o.stop_cb_active_, false))
+    {
+    }
+
+    ~delay_awaitable()
+    {
+        if(stop_cb_active_)
+            stop_cb_().~stop_cb_t();
+        if(ts_)
+            ts_->cancel(tid_);
+    }
+
+    delay_awaitable(delay_awaitable const&) = delete;
+    delay_awaitable& operator=(delay_awaitable const&) = delete;
+    delay_awaitable& operator=(delay_awaitable&&) = delete;
+
+    bool await_ready() const noexcept
+    {
+        return dur_.count() <= 0;
+    }
+
+    std::coroutine_handle<>
+    await_suspend(
+        std::coroutine_handle<> h,
+        io_env const* env) noexcept
+    {
+        // Already stopped: resume immediately
+        if(env->stop_token.stop_requested())
+        {
+            canceled_ = true;
+            return h;
+        }
+
+        ts_ = &env->executor.context().use_service<detail::timer_service>();
+
+        // Schedule timer (won't fire inline since deadline is in the future)
+        tid_ = ts_->schedule_after(dur_,
+            [this, h, ex = env->executor]()
+            {
+                if(!claimed_.exchange(
+                    true, std::memory_order_acq_rel))
+                {
+                    ex.post(h);
+                }
+            });
+
+        // Register stop callback (may fire inline)
+        ::new(stop_cb_buf_) stop_cb_t(
+            env->stop_token,
+            cancel_fn{this, env->executor, h});
+        stop_cb_active_ = true;
+
+        return std::noop_coroutine();
+    }
+
+    void await_resume() noexcept
+    {
+        if(stop_cb_active_)
+        {
+            stop_cb_().~stop_cb_t();
+            stop_cb_active_ = false;
+        }
+        if(ts_)
+            ts_->cancel(tid_);
+    }
+};
+
+/** Suspend the current coroutine for a duration.
+
+    Returns an IoAwaitable that completes at or after the
+    specified duration, or earlier if the environment's stop
+    token is activated. Completion is always normal (void
+    return); no exception is thrown on cancellation.
+
+    Zero or negative durations complete synchronously without
+    scheduling a timer.
+
+    @par Example
+    @code
+    co_await delay(std::chrono::milliseconds(100));
+    @endcode
+
+    @param dur The duration to wait.
+
+    @return A @ref delay_awaitable whose `await_resume`
+        returns `void`.
+
+    @throws Nothing.
+
+    @see timeout, delay_awaitable
+*/
+template<typename Rep, typename Period>
+delay_awaitable
+delay(std::chrono::duration<Rep, Period> dur) noexcept
+{
+    return delay_awaitable{
+        std::chrono::duration_cast<std::chrono::nanoseconds>(dur)};
+}
+
+} // capy
+} // boost
+
+#endif

include/boost/capy/error.hpp

@@ -43,7 +43,10 @@ enum class error
     stream_truncated,
 
     /// Requested item was not found. Compare with `cond::not_found`.
-    not_found
+    not_found,
+
+    /// Operation timed out. Compare with `cond::timeout`.
+    timeout
 };
 
 } // capy

include/boost/capy/ex/detail/timer_service.hpp

@@ -0,0 +1,126 @@
+//
+// 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/capy
+//
+
+#ifndef BOOST_CAPY_EX_TIMER_SERVICE_HPP
+#define BOOST_CAPY_EX_TIMER_SERVICE_HPP
+
+#include <boost/capy/detail/config.hpp>
+#include <boost/capy/ex/execution_context.hpp>
+
+#include <chrono>
+#include <cstdint>
+#include <functional>
+#include <mutex>
+#include <condition_variable>
+#include <queue>
+#include <thread>
+#include <unordered_set>
+#include <vector>
+
+namespace boost {
+namespace capy {
+namespace detail {
+
+/* Shared timer thread for an execution_context.
+
+   One background std::jthread per execution_context. All timeouts
+   scheduled through this context share the same thread, which sleeps
+   on a condition variable until the next deadline.
+
+   The timer thread never touches coroutine frames or executors
+   directly — callbacks are responsible for posting work through
+   the appropriate executor.
+*/
+
+class BOOST_CAPY_DECL
+    timer_service
+    : public execution_context::service
+{
+public:
+    using timer_id = std::uint64_t;
+
+    explicit timer_service(execution_context& ctx);
+
+    /** Schedule a callback to fire after a duration.
+
+        The callback is invoked on the timer service's background
+        thread. It must not block for extended periods.
+
+        @return An id that can be passed to cancel().
+    */
+    template<typename Rep, typename Period>
+    timer_id schedule_after(
+        std::chrono::duration<Rep, Period> dur,
+        std::function<void()> cb)
+    {
+        auto deadline = std::chrono::steady_clock::now() + dur;
+        return schedule_at(deadline, std::move(cb));
+    }
+
+    /** Cancel a pending timer.
+
+        After this function returns, the callback is guaranteed
+        not to be running and will never be invoked. If the
+        callback is currently executing on the timer thread,
+        this call blocks until it completes.
+
+        Safe to call with any id, including ids that have
+        already fired, been cancelled, or were never issued.
+    */
+    void cancel(timer_id id);
+
+protected:
+    void shutdown() override;
+
+private:
+    struct entry
+    {
+        std::chrono::steady_clock::time_point deadline;
+        timer_id id;
+        std::function<void()> callback;
+
+        bool operator>(entry const& o) const noexcept
+        {
+            return deadline > o.deadline;
+        }
+    };
+
+    timer_id schedule_at(
+        std::chrono::steady_clock::time_point deadline,
+        std::function<void()> cb);
+
+    void run();
+
+// warning C4251: std types need to have dll-interface
+#ifdef _MSC_VER
+# pragma warning(push)
+# pragma warning(disable: 4251)
+#endif
+    std::mutex mutex_;
+    std::condition_variable cv_;
+    std::condition_variable cancel_cv_;
+    std::priority_queue<
+        entry,
+        std::vector<entry>,
+        std::greater<>> queue_;
+    std::unordered_set<timer_id> active_ids_;
+    timer_id next_id_ = 0;
+    timer_id executing_id_ = 0;
+    bool stopped_ = false;
+    std::jthread thread_;
+#ifdef _MSC_VER
+# pragma warning(pop)
+#endif
+};
+
+} // detail
+} // capy
+} // boost
+
+#endif