Update documentation table of contents and tidy README

doc/scheduler.md

@@ -62,11 +62,10 @@ Corosio's `task<T>` returns `coroutine_handle` from `await_suspend`, enabling co
 
 ```cpp
 // task<T>::await_suspend - returns coroutine_handle
-coro await_suspend(coro cont, executor_ref caller_ex, std::stop_token token)
+std::coroutine_handle<> await_suspend(std::coroutine_handle<> cont, io_env const& env)
 {
-    h_.promise().set_continuation(cont, caller_ex);
-    h_.promise().set_executor(caller_ex);
-    h_.promise().set_stop_token(token);
+    h_.promise().set_continuation(cont, env.executor);
+    h_.promise().set_environment(env);
     return h_;  // compiler tail-calls this handle
 }
 ```
@@ -78,7 +77,7 @@ auto final_suspend() noexcept
 {
     struct awaiter
     {
-        coro await_suspend(coro) const noexcept
+        std::coroutine_handle<> await_suspend(std::coroutine_handle<>) const noexcept
         {
             return p_->complete();  // returns continuation
         }
@@ -121,10 +120,10 @@ auto transform_awaitable(Awaitable&& a)
 }
 ```
 
-The `await_suspend` signature accepts additional context parameters:
+The `await_suspend` signature accepts the execution environment:
 
 ```cpp
-coro await_suspend(coro cont, executor_ref caller_ex, std::stop_token token)
+std::coroutine_handle<> await_suspend(std::coroutine_handle<> cont, io_env const& env)
 ```
 
 This design allows third-party awaitable types to integrate with Corosio's I/O system by satisfying the `IoAwaitable` concept.

include/boost/corosio/basic_io_context.hpp

@@ -12,7 +12,7 @@
 
 #include <boost/corosio/detail/config.hpp>
 #include <boost/corosio/detail/scheduler.hpp>
-#include <boost/capy/coro.hpp>
+#include <coroutine>
 #include <boost/capy/ex/execution_context.hpp>
 
 #include <chrono>
@@ -341,29 +341,21 @@ class basic_io_context::executor_type
 
     /** Dispatch a coroutine handle.
 
-        If called from within `run()`, resumes the coroutine inline
-        by calling `h.resume()`. The call returns when the coroutine
-        suspends or completes. Otherwise posts the coroutine for
-        later execution.
-
-        After this function returns, the state of `h` is unspecified.
-        The coroutine may have completed, been destroyed, or suspended
-        at a different suspension point. Callers must not assume `h`
-        remains valid after calling `dispatch`.
-
-        @note Because this function may call `h.resume()` before
-        returning, it cannot be used to implement symmetric transfer
-        from `await_suspend`.
+        Returns a handle for symmetric transfer. If called from
+        within `run()`, returns `h`. Otherwise posts the coroutine
+        for later execution and returns `std::noop_coroutine()`.
 
         @param h The coroutine handle to dispatch.
+
+        @return A handle for symmetric transfer or `std::noop_coroutine()`.
     */
-    void
-    dispatch(capy::coro h) const
+    std::coroutine_handle<>
+    dispatch(std::coroutine_handle<> h) const
     {
         if (running_in_this_thread())
-            h.resume();
-        else
-            ctx_->sched_->post(h);
+            return h;
+        ctx_->sched_->post(h);
+        return std::noop_coroutine();
     }
 
     /** Post a coroutine for deferred execution.
@@ -374,7 +366,7 @@ class basic_io_context::executor_type
         @param h The coroutine handle to post.
     */
     void
-    post(capy::coro h) const
+    post(std::coroutine_handle<> h) const
     {
         ctx_->sched_->post(h);
     }

include/boost/corosio/detail/scheduler.hpp

@@ -11,7 +11,7 @@
 #define BOOST_COROSIO_DETAIL_SCHEDULER_HPP
 
 #include <boost/corosio/detail/config.hpp>
-#include <boost/capy/coro.hpp>
+#include <coroutine>
 
 #include <cstddef>
 
@@ -22,7 +22,7 @@ class scheduler_op;
 struct scheduler
 {
     virtual ~scheduler() = default;
-    virtual void post(capy::coro) const = 0;
+    virtual void post(std::coroutine_handle<>) const = 0;
     virtual void post(scheduler_op*) const = 0;
 
     /** Notify scheduler of pending work (for executor use).

include/boost/corosio/io_stream.hpp

@@ -15,6 +15,7 @@
 #include <boost/capy/io_result.hpp>
 #include <boost/corosio/io_buffer_param.hpp>
 #include <boost/capy/ex/executor_ref.hpp>
+#include <boost/capy/ex/io_env.hpp>
 #include <system_error>
 
 #include <coroutine>
@@ -228,11 +229,10 @@ class BOOST_COROSIO_DECL io_stream : public io_object
 
         auto await_suspend(
             std::coroutine_handle<> h,
-            capy::executor_ref ex,
-            std::stop_token token) -> std::coroutine_handle<>
+            capy::io_env const& env) -> std::coroutine_handle<>
         {
-            token_ = std::move(token);
-            return ios_.get().read_some(h, ex, buffers_, token_, &ec_, &bytes_transferred_);
+            token_ = env.stop_token;
+            return ios_.get().read_some(h, env.executor, buffers_, token_, &ec_, &bytes_transferred_);
         }
     };
 
@@ -268,11 +268,10 @@ class BOOST_COROSIO_DECL io_stream : public io_object
 
         auto await_suspend(
             std::coroutine_handle<> h,
-            capy::executor_ref ex,
-            std::stop_token token) -> std::coroutine_handle<>
+            capy::io_env const& env) -> std::coroutine_handle<>
         {
-            token_ = std::move(token);
-            return ios_.get().write_some(h, ex, buffers_, token_, &ec_, &bytes_transferred_);
+            token_ = env.stop_token;
+            return ios_.get().write_some(h, env.executor, buffers_, token_, &ec_, &bytes_transferred_);
         }
     };
 

include/boost/corosio/resolver.hpp

@@ -18,6 +18,7 @@
 #include <boost/corosio/resolver_results.hpp>
 #include <boost/capy/ex/executor_ref.hpp>
 #include <boost/capy/ex/execution_context.hpp>
+#include <boost/capy/ex/io_env.hpp>
 #include <boost/capy/concept/executor.hpp>
 
 #include <system_error>
@@ -238,22 +239,12 @@ class BOOST_COROSIO_DECL resolver : public io_object
             return {ec_, std::move(results_)};
         }
 
-        template<typename Ex>
         auto await_suspend(
             std::coroutine_handle<> h,
-            Ex const& ex) -> std::coroutine_handle<>
+            capy::io_env const& env) -> std::coroutine_handle<>
         {
-            return r_.get().resolve(h, ex, host_, service_, flags_, token_, &ec_, &results_);
-        }
-
-        template<typename Ex>
-        auto await_suspend(
-            std::coroutine_handle<> h,
-            Ex const& ex,
-            std::stop_token token) -> std::coroutine_handle<>
-        {
-            token_ = std::move(token);
-            return r_.get().resolve(h, ex, host_, service_, flags_, token_, &ec_, &results_);
+            token_ = env.stop_token;
+            return r_.get().resolve(h, env.executor, host_, service_, flags_, token_, &ec_, &results_);
         }
     };
 
@@ -288,22 +279,12 @@ class BOOST_COROSIO_DECL resolver : public io_object
             return {ec_, std::move(result_)};
         }
 
-        template<typename Ex>
-        auto await_suspend(
-            std::coroutine_handle<> h,
-            Ex const& ex) -> std::coroutine_handle<>
-        {
-            return r_.get().reverse_resolve(h, ex, ep_, flags_, token_, &ec_, &result_);
-        }
-
-        template<typename Ex>
         auto await_suspend(
             std::coroutine_handle<> h,
-            Ex const& ex,
-            std::stop_token token) -> std::coroutine_handle<>
+            capy::io_env const& env) -> std::coroutine_handle<>
         {
-            token_ = std::move(token);
-            return r_.get().reverse_resolve(h, ex, ep_, flags_, token_, &ec_, &result_);
+            token_ = env.stop_token;
+            return r_.get().reverse_resolve(h, env.executor, ep_, flags_, token_, &ec_, &result_);
         }
     };
 

include/boost/corosio/signal_set.hpp

@@ -17,6 +17,7 @@
 #include <boost/capy/error.hpp>
 #include <boost/capy/ex/executor_ref.hpp>
 #include <boost/capy/ex/execution_context.hpp>
+#include <boost/capy/ex/io_env.hpp>
 #include <boost/capy/concept/executor.hpp>
 #include <system_error>
 
@@ -188,14 +189,12 @@ class BOOST_COROSIO_DECL signal_set : public io_object
             return {ec_, signal_number_};
         }
 
-        template<typename Ex>
         auto await_suspend(
             std::coroutine_handle<> h,
-            Ex const& ex,
-            std::stop_token token) -> std::coroutine_handle<>
+            capy::io_env const& env) -> std::coroutine_handle<>
         {
-            token_ = std::move(token);
-            return s_.get().wait(h, ex, token_, &ec_, &signal_number_);
+            token_ = env.stop_token;
+            return s_.get().wait(h, env.executor, token_, &ec_, &signal_number_);
         }
     };
 

include/boost/corosio/tcp_acceptor.hpp

@@ -18,6 +18,7 @@
 #include <boost/corosio/tcp_socket.hpp>
 #include <boost/capy/ex/executor_ref.hpp>
 #include <boost/capy/ex/execution_context.hpp>
+#include <boost/capy/ex/io_env.hpp>
 #include <boost/capy/concept/executor.hpp>
 
 #include <system_error>
@@ -100,22 +101,12 @@ class BOOST_COROSIO_DECL tcp_acceptor : public io_object
             return {ec_};
         }
 
-        template<typename Ex>
         auto await_suspend(
             std::coroutine_handle<> h,
-            Ex const& ex) -> std::coroutine_handle<>
+            capy::io_env const& env) -> std::coroutine_handle<>
         {
-            return acc_.get().accept(h, ex, token_, &ec_, &peer_impl_);
-        }
-
-        template<typename Ex>
-        auto await_suspend(
-            std::coroutine_handle<> h,
-            Ex const& ex,
-            std::stop_token token) -> std::coroutine_handle<>
-        {
-            token_ = std::move(token);
-            return acc_.get().accept(h, ex, token_, &ec_, &peer_impl_);
+            token_ = env.stop_token;
+            return acc_.get().accept(h, env.executor, token_, &ec_, &peer_impl_);
         }
     };