Update documentation table of contents and tidy README

[vinniefalco]

Summary by CodeRabbit

• Refactor
  • Migrated internal coroutine handling to use standard C++ coroutine primitives instead of a custom wrapper, improving standards compliance and reducing library dependencies.
  • Consolidated executor and stop token context passing into a unified environment object, simplifying API surface for coroutine suspension points and improving code consistency across I/O operations and schedulers.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR refactors the corosio library to unify executor and cancellation token handling by replacing separate Ex/executor_ref and std::stop_token parameters with a single capy::io_env const& parameter throughout awaitable suspension points, and migrates from library-specific capy::coro to standard std::coroutine_handle<> across all backends.

Changes

Cohort / File(s)	Summary
Awaitable API Refactoring include/boost/corosio/io_stream.hpp, include/boost/corosio/resolver.hpp, include/boost/corosio/signal_set.hpp, include/boost/corosio/tcp_acceptor.hpp, include/boost/corosio/tcp_socket.hpp, include/boost/corosio/timer.hpp	Updated await_suspend signatures to accept capy::io_env const& instead of separate executor and stop_token parameters; implementations now extract executor and token from environment.
Server Promise and Awaitable Wiring include/boost/corosio/tcp_server.hpp, src/corosio/src/tcp_server.cpp	Refactored promise_type to store and propagate io_env throughout coroutine context; updated push_awaitable and pop_awaitable await_suspend signatures to use io_env; changed stop token retrieval from direct this_coro::stop_token to environment-sourced token.
Scheduler and Context APIs include/boost/corosio/basic_io_context.hpp, include/boost/corosio/detail/scheduler.hpp	Changed dispatch and post methods to use std::coroutine_handle<> instead of capy::coro; updated include from capy.hpp to <coroutine>.
Coroutine Handle Dispatch Utility src/corosio/src/detail/dispatch_coro.hpp	New helper function providing fast-path dispatch for coroutine handles; checks executor type to determine inline resume vs. scheduled dispatch.
EPoll Backend Implementation src/corosio/src/detail/epoll/op.hpp, src/corosio/src/detail/epoll/acceptors.cpp, src/corosio/src/detail/epoll/scheduler.cpp, src/corosio/src/detail/epoll/scheduler.hpp, src/corosio/src/detail/epoll/sockets.cpp	Replaced capy::coro with std::coroutine_handle<>; transitioned from direct resume to dispatch_coro(...).resume() mechanism; updated scheduler post signature.
IOCP Backend Implementation src/corosio/src/detail/iocp/overlapped_op.hpp, src/corosio/src/detail/iocp/resolver_service.cpp, src/corosio/src/detail/iocp/scheduler.cpp, src/corosio/src/detail/iocp/scheduler.hpp, src/corosio/src/detail/iocp/signals.cpp, src/corosio/src/detail/iocp/signals.hpp, src/corosio/src/detail/iocp/sockets.cpp, src/corosio/src/detail/iocp/sockets.hpp	Updated coroutine handle type from capy::coro to std::coroutine_handle<> across all operation structures; replaced resume_coro with dispatch_coro invocations; added cancellation flag updates and pending I/O checks; updated public function signatures for socket and acceptor operations.
kqueue Backend Implementation src/corosio/src/detail/kqueue/op.hpp, src/corosio/src/detail/kqueue/acceptors.cpp, src/corosio/src/detail/kqueue/scheduler.cpp, src/corosio/src/detail/kqueue/scheduler.hpp, src/corosio/src/detail/kqueue/sockets.cpp	Migrated from capy::coro to std::coroutine_handle<>; replaced resume_coro with dispatch_coro(...).resume() throughout; updated scheduler post signature and implementation.
POSIX Backend Implementation src/corosio/src/detail/posix/resolver_service.cpp, src/corosio/src/detail/posix/signals.cpp	Changed coroutine handle type from capy::coro to std::coroutine_handle<>; replaced resume_coro with dispatch_coro for operation completion paths.
Select Backend Implementation src/corosio/src/detail/select/op.hpp, src/corosio/src/detail/select/acceptors.cpp, src/corosio/src/detail/select/scheduler.cpp, src/corosio/src/detail/select/scheduler.hpp, src/corosio/src/detail/select/sockets.cpp	Updated coroutine handle type from capy::coro to std::coroutine_handle<>; replaced resume_coro with dispatch_coro mechanism; updated scheduler post signature across all implementations.
Resume Helper Refactoring src/corosio/src/detail/resume_coro.hpp	Updated resume_coro function signature to accept std::coroutine_handle<> instead of capy::coro; replaced include of boost/capy/coro.hpp with standard <coroutine>.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• Add kqueue backend #114: Implements kqueue backend with native Ex/capy::executor_ref and stop_token signatures that directly conflict with this PR's unified io_env approach.
• Implement single reactor scheduler for epoll backend #49: Modifies epoll backend operation and scheduler code affecting the same files (epoll_op, scheduler) updated in this PR.
• Epoll optimizations #106: Changes epoll internals (op.hpp, acceptors.cpp, scheduler.cpp) with overlapping coroutine handle and resume mechanism updates.

Poem

