Repository navigation
Conversation
Add 4l, one conceptual home for async_mutex, async_event and async_waker: choosing between them and a strand, the shared threading model, the cancellation and destruction rules, and allocation. The page shows existing tagged regions only. Link it from the glossary entries, the 4j destruction paragraph (split into shorter sentences), and the Next Steps of 8b, 8f and 8l.
Add 8r, which documents example/early-quitter as a user-written task type: when to use it instead of task, the signal-to-stop pattern, how a stop ends a run of quitters, results that race a stop, the boundary rule, cleanup after the completion handler, the self-checks and the known limitations. It keeps the still-valid rationale of the deleted doc/quitter.md. Link it from 4e and from a TIP in 4f, and say in 4f that when_any cancels the losers when the first task succeeds.
Add 8t, which walks through asio_callbacks.cpp and the uni_stream adapter built on async_initiate. Point 8p's note and See Also at 8t and at the 9n section that covers any_stream.cpp.
Add 4l, 8t and 8r to the nav, the chapter intros and the index. In 8.intro, state that example code is not Capy API, correct the claim that every example is self-contained, and add a table of the programs that have no page, with a nav entry. when-any-cancellation is listed as out of date. Rewrite example/README.md as an index of all 24 example directories. Also add the missing 4j entry to 4.intro.
- 4l: the lock error code covers every cancellation, the shutdown callout no longer relies on a declaration outside the include, and the allocation rule notes that posting a waiter may allocate. - 8r: place the asynchronous stop race before the gate runs, say that the shutdown output omits its latency line, and drop the note that went beyond the two ideas kept from doc/quitter.md. - 8.intro: link any_stream.cpp itself, and do not link the out-of-date when-any-cancellation directory. - 8p: link the 9n section on any_stream.cpp from See Also. - example/README.md: any-sender-size counts the allocations of both connect and start.
carries_stop has no cv-qualified forms, so a const result cannot carry the stop and is dropped like a reference result; it is not moved. Also: 4l no longer suggests waking a waker from a signal handler, 8r says to copy shutdown.cpp's order instead of calling main.cpp's order safe, 8t says capy_streams.hpp declares rather than defines, and the CUDA rows name the C++20 requirement.
The pool is declared before the strands and wakers, so its joining destructor runs after them and cannot be the reason. The reasons are that each run_async call keeps its own copy of its strand, sharing one reference-counted state, and that a claimed waiter never touches its waker again. Also: the gate is created when an awaited operation is first not ready, 8t says that b2 builds the asio examples unconditionally and that the two chains can interleave differently, and the any-sender-size row matches the README.
BOOST_CAPY_BUILD_CUDA_EXAMPLES adds all four cuda/ programs, and cuda/pipeline fails to configure without BOOST_CAPY_BUILD_NVEXEC_EXAMPLES, which needs BOOST_CAPY_BUILD_STDEXEC_EXAMPLES and C++23. Say so under the 8.intro table and in example/README.md. Also: 4l says unlock() skips waiters a stop already claimed and that the shutdown snippet's one-thread pool meets the threading rule; 8r draws the stop transfer from the gate straight to run_async and no longer says inner quitters may use any result type.
|
An automated preview of the documentation is available at https://483.capy.prtest3.cppalliance.org/index.html If more commits are pushed to the pull request, the docs will rebuild at the same URL. 2026-11-12 00:30:10 UTC |
|
GCOVR code coverage report https://483.capy.prtest3.cppalliance.org/gcovr/index.html Build time: 2026-11-12 00:42:03 UTC |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #483 +/- ##
===========================================
+ Coverage 98.45% 98.46% +0.01%
===========================================
Files 135 135
Lines 7250 7250
===========================================
+ Hits 7138 7139 +1
+ Misses 112 111 -1
Flags with carried forward coverage won't be shown. Click here to find out more. Continue to review full report in Codecov by Harness.
🚀 New features to boost your workflow:
|
TheLingeringWill
force-pushed
the
pr/document-toolkit-examples-quitter
branch
from
November 10, 2026 23:55
cf563c3 to
d355a4a
Compare
TheLingeringWill
marked this pull request as ready for review
November 11, 2026 00:20
sgerbino
approved these changes
Nov 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #409. Part of #416.
The Boost review asked why the quitter and the other toolkit pieces ship if the manual does not document them. #481 moved the quitter out of the library into
example/early-quitter. This PR documents it, and the rest ofexample/, in the manual. Every example program now has a page or a row in a table. The manual also states that example code is not part of Capy.New pages
4.coroutines/4l.synchronization.adoc): when to use a strand,async_mutex,async_event, orasync_waker. It covers how each one treats a stop, what destruction does to its waiters, and the threading model. It includes tagged regions that already exist in the examples and snippets, so it adds no snippet file.8.examples/8r.early-quitter.adoc): a walkthrough ofmain.cpp, withquitter.hppandshutdown.cppin collapsible blocks. It covers when to use the quitter instead oftask, the two cases of the stop rule, what each check inchecks.cppcovers, and the known limitations. It says the quitter is example code (feat!: move quitter out of the library into an example #481, quitter's place in the library #431), and thattaskis Capy's only task type.8.examples/8t.asio-callbacks.adoc):asio_callbacks.cppand itsuni_streamadapter, the opposite direction of 8p.Changes to existing pages
8.intro: a "Library Code and Example Code" section, entries for 8r and 8t, and an "Other Programs in the Repository" table for the examples without a page.example/README.md: rewritten as an index of every example directory, split between the programs the manual teaches and the others, with their build flags. Drops the stalestream-pipeline/entry.nav.adoc: the three new pages and the new table.when_anysentence now says losing tasks are cancelled when the first task succeeds, not when it completes, and links 8f.