Move post_resume from the public interface to test helpers

Author: mvandeberg

include/boost/capy/ex/io_env.hpp

@@ -20,32 +20,6 @@
 namespace boost {
 namespace capy {
 
-/** Callable that posts a continuation to an executor.
-
-    Use this as the callback type for `std::stop_callback` instead
-    of resuming a coroutine handle directly. Direct resumption runs
-    the coroutine inline on whatever thread calls `request_stop()`,
-    which bypasses the executor and corrupts the thread-local
-    frame allocator.
-
-    Prefer @ref io_env::post_resume and the @ref stop_resume_callback
-    alias to construct these—see examples there.
-
-    @see io_env::post_resume, stop_resume_callback
-*/
-struct resume_via_post
-{
-    executor_ref ex;
-    mutable continuation cont;
-
-    // post() must not throw; stop_callback requires a
-    // non-throwing invocable.
-    void operator()() const noexcept
-    {
-        ex.post(cont);
-    }
-};
-
 /** Execution environment for IoAwaitables.
 
     This struct bundles the execution context passed through
@@ -60,27 +34,11 @@ struct resume_via_post
     chain. Awaitables receive `io_env const*` in `await_suspend`
     and should store it directly, never copy the pointed-to object.
 
-    @par Stop Callback Contract
-
-    Awaitables that register a `std::stop_callback` **must not**
-    resume the coroutine handle directly. The callback fires
-    synchronously on the thread that calls `request_stop()`, which
-    may not be an executor-managed thread. Resuming inline poisons
-    that thread's TLS frame allocator with the pool's allocator,
-    causing use-after-free on the next coroutine allocation.
-
-    Use @ref io_env::post_resume and @ref stop_resume_callback:
-    @code
-    std::optional<stop_resume_callback> stop_cb_;
-    // In await_suspend:
-    stop_cb_.emplace(env->stop_token, env->post_resume(h));
-    @endcode
-
     @par Thread Safety
     The referenced executor and allocator must remain valid
     for the lifetime of any coroutine using this environment.
 
-    @see IoAwaitable, IoRunnable, resume_via_post
+    @see IoAwaitable, IoRunnable
 */
 struct io_env
 {
@@ -96,45 +54,8 @@ struct io_env
     */
     std::pmr::memory_resource* frame_allocator = nullptr;
 
-    /** Create a resume_via_post callable for this environment.
-
-        Convenience method for registering @ref stop_resume_callback
-        instances. Wraps the coroutine handle in a @ref continuation
-        and pairs it with this environment's executor. Equivalent to
-        `resume_via_post{executor, continuation{h}}`.
-
-        @par Example
-        @code
-        stop_cb_.emplace(env->stop_token, env->post_resume(h));
-        @endcode
-
-        @param h The coroutine handle to wrap in a continuation
-            and post on cancellation.
-
-        @return A @ref resume_via_post callable that holds a
-        non-owning @ref executor_ref and a @ref continuation.
-        The callable must not outlive the executor it references.
-
-        @see resume_via_post, stop_resume_callback
-    */
-    resume_via_post
-    post_resume(std::coroutine_handle<> h) const noexcept
-    {
-        return resume_via_post{executor, continuation{h}};
-    }
 };
 
-/** Type alias for a stop callback that posts through the executor.
-
-    Use this to declare the stop callback member in your awaitable:
-    @code
-    std::optional<stop_resume_callback> stop_cb_;
-    @endcode
-
-    @see resume_via_post, io_env::post_resume
-*/
-using stop_resume_callback = std::stop_callback<resume_via_post>;
-
 } // capy
 } // boost
 

test/unit/test_helpers.hpp

@@ -256,6 +256,31 @@ struct self_destroy_awaitable
 };
 
 
+// Callable that posts a continuation to an executor instead of
+// resuming a coroutine handle inline.  Use as the callback type
+// for std::stop_callback — direct resumption runs the coroutine
+// on whatever thread calls request_stop(), bypassing the executor.
+struct resume_via_post
+{
+    executor_ref ex;
+    mutable continuation cont;
+
+    void operator()() const noexcept
+    {
+        ex.post(cont);
+    }
+};
+
+using stop_resume_callback = std::stop_callback<resume_via_post>;
+
+inline resume_via_post
+post_resume(
+    io_env const& env,
+    std::coroutine_handle<> h) noexcept
+{
+    return resume_via_post{env.executor, continuation{h}};
+}
+
 // test awaitable that must be stopped in order to resume.
 // Uses resume_via_post to ensure the coroutine resumes on the
 // executor's thread, not on whatever thread calls request_stop().
@@ -293,7 +318,7 @@ struct stop_only_awaitable
         if (env->stop_token.stop_requested())
             return h;
         ::new(stop_cb_buf_) stop_resume_callback(
-            env->stop_token, env->post_resume(h));
+            env->stop_token, post_resume(*env, h));
         active_.store(true, std::memory_order_release);
         return std::noop_coroutine();
     }