Add continuation_op to eliminate heap allocation on executor post

continuation_op wraps a capy::continuation inside a scheduler_op so
the scheduler can queue it in the same FIFO as I/O completions
without heap-allocating a post_handler. A magic tag allows
try_from_continuation() to distinguish tagged continuations from
bare ones (e.g. capy's run_async), falling back to the existing
heap path when needed.

All sites that previously stored capy::continuation now store
continuation_op, giving the zero-alloc path to timer completions,
signal delivery, and tcp_server worker management. The tcp_server
launcher and test helpers still use the heap path since their
continuations are stack-local

Author: mvandeberg

include/boost/corosio/detail/continuation_op.hpp

@@ -0,0 +1,114 @@
+//
+// 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_CONTINUATION_OP_HPP
+#define BOOST_COROSIO_DETAIL_CONTINUATION_OP_HPP
+
+#include <boost/corosio/detail/scheduler_op.hpp>
+#include <boost/capy/continuation.hpp>
+
+#include <atomic>
+#include <cstdint>
+#include <cstring>
+
+namespace boost::corosio::detail {
+
+/* Scheduler operation that resumes a capy::continuation.
+
+   Embeds a continuation alongside a scheduler_op so the
+   scheduler can queue it in the same FIFO as I/O completions
+   without a heap allocation. The continuation lives in the
+   caller's coroutine frame (awaitable or op struct); this
+   wrapper gives it a scheduler_op identity.
+
+   io_context::executor_type::post(continuation&) uses
+   try_from_continuation() to recover the enclosing
+   continuation_op via a magic tag. The tag is read through
+   memcpy (not through a continuation_op*) so that UBSan
+   does not flag the speculative pointer arithmetic when the
+   continuation is not actually inside a continuation_op.
+*/
+struct continuation_op final : scheduler_op
+{
+    static constexpr std::uint32_t magic_ = 0xC0710Au;
+
+    std::uint32_t tag_ = magic_;
+    capy::continuation cont;
+
+    continuation_op() noexcept : scheduler_op(&do_complete) {}
+
+    // Reactor backends (epoll, select, kqueue) dispatch through
+    // virtual operator()(). IOCP dispatches through func_ which
+    // routes to do_complete below.
+    void operator()() override
+    {
+        std::atomic_thread_fence(std::memory_order_acquire);
+        cont.h.resume();
+    }
+
+    void destroy() override
+    {
+        if (cont.h)
+            cont.h.destroy();
+    }
+
+private:
+    // IOCP completion entry point. owner == nullptr means destroy.
+    static void do_complete(
+        void* owner,
+        scheduler_op* base,
+        std::uint32_t,
+        std::uint32_t)
+    {
+        auto* self = static_cast<continuation_op*>(base);
+        if (!owner)
+        {
+            if (self->cont.h)
+                self->cont.h.destroy();
+            return;
+        }
+        std::atomic_thread_fence(std::memory_order_acquire);
+        self->cont.h.resume();
+    }
+
+public:
+
+    // Recover the enclosing continuation_op from its cont member.
+    // Returns nullptr if the continuation is not tagged (bare
+    // capy::continuation from capy internals like run_async).
+    static continuation_op* try_from_continuation(
+        capy::continuation& c) noexcept
+    {
+        // offsetof on non-standard-layout is conditionally-supported;
+        // suppress the warning — all targeted compilers handle this
+        // correctly and the self-relative arithmetic is move-safe.
+#if defined(__GNUC__) || defined(__clang__)
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Winvalid-offsetof"
+#endif
+        constexpr auto cont_off = offsetof(continuation_op, cont);
+        constexpr auto tag_off  = offsetof(continuation_op, tag_);
+#if defined(__GNUC__) || defined(__clang__)
+#pragma GCC diagnostic pop
+#endif
+        // Read the tag through memcpy from a char*, not through a
+        // continuation_op*. This avoids UBSan's vptr check when
+        // the continuation is not actually inside a continuation_op.
+        auto* base = reinterpret_cast<char*>(&c) - cont_off;
+        std::uint32_t tag;
+        std::memcpy(&tag, base + tag_off, sizeof(tag));
+        if (tag != magic_)
+            return nullptr;
+        return reinterpret_cast<continuation_op*>(base);
+    }
+};
+
+} // namespace boost::corosio::detail
+
+#endif

include/boost/corosio/io/io_timer.hpp

@@ -12,8 +12,8 @@
 #define BOOST_COROSIO_IO_IO_TIMER_HPP
 
 #include <boost/corosio/detail/config.hpp>
+#include <boost/corosio/detail/continuation_op.hpp>
 #include <boost/corosio/io/io_object.hpp>
-#include <boost/capy/continuation.hpp>
 #include <boost/capy/io_result.hpp>
 #include <boost/capy/error.hpp>
 #include <boost/capy/ex/executor_ref.hpp>
@@ -47,7 +47,7 @@ class BOOST_COROSIO_DECL io_timer : public io_object
         io_timer& t_;
         std::stop_token token_;
         mutable std::error_code ec_;
-        capy::continuation cont_;
+        detail::continuation_op cont_op_;
 
         explicit wait_awaitable(io_timer& t) noexcept : t_(t) {}
 
@@ -67,7 +67,7 @@ class BOOST_COROSIO_DECL io_timer : public io_object
             -> std::coroutine_handle<>
         {
             token_     = env->stop_token;
-            cont_.h    = h;
+            cont_op_.cont.h = h;
             auto& impl = t_.get();
             // Inline fast path: already expired and not in the heap
             if (impl.heap_index_ == implementation::npos &&
@@ -78,10 +78,10 @@ class BOOST_COROSIO_DECL io_timer : public io_object
                 token_ = {}; // match normal path so await_resume
                              // returns ec_, not a stale stop check
                 auto d = env->executor;
-                d.post(cont_);
+                d.post(cont_op_.cont);
                 return std::noop_coroutine();
             }
-            return impl.wait(h, env->executor, std::move(token_), &ec_, &cont_);
+            return impl.wait(h, env->executor, std::move(token_), &ec_, &cont_op_.cont);
         }
     };
 

