From f4f821878b5da7ef0212d428d1d99120832fd334 Mon Sep 17 00:00:00 2001 From: TheLingeringWill Date: Tue, 10 Nov 2026 17:29:04 +0100 Subject: [PATCH 1/7] docs: add a reference overview that groups the API by purpose The generated index lists symbols by entity kind only. The new Reference page groups every public symbol into twelve sections, each linking its names through cpp: and the manual pages that teach them. The nav entry now opens this page, with one child per section and an "Index by Kind" child for the generated index. Refs #408. --- doc/modules/ROOT/nav.adoc | 15 +- .../ROOT/pages/reference-overview.adoc | 274 ++++++++++++++++++ 2 files changed, 288 insertions(+), 1 deletion(-) create mode 100644 doc/modules/ROOT/pages/reference-overview.adoc diff --git a/doc/modules/ROOT/nav.adoc b/doc/modules/ROOT/nav.adoc index 65a8a530a..718f18d51 100644 --- a/doc/modules/ROOT/nav.adoc +++ b/doc/modules/ROOT/nav.adoc @@ -59,7 +59,20 @@ ** xref:A.specification-methods/Ab.cancellation.adoc[Cancellation] ** xref:A.specification-methods/Ac.contingencies.adoc[Contingencies] * xref:glossary.adoc[Glossary] -* xref:reference:boost/capy.adoc[Reference] +* xref:reference-overview.adoc[Reference] +** xref:reference-overview.adoc#tasks-and-promise-types[Tasks and Promise Types] +** xref:reference-overview.adoc#results-and-errors[Results and Errors] +** xref:reference-overview.adoc#starting-and-composing-tasks[Starting and Composing Tasks] +** xref:reference-overview.adoc#executors-and-execution-contexts[Executors and Execution Contexts] +** xref:reference-overview.adoc#coroutine-environment[Coroutine Environment] +** xref:reference-overview.adoc#awaitable-protocol[The Awaitable Protocol] +** xref:reference-overview.adoc#synchronization[Synchronization] +** xref:reference-overview.adoc#frame-allocators[Frame Allocators] +** xref:reference-overview.adoc#chain-ownership-and-abandonment[Chain Ownership and Abandonment] +** xref:reference-overview.adoc#buffers[Buffers] +** xref:reference-overview.adoc#streams[Streams] +** xref:reference-overview.adoc#testing[Testing] +** xref:reference:boost/capy.adoc[Index by Kind] * xref:2.cpp20-coroutines/2.intro.adoc[Introduction To {cpp}20 Coroutines] ** xref:2.cpp20-coroutines/2a.foundations.adoc[Coroutine Foundations] ** xref:2.cpp20-coroutines/2b.syntax.adoc[{cpp}20 Syntax] diff --git a/doc/modules/ROOT/pages/reference-overview.adoc b/doc/modules/ROOT/pages/reference-overview.adoc new file mode 100644 index 000000000..6b1b739a7 --- /dev/null +++ b/doc/modules/ROOT/pages/reference-overview.adoc @@ -0,0 +1,274 @@ +// +// Copyright (c) 2026 TheLingeringWill +// +// Distributed under the Boost Software License, Version 1.0. (See accompanying +// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +// +// Official repository: https://github.com/cppalliance/capy +// + += Reference +:page-mode: reference + +This page groups the public Capy API by purpose. +Each name links to its generated reference page. +The xref:reference:boost/capy.adoc[index by kind] lists the same names by entity kind. + +All names are in namespace `boost::capy`. +Testing tools are in cpp:test[], and the coroutine accessors are in cpp:this_coro[]. +Operators are listed on the page of their type. + +[#tasks-and-promise-types] +== Tasks and Promise Types + +cpp:task[] is Capy's only task type, the return type for coroutines that perform I/O. +A task's body does not run until the task is awaited or started. +cpp:run_async[] and cpp:run[] start any type that satisfies cpp:ContextRunnable[]. +Authors of other task types build their promise type from the mixins in this section. +See xref:4.coroutines/4b.tasks.adoc[The task Type] and xref:4.coroutines/4e.context-awaitable.adoc[The ContextAwaitable Protocol]. + +[cols="1,4"] +|=== +| Kind | Names + +| Concepts +| cpp:ContextRunnable[] + +| Types +| cpp:task[], cpp:context_awaitable_promise_base[], cpp:frame_alloc_mixin[] +|=== + +[#results-and-errors] +== Results and Errors + +A cpp:results[] value bundles an error code with the values an operation produces. +Test an error code against the portable conditions in cpp:cond[], such as cpp:cond::canceled[cond::canceled]. +Capy's own codes are in cpp:error[]. +See xref:4.coroutines/4k.results.adoc[The results Type]. + +[cols="1,4"] +|=== +| Kind | Names + +| Type Aliases +| cpp:results[] + +| Enum Types +| cpp:error[], cpp:cond[] + +| Functions +| cpp:make_error_code[], cpp:make_error_condition[] +|=== + +[#starting-and-composing-tasks] +== Starting and Composing Tasks + +cpp:run_async[] starts a task from code that is not a coroutine. +Inside a coroutine, `co_await` cpp:run[] to execute a task on a chosen executor, or with its own stop token or frame allocator. +cpp:when_all[] and cpp:when_any[] concurrently run several awaitables that return cpp:results[]. +cpp:when_all[] waits for all of them, and cpp:when_any[] picks the first one that succeeds. +See xref:4.coroutines/4c.launching.adoc[Starting Coroutines] and xref:4.coroutines/4g.composition.adoc[Concurrent Composition]. + +[cols="1,4"] +|=== +| Kind | Names + +| Types +| cpp:run_async_wrapper[] + +| Functions +| cpp:run_async[], cpp:run[], cpp:when_all[], cpp:when_any[] +|=== + +[#executors-and-execution-contexts] +== Executors and Execution Contexts + +An executor dispatches or posts continuations to its execution context. +An execution context, such as cpp:thread_pool[], provides executors bound to its own resources. +cpp:strand[] serializes the coroutines dispatched through it. +Authors of custom executors queue cpp:continuation[] objects and resume them with cpp:safe_resume[]. +See xref:4.coroutines/4d.executors.adoc[Executors and Execution Contexts] and xref:8.examples/8n.custom-executor.adoc[Custom Executor]. + +[cols="1,4"] +|=== +| Kind | Names + +| Concepts +| cpp:Executor[], cpp:ExecutionContext[] + +| Types +| cpp:execution_context[], cpp:thread_pool[], cpp:strand[], cpp:executor_ref[], cpp:any_executor[], cpp:work_guard[], cpp:continuation[] + +| Functions +| cpp:get_system_context[], cpp:make_work_guard[] +|=== + +[#coroutine-environment] +== Coroutine Environment + +Each coroutine in a chain receives an cpp:await_context[] that carries its executor, stop token, and frame allocator. +Inside a task, `co_await` an object from cpp:this_coro[] to read one of them. +For example, `co_await` cpp:this_coro::stop_token[] fetches the running coroutine's stop token. +See xref:4.coroutines/4e.context-awaitable.adoc[The ContextAwaitable Protocol] and xref:4.coroutines/4f.cancellation.adoc[Stop Tokens and Cancellation]. + +[cols="1,4"] +|=== +| Kind | Names + +| Types +| cpp:await_context[], cpp:this_coro::environment_tag[], cpp:this_coro::executor_tag[], cpp:this_coro::stop_token_tag[], cpp:this_coro::frame_allocator_tag[] + +| Variables +| cpp:this_coro::environment[], cpp:this_coro::executor[], cpp:this_coro::stop_token[], cpp:this_coro::frame_allocator[] +|=== + +[#awaitable-protocol] +== The Awaitable Protocol + +Authors of awaitables, streams, and combinators use these names. +A cpp:ContextAwaitable[] receives the coroutine's environment when it suspends. +cpp:immediate[] and cpp:ready[] wrap a result that is already available. +See xref:4.coroutines/4e.context-awaitable.adoc[The ContextAwaitable Protocol]. + +[cols="1,4"] +|=== +| Kind | Names + +| Concepts +| cpp:ContextAwaitable[], cpp:ContextAwaitableRange[], cpp:AwaitSuspendResult[], cpp:awaitable_decomposes_to[], cpp:decomposes_to[] + +| Types +| cpp:immediate[] + +| Type Aliases +| cpp:awaitable_result_t[] + +| Functions +| cpp:ready[] +|=== + +[#synchronization] +== Synchronization + +These primitives suspend a task instead of blocking its thread. +cpp:async_mutex[] grants exclusive access, cpp:async_event[] resumes every waiter, and cpp:async_waker[] hands one wakeup to one waiter. +To serialize all work without a lock, use the cpp:strand[] from <>. +See xref:8.examples/8l.async-mutex.adoc[Async Mutex], xref:8.examples/8b.producer-consumer.adoc[Producer-Consumer], and xref:8.examples/8f.timeout-cancellation.adoc[Timeout with Cancellation]. + +[cols="1,4"] +|=== +| Kind | Names + +| Types +| cpp:async_mutex[], cpp:async_event[], cpp:async_waker[] +|=== + +[#frame-allocators] +== Frame Allocators + +A task's `operator new` takes its frame from the thread's current frame allocator. +cpp:run_async[] sets that allocator before it creates the task. +Without an explicit allocator, it uses the execution context's default, typically a recycling allocator. +Code that resumes a coroutine handle directly calls cpp:safe_resume[] to keep that allocator intact. +Promise types get allocator support from cpp:frame_alloc_mixin[], listed under <>. +See xref:4.coroutines/4h.allocators.adoc[Frame Allocators]. + +[cols="1,4"] +|=== +| Kind | Names + +| Types +| cpp:recycling_memory_resource[] + +| Functions +| cpp:get_recycling_memory_resource[], cpp:get_current_frame_allocator[], cpp:set_current_frame_allocator[], cpp:safe_resume[] +|=== + +[#chain-ownership-and-abandonment] +== Chain Ownership and Abandonment + +Each xref:glossary.adoc#segment[segment] of a coroutine chain has a cpp:chain_owner[]. +A holder that can never resume a suspended coroutine gives it up with cpp:abandon[]. +Execution contexts, strands, and primitives do this when they are destroyed. +See xref:4.coroutines/4j.lifetimes.adoc[Lifetime and Ownership]. + +[cols="1,4"] +|=== +| Kind | Names + +| Types +| cpp:chain_owner[] + +| Functions +| cpp:abandon[] +|=== + +[#buffers] +== Buffers + +A buffer refers to a contiguous region of memory. +A buffer sequence is one buffer or a range of them. +cpp:make_buffer[] makes a buffer from a region of memory, a string view, or a contiguous range. +The other functions measure a buffer sequence, copy it, return its first buffer, or iterate over its buffers or bytes. +Each archetype satisfies its sequence concept but has no default constructor. +See xref:5.buffers/5.intro.adoc[Buffer Sequences]. + +[cols="1,4"] +|=== +| Kind | Names + +| Concepts +| cpp:ConstBuffer[], cpp:MutableBuffer[], cpp:ConstBufferSequence[], cpp:MutableBufferSequence[] + +| Types +| cpp:const_buffer[], cpp:mutable_buffer[], cpp:buffers_iterator[], cpp:const_buffer_archetype[], cpp:mutable_buffer_archetype[] + +| Type Aliases +| cpp:buffer_type[] + +| Functions +| cpp:make_buffer[], cpp:buffer_size[], cpp:buffers_count[], cpp:buffers_empty[], cpp:buffer_copy[], cpp:buffers_front[], cpp:buffers_begin[], cpp:buffers_end[], cpp:buffer_sequence_begin[], cpp:buffer_sequence_end[] +|=== + +[#streams] +== Streams + +A stream reads into or writes from buffer sequences. +cpp:read[] fills the whole buffer sequence, and cpp:write[] writes all of it. +Each function in this section is awaited with `co_await`. +The type-erased wrappers accept any stream that satisfies the matching concept and hide its type. +See xref:6.streams/6.intro.adoc[Streams]. + +[cols="1,4"] +|=== +| Kind | Names + +| Concepts +| cpp:ReadStream[], cpp:WriteStream[], cpp:Stream[] + +| Types +| cpp:any_read_stream[], cpp:any_write_stream[], cpp:any_stream[] + +| Functions +| cpp:read[], cpp:read_at_least[], cpp:write[], cpp:write_at_least[] +|=== + +[#testing] +== Testing + +The tools in cpp:test[] drive tasks and streams without a real I/O backend. +cpp:test::run_blocking[] starts a task and waits on the calling thread until it completes. +cpp:test::fuse[] injects a failure at a different point on each pass. +cpp:set_current_thread_name[] is in `boost::capy`, but its header is ``. +See xref:7.testing/7.intro.adoc[Testing]. + +[cols="1,4"] +|=== +| Kind | Names + +| Types +| cpp:test::blocking_context[], cpp:test::blocking_executor[], cpp:test::fuse[], cpp:test::read_stream[], cpp:test::write_stream[], cpp:test::stream[], cpp:test::bufgrind[] + +| Functions +| cpp:test::run_blocking[], cpp:test::make_stream_pair[], cpp:test::buffer_to_string[], cpp:set_current_thread_name[] +|=== From 7ec4a9c9491d094aeff09ae1a23f65dbb2d3df38 Mon Sep 17 00:00:00 2001 From: TheLingeringWill Date: Tue, 10 Nov 2026 17:29:05 +0100 Subject: [PATCH 2/7] docs: link the reference overview from the glossary and style guide The glossary See Also lists both the grouped overview and the generated index. STYLE_GUIDE E3 records that the overview must list every indexed symbol once and be updated with API changes. Refs #408. --- doc/STYLE_GUIDE.md | 5 +++++ doc/modules/ROOT/pages/glossary.adoc | 3 ++- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/doc/STYLE_GUIDE.md b/doc/STYLE_GUIDE.md index 2c41342f9..885cb91af 100644 --- a/doc/STYLE_GUIDE.md +++ b/doc/STYLE_GUIDE.md @@ -216,6 +216,11 @@ it only in the sense the row names. **scheduler** is approved only in its P2300 `page-toc` attribute in `doc/antora.yml`, not by the theme. - **E3.** The reference is grouped by functionality where the generator allows; operators are documented with their types; asynchronous operations are distinguishable from synchronous. + MrDocs groups the generated index by entity kind only, so the hand-written page + `doc/modules/ROOT/pages/reference-overview.adoc` groups by purpose every symbol on the + generated `boost::capy`, `test`, and `this_coro` index pages, except namespaces and operators. Each such + symbol appears there once, as a `cpp:` link in one section's table. A change that adds, + removes, or renames such a symbol updates that page in the same pull request. - **E4.** The theme passes a contrast check in both light and dark mode. *(Review tier: the gated failures were all `color-contrast` on shared Antora theme nav chrome — an external UI bundle Capy cannot fix, the same rationale that demoted E2; scan runs non-blocking, verify by diff --git a/doc/modules/ROOT/pages/glossary.adoc b/doc/modules/ROOT/pages/glossary.adoc index ea029f9f1..f2a2d17ba 100644 --- a/doc/modules/ROOT/pages/glossary.adoc +++ b/doc/modules/ROOT/pages/glossary.adoc @@ -335,4 +335,5 @@ lifetime, so the execution context does not stop running. See cpp:work_guard[]. == See Also -* xref:reference:boost/capy.adoc[Reference]: API reference documentation +* xref:reference-overview.adoc[Reference]: the API grouped by purpose +* xref:reference:boost/capy.adoc[Index by Kind]: the generated index, grouped by entity kind From 1aef267310e131675c3daabdc330ad581a8f0b7b Mon Sep 17 00:00:00 2001 From: TheLingeringWill Date: Tue, 10 Nov 2026 17:32:17 +0100 Subject: [PATCH 3/7] docs: tighten the reference overview after review Say when strands abandon coroutines, that read and write stop on an error, which frame allocator run_async uses by default, and that the generated index also lists namespaces and operators. E3 now says each symbol is listed once in a table, since intros mention some again. Refs #408. --- doc/STYLE_GUIDE.md | 7 ++++--- doc/modules/ROOT/pages/reference-overview.adoc | 8 ++++---- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/doc/STYLE_GUIDE.md b/doc/STYLE_GUIDE.md index 885cb91af..7cd8749b2 100644 --- a/doc/STYLE_GUIDE.md +++ b/doc/STYLE_GUIDE.md @@ -218,9 +218,10 @@ it only in the sense the row names. **scheduler** is approved only in its P2300 documented with their types; asynchronous operations are distinguishable from synchronous. MrDocs groups the generated index by entity kind only, so the hand-written page `doc/modules/ROOT/pages/reference-overview.adoc` groups by purpose every symbol on the - generated `boost::capy`, `test`, and `this_coro` index pages, except namespaces and operators. Each such - symbol appears there once, as a `cpp:` link in one section's table. A change that adds, - removes, or renames such a symbol updates that page in the same pull request. + generated `boost::capy`, `test`, and `this_coro` index pages, except namespaces and + operators. Each such symbol is listed once, as a `cpp:` link in one section's table. A + change that adds, removes, or renames such a symbol updates that page in the same pull + request. - **E4.** The theme passes a contrast check in both light and dark mode. *(Review tier: the gated failures were all `color-contrast` on shared Antora theme nav chrome — an external UI bundle Capy cannot fix, the same rationale that demoted E2; scan runs non-blocking, verify by diff --git a/doc/modules/ROOT/pages/reference-overview.adoc b/doc/modules/ROOT/pages/reference-overview.adoc index 6b1b739a7..53454ef60 100644 --- a/doc/modules/ROOT/pages/reference-overview.adoc +++ b/doc/modules/ROOT/pages/reference-overview.adoc @@ -12,7 +12,7 @@ This page groups the public Capy API by purpose. Each name links to its generated reference page. -The xref:reference:boost/capy.adoc[index by kind] lists the same names by entity kind. +The xref:reference:boost/capy.adoc[index by kind] lists these names, plus namespaces and operators, by entity kind. All names are in namespace `boost::capy`. Testing tools are in cpp:test[], and the coroutine accessors are in cpp:this_coro[]. @@ -168,7 +168,7 @@ See xref:8.examples/8l.async-mutex.adoc[Async Mutex], xref:8.examples/8b.produce A task's `operator new` takes its frame from the thread's current frame allocator. cpp:run_async[] sets that allocator before it creates the task. -Without an explicit allocator, it uses the execution context's default, typically a recycling allocator. +Without an explicit allocator, it uses the execution context's frame allocator, which is the recycling allocator unless replaced. Code that resumes a coroutine handle directly calls cpp:safe_resume[] to keep that allocator intact. Promise types get allocator support from cpp:frame_alloc_mixin[], listed under <>. See xref:4.coroutines/4h.allocators.adoc[Frame Allocators]. @@ -189,7 +189,7 @@ See xref:4.coroutines/4h.allocators.adoc[Frame Allocators]. Each xref:glossary.adoc#segment[segment] of a coroutine chain has a cpp:chain_owner[]. A holder that can never resume a suspended coroutine gives it up with cpp:abandon[]. -Execution contexts, strands, and primitives do this when they are destroyed. +Execution contexts and primitives do this when they shut down, and strands do it when their execution context shuts down. See xref:4.coroutines/4j.lifetimes.adoc[Lifetime and Ownership]. [cols="1,4"] @@ -234,7 +234,7 @@ See xref:5.buffers/5.intro.adoc[Buffer Sequences]. == Streams A stream reads into or writes from buffer sequences. -cpp:read[] fills the whole buffer sequence, and cpp:write[] writes all of it. +cpp:read[] fills the whole buffer sequence, and cpp:write[] writes all of it, unless an error stops them first. Each function in this section is awaited with `co_await`. The type-erased wrappers accept any stream that satisfies the matching concept and hide its type. See xref:6.streams/6.intro.adoc[Streams]. From b2d35fa534b9631f053025c4db074b4250eeb5c7 Mon Sep 17 00:00:00 2001 From: TheLingeringWill Date: Tue, 10 Nov 2026 17:34:26 +0100 Subject: [PATCH 4/7] docs: correct what abandons coroutines on the reference overview Capy's primitives resume their waiters with a canceled error when destroyed; only execution contexts and strands abandon them. Also say what safe_resume restores, that it resumes a continuation's handle, and that this_coro::environment reads all three values. Refs #408. --- doc/STYLE_GUIDE.md | 4 ++-- doc/modules/ROOT/pages/reference-overview.adoc | 9 +++++---- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/doc/STYLE_GUIDE.md b/doc/STYLE_GUIDE.md index 7cd8749b2..cde856f90 100644 --- a/doc/STYLE_GUIDE.md +++ b/doc/STYLE_GUIDE.md @@ -217,8 +217,8 @@ it only in the sense the row names. **scheduler** is approved only in its P2300 - **E3.** The reference is grouped by functionality where the generator allows; operators are documented with their types; asynchronous operations are distinguishable from synchronous. MrDocs groups the generated index by entity kind only, so the hand-written page - `doc/modules/ROOT/pages/reference-overview.adoc` groups by purpose every symbol on the - generated `boost::capy`, `test`, and `this_coro` index pages, except namespaces and + `doc/modules/ROOT/pages/reference-overview.adoc` groups every symbol on the generated + `boost::capy`, `test`, and `this_coro` index pages by purpose, except namespaces and operators. Each such symbol is listed once, as a `cpp:` link in one section's table. A change that adds, removes, or renames such a symbol updates that page in the same pull request. diff --git a/doc/modules/ROOT/pages/reference-overview.adoc b/doc/modules/ROOT/pages/reference-overview.adoc index 53454ef60..19ac7b4f1 100644 --- a/doc/modules/ROOT/pages/reference-overview.adoc +++ b/doc/modules/ROOT/pages/reference-overview.adoc @@ -86,7 +86,7 @@ See xref:4.coroutines/4c.launching.adoc[Starting Coroutines] and xref:4.coroutin An executor dispatches or posts continuations to its execution context. An execution context, such as cpp:thread_pool[], provides executors bound to its own resources. cpp:strand[] serializes the coroutines dispatched through it. -Authors of custom executors queue cpp:continuation[] objects and resume them with cpp:safe_resume[]. +Authors of custom executors queue cpp:continuation[] objects and resume their handles with cpp:safe_resume[]. See xref:4.coroutines/4d.executors.adoc[Executors and Execution Contexts] and xref:8.examples/8n.custom-executor.adoc[Custom Executor]. [cols="1,4"] @@ -107,7 +107,7 @@ See xref:4.coroutines/4d.executors.adoc[Executors and Execution Contexts] and xr == Coroutine Environment Each coroutine in a chain receives an cpp:await_context[] that carries its executor, stop token, and frame allocator. -Inside a task, `co_await` an object from cpp:this_coro[] to read one of them. +Inside a task, `co_await` an object from cpp:this_coro[] to read one of them, or cpp:this_coro::environment[] to read all three. For example, `co_await` cpp:this_coro::stop_token[] fetches the running coroutine's stop token. See xref:4.coroutines/4e.context-awaitable.adoc[The ContextAwaitable Protocol] and xref:4.coroutines/4f.cancellation.adoc[Stop Tokens and Cancellation]. @@ -169,7 +169,7 @@ See xref:8.examples/8l.async-mutex.adoc[Async Mutex], xref:8.examples/8b.produce A task's `operator new` takes its frame from the thread's current frame allocator. cpp:run_async[] sets that allocator before it creates the task. Without an explicit allocator, it uses the execution context's frame allocator, which is the recycling allocator unless replaced. -Code that resumes a coroutine handle directly calls cpp:safe_resume[] to keep that allocator intact. +Code that resumes a coroutine handle directly calls cpp:safe_resume[], which restores the thread's frame allocator after the coroutine yields control. Promise types get allocator support from cpp:frame_alloc_mixin[], listed under <>. See xref:4.coroutines/4h.allocators.adoc[Frame Allocators]. @@ -189,7 +189,8 @@ See xref:4.coroutines/4h.allocators.adoc[Frame Allocators]. Each xref:glossary.adoc#segment[segment] of a coroutine chain has a cpp:chain_owner[]. A holder that can never resume a suspended coroutine gives it up with cpp:abandon[]. -Execution contexts and primitives do this when they shut down, and strands do it when their execution context shuts down. +Execution contexts do this when they shut down, and so do strands when their execution context shuts down. +A destroyed cpp:async_mutex[] or other primitive instead resumes its waiters with a canceled error. See xref:4.coroutines/4j.lifetimes.adoc[Lifetime and Ownership]. [cols="1,4"] From d20d8925a7b07878b11c7efc17e47eafc9e52fb7 Mon Sep 17 00:00:00 2001 From: TheLingeringWill Date: Tue, 10 Nov 2026 23:11:51 +0100 Subject: [PATCH 5/7] docs: fix Reference links and note upward abandonment The Methods of API Description intro now links the reference overview, and the buffer-inspection page names the generated index by its new nav label. The overview's chain ownership section now says that when_all, when_any, run and test::run_blocking abandon their caller when a coroutine they started is abandoned. --- doc/modules/ROOT/pages/7.testing/7e.buffer-inspection.adoc | 2 +- doc/modules/ROOT/pages/A.specification-methods/A.intro.adoc | 2 +- doc/modules/ROOT/pages/reference-overview.adoc | 1 + 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/modules/ROOT/pages/7.testing/7e.buffer-inspection.adoc b/doc/modules/ROOT/pages/7.testing/7e.buffer-inspection.adoc index e87c3a514..5dcc89374 100644 --- a/doc/modules/ROOT/pages/7.testing/7e.buffer-inspection.adoc +++ b/doc/modules/ROOT/pages/7.testing/7e.buffer-inspection.adoc @@ -110,4 +110,4 @@ cpp:test::read_stream[read_stream], applying both utilities together: include::example$snippets/7e_buffer_inspection.cpp[tag=parser_all_splits,indent=0] ---- -See xref:reference:boost/capy.adoc[Reference] for the full API browser. +See the xref:reference:boost/capy.adoc[Index by Kind] for the full API browser. diff --git a/doc/modules/ROOT/pages/A.specification-methods/A.intro.adoc b/doc/modules/ROOT/pages/A.specification-methods/A.intro.adoc index ccf3c8a82..bd914d664 100644 --- a/doc/modules/ROOT/pages/A.specification-methods/A.intro.adoc +++ b/doc/modules/ROOT/pages/A.specification-methods/A.intro.adoc @@ -11,7 +11,7 @@ :page-mode: explanation This section describes the conventions used to specify the API of this library in the -following xref:reference:boost/capy.adoc[Reference] section. +following xref:reference-overview.adoc[Reference] section. == What This Section Covers diff --git a/doc/modules/ROOT/pages/reference-overview.adoc b/doc/modules/ROOT/pages/reference-overview.adoc index 19ac7b4f1..850c3d853 100644 --- a/doc/modules/ROOT/pages/reference-overview.adoc +++ b/doc/modules/ROOT/pages/reference-overview.adoc @@ -190,6 +190,7 @@ See xref:4.coroutines/4h.allocators.adoc[Frame Allocators]. Each xref:glossary.adoc#segment[segment] of a coroutine chain has a cpp:chain_owner[]. A holder that can never resume a suspended coroutine gives it up with cpp:abandon[]. Execution contexts do this when they shut down, and so do strands when their execution context shuts down. +Abandonment also travels up a chain: when a coroutine started by cpp:when_all[], cpp:when_any[], cpp:run[] or cpp:test::run_blocking[] is abandoned, its caller is abandoned too. A destroyed cpp:async_mutex[] or other primitive instead resumes its waiters with a canceled error. See xref:4.coroutines/4j.lifetimes.adoc[Lifetime and Ownership]. From 2e5857d0e5983cf2843170b441e11f13e0db7bf6 Mon Sep 17 00:00:00 2001 From: TheLingeringWill Date: Tue, 10 Nov 2026 23:20:01 +0100 Subject: [PATCH 6/7] docs: use the author's name in the reference overview copyright --- doc/modules/ROOT/pages/reference-overview.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/modules/ROOT/pages/reference-overview.adoc b/doc/modules/ROOT/pages/reference-overview.adoc index 850c3d853..abbe27667 100644 --- a/doc/modules/ROOT/pages/reference-overview.adoc +++ b/doc/modules/ROOT/pages/reference-overview.adoc @@ -1,5 +1,5 @@ // -// Copyright (c) 2026 TheLingeringWill +// Copyright (c) 2026 Jonathan EL BAZ // // Distributed under the Boost Software License, Version 1.0. (See accompanying // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) From fc798fecd5ca7658c79c359cbf29a4d53b3218ee Mon Sep 17 00:00:00 2001 From: TheLingeringWill Date: Tue, 10 Nov 2026 23:29:06 +0100 Subject: [PATCH 7/7] docs: correct the environment and abandonment notes in the reference overview await_context also carries the segment owner, which this_coro reads only through environment. test::run_blocking does not abandon its caller; it throws error::canceled, so drop it from the upward-abandonment list. --- doc/modules/ROOT/pages/reference-overview.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/modules/ROOT/pages/reference-overview.adoc b/doc/modules/ROOT/pages/reference-overview.adoc index abbe27667..de8f0af9a 100644 --- a/doc/modules/ROOT/pages/reference-overview.adoc +++ b/doc/modules/ROOT/pages/reference-overview.adoc @@ -106,8 +106,8 @@ See xref:4.coroutines/4d.executors.adoc[Executors and Execution Contexts] and xr [#coroutine-environment] == Coroutine Environment -Each coroutine in a chain receives an cpp:await_context[] that carries its executor, stop token, and frame allocator. -Inside a task, `co_await` an object from cpp:this_coro[] to read one of them, or cpp:this_coro::environment[] to read all three. +Each coroutine in a chain receives an cpp:await_context[] that carries its executor, stop token, frame allocator, and segment owner. +Inside a task, `co_await` an object from cpp:this_coro[] to read the executor, stop token, or frame allocator, or cpp:this_coro::environment[] to read them all. For example, `co_await` cpp:this_coro::stop_token[] fetches the running coroutine's stop token. See xref:4.coroutines/4e.context-awaitable.adoc[The ContextAwaitable Protocol] and xref:4.coroutines/4f.cancellation.adoc[Stop Tokens and Cancellation]. @@ -190,7 +190,7 @@ See xref:4.coroutines/4h.allocators.adoc[Frame Allocators]. Each xref:glossary.adoc#segment[segment] of a coroutine chain has a cpp:chain_owner[]. A holder that can never resume a suspended coroutine gives it up with cpp:abandon[]. Execution contexts do this when they shut down, and so do strands when their execution context shuts down. -Abandonment also travels up a chain: when a coroutine started by cpp:when_all[], cpp:when_any[], cpp:run[] or cpp:test::run_blocking[] is abandoned, its caller is abandoned too. +Abandonment also travels up a chain: when a coroutine started by cpp:when_all[], cpp:when_any[] or cpp:run[] is abandoned, its caller is abandoned too. A destroyed cpp:async_mutex[] or other primitive instead resumes its waiters with a canceled error. See xref:4.coroutines/4j.lifetimes.adoc[Lifetime and Ownership].