diff --git a/doc/STYLE_GUIDE.md b/doc/STYLE_GUIDE.md index 2c41342f9..cde856f90 100644 --- a/doc/STYLE_GUIDE.md +++ b/doc/STYLE_GUIDE.md @@ -216,6 +216,12 @@ 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 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. - **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/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/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/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 diff --git a/doc/modules/ROOT/pages/reference-overview.adoc b/doc/modules/ROOT/pages/reference-overview.adoc new file mode 100644 index 000000000..de8f0af9a --- /dev/null +++ b/doc/modules/ROOT/pages/reference-overview.adoc @@ -0,0 +1,276 @@ +// +// 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) +// +// 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 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[]. +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 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"] +|=== +| 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, 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]. + +[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 frame allocator, which is the recycling allocator unless replaced. +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]. + +[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 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[] 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]. + +[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, 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]. + +[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[] +|===