Update docs for io_result-based when_all/when_any signatures by mvandeberg · Pull Request #248 · cppalliance/capy

mvandeberg · 2026-03-31T17:54:23Z

Closes #244

All documentation and Antora example pages still described the old API where when_all/when_any accepted plain task and returned tuples/variants without error_code. Update to match the current io_result-aware combinators:

when_all children must be io_task, result is io_result<R1,...,Rn>
when_any result is variant<error_code, R1,...,Rn> with error at index 0; only !ec wins
Replace monostate references with tuple<> for void tasks
Replace fictitious timeout_after examples with the real timeout combinator
Fix when_any docs that incorrectly described exceptions as valid completions

Summary by CodeRabbit

Documentation
- Clarified example documentation to explicitly describe both possible return values when using the concurrent operation range overload.
- Removed the timeout‑bounded demo that showed racing a task against a timeout; the remaining examples continue to demonstrate concurrent races.

coderabbitai · 2026-03-31T17:54:42Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: ab6b842a-d3da-4b14-83f8-92f978cec568

📥 Commits

Reviewing files that changed from the base of the PR and between ee042fe and 32ba620.

⛔ Files ignored due to path filters (9)

doc/modules/ROOT/pages/4.coroutines/4f.composition.adoc is excluded by !**/doc/**
doc/modules/ROOT/pages/7.examples/7b.producer-consumer.adoc is excluded by !**/doc/**
doc/modules/ROOT/pages/7.examples/7g.parallel-fetch.adoc is excluded by !**/doc/**
doc/modules/ROOT/pages/7.examples/7k.strand-serialization.adoc is excluded by !**/doc/**
doc/modules/ROOT/pages/7.examples/7l.async-mutex.adoc is excluded by !**/doc/**
doc/modules/ROOT/pages/7.examples/7m.parallel-tasks.adoc is excluded by !**/doc/**
doc/modules/ROOT/pages/7.examples/7n.custom-executor.adoc is excluded by !**/doc/**
doc/unlisted/coroutines-when-all.adoc is excluded by !**/doc/**
doc/unlisted/coroutines-when-any.adoc is excluded by !**/doc/**

📒 Files selected for processing (1)

example/when-any-cancellation/when_any_cancellation.cpp

💤 Files with no reviewable changes (1)

example/when-any-cancellation/when_any_cancellation.cpp

📝 Walkthrough

Walkthrough

Removed the timeout_a_worker() demo from example/when-any-cancellation/when_any_cancellation.cpp; the demo that raced a background_worker against a timeout was deleted and run_demos() no longer calls it, leaving race_data_sources() and race_vector_of_sources() as remaining demos.

Changes

Cohort / File(s)	Summary
Example removal `example/when-any-cancellation/when_any_cancellation.cpp`	Removed the local demo function `timeout_a_worker()` and its explanatory comment; removed the `co_await capy::when_any(background_worker(...), timeout(...))` example and its selection/printing logic. `run_demos()` no longer invokes the timeout-bounded worker demo.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

Add when_any examples to demonstrate cancellation of competing tasks #174: Removed the same timeout_a_worker() demo and its invocation from example/when-any-cancellation/when_any_cancellation.cpp.
Feature: when_any #101: Added the when_any implementation, documentation, and tests — related to the demo usage that was removed.

Poem

🐰 I hopped through examples, found one less race,
A timeout demo vanished without a trace.
Two demos remain, calm in their place,
I nibble a carrot and smile at the pace. 🥕

🚥 Pre-merge checks | ✅ 1 | ❌ 3

❌ Failed checks (3 warnings)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The PR title describes documentation updates for when_all/when_any signatures, but the actual changeset only removes a demo function timeout_a_worker() with no documentation changes present.	Verify if documentation files were actually modified. If the PR is meant for docs, include doc changes. If this is a demo-only change, retitle to reflect removal of timeout_a_worker() demo function.
Linked Issues check	⚠️ Warning	Issue `#244` requests documentation updates for when_all/when_any with io_result-based signatures and error propagation clarification, but the changeset contains no documentation or substantive example updates.	Add documentation updates and corrected examples showing io_task children, io_result returns, variant completion handling, and actual timeout combinator usage as specified in issue `#244`.
Out of Scope Changes check	⚠️ Warning	The removal of timeout_a_worker() demo function is out of scope relative to the PR's stated objective of updating documentation for io_result-based combinator signatures.	Either include the intended documentation changes that address issue `#244` requirements, or update PR title and description to reflect this is a demo function cleanup.

✅ 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

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

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

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@example/when-any-cancellation/when_any_cancellation.cpp`:
- Around line 118-119: The comment incorrectly calls the call-site a "range
overload" though this is the two-argument when_any(...) form; update the comment
(near the existing line referencing void tasks) to say that the two-argument
when_any(...) overload returns std::variant<std::error_code, std::size_t> (i.e.,
either the error code or the winner's index) rather than calling it a range
overload so the wording matches the use of when_any(...).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: db7a51db-d55b-4519-aa79-1c201b8a6636

📥 Commits

Reviewing files that changed from the base of the PR and between bf08032 and db92ccb.

⛔ Files ignored due to path filters (9)

doc/modules/ROOT/pages/4.coroutines/4f.composition.adoc is excluded by !**/doc/**
doc/modules/ROOT/pages/7.examples/7b.producer-consumer.adoc is excluded by !**/doc/**
doc/modules/ROOT/pages/7.examples/7g.parallel-fetch.adoc is excluded by !**/doc/**
doc/modules/ROOT/pages/7.examples/7k.strand-serialization.adoc is excluded by !**/doc/**
doc/modules/ROOT/pages/7.examples/7l.async-mutex.adoc is excluded by !**/doc/**
doc/modules/ROOT/pages/7.examples/7m.parallel-tasks.adoc is excluded by !**/doc/**
doc/modules/ROOT/pages/7.examples/7n.custom-executor.adoc is excluded by !**/doc/**
doc/unlisted/coroutines-when-all.adoc is excluded by !**/doc/**
doc/unlisted/coroutines-when-any.adoc is excluded by !**/doc/**

📒 Files selected for processing (1)

example/when-any-cancellation/when_any_cancellation.cpp

coderabbitai · 2026-03-31T17:56:56Z

example/when-any-cancellation/when_any_cancellation.cpp

+// With void tasks, the range overload returns std::variant< std::error_code, std::size_t > 
+// returning either the error code or the winner's index.


⚠️ Potential issue | 🟡 Minor

Correct overload wording in the comment for this call site.

This function uses the two-argument when_any(...) call form here, but the comment says “range overload,” which is misleading in-context.

✏️ Suggested wording update

-// With void tasks, the range overload returns std::variant< std::error_code, std::size_t > -// returning either the error code or the winner's index. +// For this void-task race, `when_any` yields a variant whose alternatives encode +// either an error code (index 0) or the winning completion alternative.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed. In `@example/when-any-cancellation/when_any_cancellation.cpp` around lines 118 - 119, The comment incorrectly calls the call-site a "range overload" though this is the two-argument when_any(...) form; update the comment (near the existing line referencing void tasks) to say that the two-argument when_any(...) overload returns std::variant<std::error_code, std::size_t> (i.e., either the error code or the winner's index) rather than calling it a range overload so the wording matches the use of when_any(...).

cppalliance-bot · 2026-03-31T17:57:09Z

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

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

2026-03-31 23:01:51 UTC

cppalliance-bot · 2026-03-31T18:12:13Z

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

Build time: 2026-03-31 23:16:18 UTC

codecov · 2026-03-31T19:09:05Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.50%. Comparing base (bf08032) to head (32ba620).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop     #248   +/-   ##
========================================
  Coverage    92.50%   92.50%           
========================================
  Files          170      170           
  Lines         9348     9348           
========================================
  Hits          8647     8647           
  Misses         701      701

Flag	Coverage Δ
linux	`92.46% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

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 bf08032...32ba620. Read the comment docs.

🚀 New features to boost your workflow:

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

…ance#244) All documentation and Antora example pages still described the old API where when_all/when_any accepted plain task<T> and returned tuples/variants without error_code. Update to match the current io_result-aware combinators: - when_all children must be io_task, result is io_result<R1,...,Rn> - when_any result is variant<error_code, R1,...,Rn> with error at index 0; only !ec wins - Replace monostate references with tuple<> for void tasks - Replace fictitious timeout_after examples with the real timeout combinator - Fix when_any docs that incorrectly described exceptions as valid completions

coderabbitai bot reviewed Mar 31, 2026

View reviewed changes

mvandeberg force-pushed the pr/244-update-docs branch from db92ccb to ee042fe Compare March 31, 2026 19:10

mvandeberg force-pushed the pr/244-update-docs branch from ee042fe to 32ba620 Compare March 31, 2026 22:55

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update docs for io_result-based when_all/when_any signatures#248

Update docs for io_result-based when_all/when_any signatures#248
mvandeberg wants to merge 1 commit intocppalliance:developfrom
mvandeberg:pr/244-update-docs

mvandeberg commented Mar 31, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Mar 31, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Poem

❌ Failed checks (3 warnings)

Uh oh!

coderabbitai bot left a comment

Uh oh!

coderabbitai bot Mar 31, 2026

Uh oh!

cppalliance-bot commented Mar 31, 2026 •

edited

Loading

Uh oh!

cppalliance-bot commented Mar 31, 2026 •

edited

Loading

Uh oh!

codecov bot commented Mar 31, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		// With void tasks, the range overload returns std::variant< std::error_code, std::size_t >
		// returning either the error code or the winner's index.

Conversation

mvandeberg commented Mar 31, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Poem

❌ Failed checks (3 warnings)

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai bot Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

cppalliance-bot commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cppalliance-bot commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mvandeberg commented Mar 31, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Mar 31, 2026 •

edited

Loading

cppalliance-bot commented Mar 31, 2026 •

edited

Loading

cppalliance-bot commented Mar 31, 2026 •

edited

Loading

codecov bot commented Mar 31, 2026 •

edited

Loading