include/boost/corosio/io_context.hpp

@@ -13,6 +13,7 @@
 #define BOOST_COROSIO_IO_CONTEXT_HPP
 
 #include <boost/corosio/detail/config.hpp>
+#include <boost/corosio/detail/continuation_op.hpp>
 #include <boost/corosio/detail/platform.hpp>
 #include <boost/corosio/detail/scheduler.hpp>
 #include <boost/capy/continuation.hpp>
@@ -379,31 +380,50 @@ class io_context::executor_type
     /** Dispatch a continuation.
 
         Returns a handle for symmetric transfer. If called from
-        within `run()`, returns `c.h`. Otherwise posts the coroutine
-        for later execution and returns `std::noop_coroutine()`.
+        within `run()`, returns `c.h`. Otherwise posts the
+        enclosing continuation_op as a scheduler_op for later
+        execution and returns `std::noop_coroutine()`.
 
-        @param c The continuation to dispatch.
+        @param c The continuation to dispatch. Must be the `cont`
+                 member of a `detail::continuation_op`.
 
         @return A handle for symmetric transfer or `std::noop_coroutine()`.
     */
     std::coroutine_handle<> dispatch(capy::continuation& c) const
     {
         if (running_in_this_thread())
             return c.h;
-        ctx_->sched_->post(c.h);
+        post(c);
         return std::noop_coroutine();
     }
 
     /** Post a continuation for deferred execution.
 
-        The coroutine will be resumed during a subsequent call to
-        `run()`.
-
-        @param c The continuation to post.
+        If the continuation is backed by a continuation_op
+        (tagged), posts it directly as a scheduler_op — zero
+        heap allocation. Otherwise falls back to the
+        heap-allocating post(coroutine_handle<>) path.
     */
     void post(capy::continuation& c) const
     {
-        ctx_->sched_->post(c.h);
+        auto* op = detail::continuation_op::try_from_continuation(c);
+        if (op)
+            ctx_->sched_->post(op);
+        else
+            ctx_->sched_->post(c.h);
+    }
+
+    /** Post a bare coroutine handle for deferred execution.
+
+        Heap-allocates a scheduler_op to wrap the handle. Prefer
+        posting through a continuation_op-backed continuation when
+        the continuation has suitable lifetime.
+
+        @param h The coroutine handle to post.
+    */
+    void post(std::coroutine_handle<> h) const
+    {
+        ctx_->sched_->post(h);
     }
 
     /** Compare two executors for equality.

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

@@ -177,8 +177,8 @@ epoll_tcp_acceptor::accept(
                 if (impl_out)
                     *impl_out = nullptr;
             }
-            op.cont.h = h;
-            return dispatch_coro(ex, op.cont);
+            op.cont_op.cont.h = h;
+            return dispatch_coro(ex, op.cont_op.cont);
         }
 
         op.accepted_fd  = accepted;

include/boost/corosio/native/detail/iocp/win_overlapped_op.hpp

@@ -62,7 +62,7 @@ struct overlapped_op
 
     long ready_ = 0;
     std::coroutine_handle<> h;
-    capy::continuation cont;
+    detail::continuation_op cont_op;
     capy::executor_ref ex;
     std::error_code* ec_out = nullptr;
     std::size_t* bytes_out  = nullptr;
@@ -145,8 +145,8 @@ struct overlapped_op
         if (bytes_out)
             *bytes_out = static_cast<std::size_t>(bytes_transferred);
 
-        cont.h = h;
-        dispatch_coro(ex, cont).resume();
+        cont_op.cont.h = h;
+        dispatch_coro(ex, cont_op.cont).resume();
     }
 
     /** Disarm cancellation and abandon the coroutine handle. */