🐰 From many threads we weave one stream,
io_env carries the unified dream—
No more scattered Ex and token dance,
Just one environment at each glance!
Coroutines dispatch with steady grace,
Standard handles light the way with pace! 🎉

🚥 Pre-merge checks | ✅ 1 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The PR title claims documentation and README updates, but the changeset is a massive refactor replacing capy::coro with std::coroutine_handle<> and restructuring io_env handling across all files.	Update the title to accurately reflect the major refactoring, such as 'Refactor coroutine handling to use standard std::coroutine_handle and io_env' to represent the scope of changes.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cppalliance-bot]

An automated preview of the documentation is available at https://117.corosio.prtest3.cppalliance.org/index.html

If more commits are pushed to the pull request, the docs will rebuild at the same URL.

2026-02-11 05:03:34 UTC

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 80.35%. Comparing base (ad5dd27) to head (c7378c2).
⚠️ Report is 4 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #117      +/-   ##
===========================================
+ Coverage    80.12%   80.35%   +0.22%     
===========================================
  Files           65       65              
  Lines         5640     5639       -1     
===========================================
+ Hits          4519     4531      +12     
+ Misses        1121     1108      -13     

Files with missing lines	Coverage Δ
include/boost/corosio/basic_io_context.hpp	95.45% <100.00%> (ø)
include/boost/corosio/detail/scheduler.hpp	100.00% <ø> (ø)
include/boost/corosio/io_stream.hpp	100.00% <100.00%> (ø)
include/boost/corosio/resolver.hpp	97.40% <100.00%> (ø)
include/boost/corosio/signal_set.hpp	93.33% <100.00%> (ø)
include/boost/corosio/tcp_acceptor.hpp	94.59% <100.00%> (ø)
include/boost/corosio/tcp_server.hpp	80.43% <100.00%> (ø)
include/boost/corosio/tcp_socket.hpp	91.17% <100.00%> (ø)
include/boost/corosio/timer.hpp	94.11% <100.00%> (ø)
src/corosio/src/detail/dispatch_coro.hpp	100.00% <100.00%> (ø)
... and 13 more

... and 1 file with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update ef608fa...c7378c2. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[cppalliance-bot]

GCOVR code coverage report https://117.corosio.prtest3.cppalliance.org/gcovr/index.html
LCOV code coverage report https://117.corosio.prtest3.cppalliance.org/genhtml/index.html
Coverage Diff Report https://117.corosio.prtest3.cppalliance.org/diff-report/index.html

Build time: 2026-02-10 01:42:36 UTC

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/corosio/src/detail/resume_coro.hpp (1)

30-38: ⚠️ Potential issue | 🟡 Minor

Remove resume_coro.hpp — the function is now completely unused.

The migration from resume_coro to dispatch_coro is complete; dispatch_coro is now used in 28+ locations across all platform implementations (select, iocp, kqueue, epoll). No callers of resume_coro remain in the codebase. Since this is an internal detail (not exported in public headers), it is safe to delete the file entirely.

🧹 Nitpick comments (5)

src/corosio/src/detail/kqueue/acceptors.cpp (1)

46-46: Nit: block comment describes the old resume path.

Line 46 says "resumed via saved_ex.dispatch()" but the code now uses dispatch_coro(saved_ex, saved_h).resume(). Consider updating the comment to match the new mechanism.

src/corosio/src/detail/iocp/signals.hpp (1)

23-24: Pre-existing: duplicate #include <system_error>.

Lines 23 and 24 both include <system_error>. Not introduced by this PR, but worth cleaning up if you're in the area.

Proposed fix

 `#include` "src/detail/intrusive.hpp"
 `#include` <system_error>
-
-#include <system_error>

src/corosio/src/detail/posix/resolver_service.cpp (1)

498-503: work_finished() called before dispatch_coro — confirm ordering is intentional.

impl->svc_.work_finished() at line 501 decrements the scheduler's outstanding work count before the coroutine is resumed at line 502. If this was the last work item, it could trigger stop() on the scheduler. The resumed coroutine may then attempt to perform further I/O operations on a stopped scheduler.

This ordering was presumably the same before the migration (with resume_coro), so it's not a new issue. Just flagging for awareness since the kqueue/select op patterns call work_finished() via the work_guard/work_cleanup RAII in the scheduler's do_one() loop, not in the op itself.

include/boost/corosio/resolver.hpp (1)

230-233: await_ready checks a default-constructed token_ — always returns false.

token_ is only populated in await_suspend (line 246), but await_ready (line 232) is called before await_suspend. A default std::stop_token has no associated stop state, so stop_requested() always returns false, making await_ready a no-op. The same pattern exists in reverse_resolve_awaitable at line 272.

This is pre-existing behavior (not introduced by this PR), but it means the early-exit optimization for already-cancelled tokens never triggers.

src/corosio/src/detail/iocp/sockets.cpp (1)

404-414: Asymmetric error handling between do_read_io and do_write_io.

On synchronous failure, do_read_io invokes the handler inline (line 413: op.invoke_handler()), while do_write_io posts the operation to the scheduler queue (line 449: svc_.post(&op)). Both are called via symmetric-transfer initiators so the caller is already suspended in both cases, making inline completion equally safe for writes. The inconsistency is not a bug, but it makes the code harder to reason about—consider aligning the two paths.

Also applies to: 441-450