include/boost/corosio/native/detail/iocp/win_resolver_service.hpp

@@ -270,8 +270,8 @@ resolve_op::do_complete(
 
     op->cancel_handle = nullptr;
 
-    op->cont.h = op->h;
-    dispatch_coro(op->ex, op->cont).resume();
+    op->cont_op.cont.h = op->h;
+    dispatch_coro(op->ex, op->cont_op.cont).resume();
 }
 
 // reverse_resolve_op
@@ -315,8 +315,8 @@ reverse_resolve_op::do_complete(
             op->ep, std::move(op->stored_host), std::move(op->stored_service));
     }
 
-    op->cont.h = op->h;
-    dispatch_coro(op->ex, op->cont).resume();
+    op->cont_op.cont.h = op->h;
+    dispatch_coro(op->ex, op->cont_op.cont).resume();
 }
 
 // win_resolver

include/boost/corosio/native/detail/iocp/win_signal.hpp

@@ -17,6 +17,7 @@
 
 #include <boost/corosio/detail/config.hpp>
 #include <boost/corosio/signal_set.hpp>
+#include <boost/corosio/detail/continuation_op.hpp>
 #include <boost/corosio/detail/intrusive.hpp>
 #include <boost/corosio/detail/scheduler_op.hpp>
 #include <boost/capy/continuation.hpp>
@@ -44,7 +45,7 @@ enum
 struct signal_op : scheduler_op
 {
     std::coroutine_handle<> h;
-    capy::continuation cont;
+    detail::continuation_op cont_op;
     capy::executor_ref d;
     std::error_code* ec_out  = nullptr;
     int* signal_out          = nullptr;

include/boost/corosio/native/detail/iocp/win_signals.hpp

@@ -304,8 +304,8 @@ signal_op::do_complete(
     auto* service = op->svc;
     op->svc       = nullptr;
 
-    op->cont.h = op->h;
-    dispatch_coro(op->d, op->cont).resume();
+    op->cont_op.cont.h = op->h;
+    dispatch_coro(op->d, op->cont_op.cont).resume();
 
     if (service)
         service->work_finished();
@@ -338,8 +338,8 @@ win_signal::wait(
             *ec = make_error_code(capy::error::canceled);
         if (signal_out)
             *signal_out = 0;
-        pending_op_.cont.h = h;
-        dispatch_coro(d, pending_op_.cont).resume();
+        pending_op_.cont_op.cont.h = h;
+        dispatch_coro(d, pending_op_.cont_op.cont).resume();
         // completion is always posted to scheduler queue, never inline.
         return std::noop_coroutine();
     }
@@ -612,8 +612,8 @@ win_signals::cancel_wait(win_signal& impl)
             *op->ec_out = make_error_code(capy::error::canceled);
         if (op->signal_out)
             *op->signal_out = 0;
-        op->cont.h = op->h;
-        dispatch_coro(op->d, op->cont).resume();
+        op->cont_op.cont.h = op->h;
+        dispatch_coro(op->d, op->cont_op.cont).resume();
         sched_.work_finished();
     }
 }

include/boost/corosio/native/detail/iocp/win_tcp_acceptor_service.hpp

@@ -238,11 +238,11 @@ accept_op::do_complete(
             *op->impl_out = nullptr;
     }
 
-    op->cont.h                         = op->h;
+    op->cont_op.cont.h                         = op->h;
     auto saved_ex                      = op->ex;
     auto prevent_premature_destruction = std::move(op->acceptor_ptr);
 
-    dispatch_coro(saved_ex, op->cont).resume();
+    dispatch_coro(saved_ex, op->cont_op.cont).resume();
 }
 
 // connect_op completion handler

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

@@ -208,8 +208,8 @@ kqueue_tcp_acceptor::accept(
                 if (impl_out)
                     *impl_out = nullptr;
             }
-            op.cont.h = h;
-            return dispatch_coro(ex, op.cont);
+            op.cont_op.cont.h = h;
+            return dispatch_coro(ex, op.cont_op.cont);
         }
 
         op.accepted_fd  = accepted;