diff --git a/doc/modules/ROOT/pages/2.cpp20-coroutines/2b.syntax.adoc b/doc/modules/ROOT/pages/2.cpp20-coroutines/2b.syntax.adoc index e3db2312..a7113899 100644 --- a/doc/modules/ROOT/pages/2.cpp20-coroutines/2b.syntax.adoc +++ b/doc/modules/ROOT/pages/2.cpp20-coroutines/2b.syntax.adoc @@ -4,7 +4,7 @@ This section introduces the three {cpp}20 keywords that create coroutines and wa == Prerequisites -* Completed xref:2a.foundations.adoc[Part I: Foundations] +* Completed xref:2.cpp20-coroutines/2a.foundations.adoc[Part I: Foundations] * Understanding of why coroutines exist and what problem they solve == The Three Keywords @@ -85,7 +85,7 @@ SimpleCoroutine my_first_coroutine() } ---- -The `promise_type` nested structure provides the minimum scaffolding the compiler needs. You will learn what each method does in xref:2c.machinery.adoc[Part III: Coroutine Machinery]. +The `promise_type` nested structure provides the minimum scaffolding the compiler needs. You will learn what each method does in xref:2.cpp20-coroutines/2c.machinery.adoc[Part III: Coroutine Machinery]. For now, observe that the presence of `co_return` transforms what looks like a regular function into a coroutine. If you try to compile a function with coroutine keywords but without proper infrastructure, the compiler will produce errors. diff --git a/doc/modules/ROOT/pages/2.cpp20-coroutines/2c.machinery.adoc b/doc/modules/ROOT/pages/2.cpp20-coroutines/2c.machinery.adoc index 895c8e48..ef6ea596 100644 --- a/doc/modules/ROOT/pages/2.cpp20-coroutines/2c.machinery.adoc +++ b/doc/modules/ROOT/pages/2.cpp20-coroutines/2c.machinery.adoc @@ -4,7 +4,7 @@ This section explains the promise type and coroutine handle—the core machinery == Prerequisites -* Completed xref:2b.syntax.adoc[Part II: {cpp}20 Syntax] +* Completed xref:2.cpp20-coroutines/2b.syntax.adoc[Part II: {cpp}20 Syntax] * Understanding of the three coroutine keywords * Familiarity with awaitables and awaiters diff --git a/doc/modules/ROOT/pages/2.cpp20-coroutines/2d.advanced.adoc b/doc/modules/ROOT/pages/2.cpp20-coroutines/2d.advanced.adoc index cda76580..ccf07fb7 100644 --- a/doc/modules/ROOT/pages/2.cpp20-coroutines/2d.advanced.adoc +++ b/doc/modules/ROOT/pages/2.cpp20-coroutines/2d.advanced.adoc @@ -4,7 +4,7 @@ This section covers advanced coroutine topics: symmetric transfer for efficient == Prerequisites -* Completed xref:2c.machinery.adoc[Part III: Coroutine Machinery] +* Completed xref:2.cpp20-coroutines/2c.machinery.adoc[Part III: Coroutine Machinery] * Understanding of promise types, coroutine handles, and generators == Symmetric Transfer diff --git a/doc/modules/ROOT/pages/3.concurrency/3b.synchronization.adoc b/doc/modules/ROOT/pages/3.concurrency/3b.synchronization.adoc index 08e8c7bf..c51f5d9a 100644 --- a/doc/modules/ROOT/pages/3.concurrency/3b.synchronization.adoc +++ b/doc/modules/ROOT/pages/3.concurrency/3b.synchronization.adoc @@ -4,7 +4,7 @@ This section introduces the dangers of shared data access and the synchronizatio == Prerequisites -* Completed xref:3a.foundations.adoc[Part I: Foundations] +* Completed xref:3.concurrency/3a.foundations.adoc[Part I: Foundations] * Understanding of threads and their lifecycle == The Danger: Race Conditions diff --git a/doc/modules/ROOT/pages/3.concurrency/3c.advanced.adoc b/doc/modules/ROOT/pages/3.concurrency/3c.advanced.adoc index eff263e6..8e3ce605 100644 --- a/doc/modules/ROOT/pages/3.concurrency/3c.advanced.adoc +++ b/doc/modules/ROOT/pages/3.concurrency/3c.advanced.adoc @@ -4,7 +4,7 @@ This section covers advanced synchronization primitives: atomics for lock-free o == Prerequisites -* Completed xref:3b.synchronization.adoc[Part II: Synchronization] +* Completed xref:3.concurrency/3b.synchronization.adoc[Part II: Synchronization] * Understanding of mutexes, lock guards, and deadlocks == Atomics: Lock-Free Operations diff --git a/doc/modules/ROOT/pages/3.concurrency/3d.patterns.adoc b/doc/modules/ROOT/pages/3.concurrency/3d.patterns.adoc index 310909ec..d1f8ca2e 100644 --- a/doc/modules/ROOT/pages/3.concurrency/3d.patterns.adoc +++ b/doc/modules/ROOT/pages/3.concurrency/3d.patterns.adoc @@ -4,7 +4,7 @@ This section covers communication mechanisms for getting results from threads an == Prerequisites -* Completed xref:3c.advanced.adoc[Part III: Advanced Primitives] +* Completed xref:3.concurrency/3c.advanced.adoc[Part III: Advanced Primitives] * Understanding of atomics, condition variables, and shared locks == Futures and Promises: Getting Results Back diff --git a/doc/modules/ROOT/pages/4.coroutines/4b.launching.adoc b/doc/modules/ROOT/pages/4.coroutines/4b.launching.adoc index a28f57e5..6d535ddb 100644 --- a/doc/modules/ROOT/pages/4.coroutines/4b.launching.adoc +++ b/doc/modules/ROOT/pages/4.coroutines/4b.launching.adoc @@ -4,7 +4,7 @@ This section explains how to launch coroutines for execution. You will learn abo == Prerequisites -* Completed xref:4a.tasks.adoc[The task Type] +* Completed xref:4.coroutines/4a.tasks.adoc[The task Type] * Understanding of lazy task execution == The Execution Model @@ -35,7 +35,7 @@ int main() thread_pool pool; run_async(pool.get_executor())(compute()); // Task is now running on the thread pool - + // pool destructor waits for work to complete return 0; } @@ -115,10 +115,10 @@ Inside a coroutine, use `run` to execute a child task on a different executor: task compute_on_pool(thread_pool& pool) { // This task runs on whatever executor we're already on - + // But this child task runs on the pool's executor: int result = co_await run(pool.get_executor())(expensive_computation()); - + // After co_await, we're back on our original executor co_return result; } diff --git a/doc/modules/ROOT/pages/4.coroutines/4c.executors.adoc b/doc/modules/ROOT/pages/4.coroutines/4c.executors.adoc index 4ebabd4b..2361ae95 100644 --- a/doc/modules/ROOT/pages/4.coroutines/4c.executors.adoc +++ b/doc/modules/ROOT/pages/4.coroutines/4c.executors.adoc @@ -4,7 +4,7 @@ This section explains executors and execution contexts—the mechanisms that con == Prerequisites -* Completed xref:4b.launching.adoc[Launching Coroutines] +* Completed xref:4.coroutines/4b.launching.adoc[Launching Coroutines] * Understanding of `run_async` and `run` == The Executor Concept diff --git a/doc/modules/ROOT/pages/4.coroutines/4d.io-awaitable.adoc b/doc/modules/ROOT/pages/4.coroutines/4d.io-awaitable.adoc index 82814a04..a4532089 100644 --- a/doc/modules/ROOT/pages/4.coroutines/4d.io-awaitable.adoc +++ b/doc/modules/ROOT/pages/4.coroutines/4d.io-awaitable.adoc @@ -4,7 +4,7 @@ This section explains the IoAwaitable protocol—Capy's mechanism for propagatin == Prerequisites -* Completed xref:4c.executors.adoc[Executors and Execution Contexts] +* Completed xref:4.coroutines/4c.executors.adoc[Executors and Execution Contexts] * Understanding of standard awaiter protocol (`await_ready`, `await_suspend`, `await_resume`) == The Problem: Context Propagation diff --git a/doc/modules/ROOT/pages/4.coroutines/4e.cancellation.adoc b/doc/modules/ROOT/pages/4.coroutines/4e.cancellation.adoc index 82ee9040..7a695dd2 100644 --- a/doc/modules/ROOT/pages/4.coroutines/4e.cancellation.adoc +++ b/doc/modules/ROOT/pages/4.coroutines/4e.cancellation.adoc @@ -4,7 +4,7 @@ This section teaches cooperative cancellation from the ground up, explaining {cp == Prerequisites -* Completed xref:4d.io-awaitable.adoc[The IoAwaitable Protocol] +* Completed xref:4.coroutines/4d.io-awaitable.adoc[The IoAwaitable Protocol] * Understanding of how context propagates through coroutine chains == Part 1: The Problem @@ -371,7 +371,7 @@ public: === when_any Cancellation -`when_any` uses stop tokens internally to cancel "losing" tasks when the first task completes. This is covered in xref:4f.composition.adoc[Concurrent Composition]. +`when_any` uses stop tokens internally to cancel "losing" tasks when the first task completes. This is covered in xref:4.coroutines/4f.composition.adoc[Concurrent Composition]. == Reference diff --git a/doc/modules/ROOT/pages/4.coroutines/4f.composition.adoc b/doc/modules/ROOT/pages/4.coroutines/4f.composition.adoc index 0dd9bd95..23135588 100644 --- a/doc/modules/ROOT/pages/4.coroutines/4f.composition.adoc +++ b/doc/modules/ROOT/pages/4.coroutines/4f.composition.adoc @@ -4,7 +4,7 @@ This section explains how to run multiple tasks concurrently using `when_all` an == Prerequisites -* Completed xref:4e.cancellation.adoc[Stop Tokens and Cancellation] +* Completed xref:4.coroutines/4e.cancellation.adoc[Stop Tokens and Cancellation] * Understanding of stop token propagation == Overview diff --git a/doc/modules/ROOT/pages/4.coroutines/4g.allocators.adoc b/doc/modules/ROOT/pages/4.coroutines/4g.allocators.adoc index 64394fa2..a3e5fa10 100644 --- a/doc/modules/ROOT/pages/4.coroutines/4g.allocators.adoc +++ b/doc/modules/ROOT/pages/4.coroutines/4g.allocators.adoc @@ -4,7 +4,7 @@ This section explains how coroutine frames are allocated and how to customize al == Prerequisites -* Completed xref:4f.composition.adoc[Concurrent Composition] +* Completed xref:4.coroutines/4f.composition.adoc[Concurrent Composition] * Understanding of coroutine frame allocation from xref:../2.cpp20-coroutines/2d.advanced.adoc[{cpp}20 Coroutines Tutorial] == The Timing Constraint diff --git a/doc/modules/ROOT/pages/5.buffers/5a.overview.adoc b/doc/modules/ROOT/pages/5.buffers/5a.overview.adoc index d8e50f85..921de559 100644 --- a/doc/modules/ROOT/pages/5.buffers/5a.overview.adoc +++ b/doc/modules/ROOT/pages/5.buffers/5a.overview.adoc @@ -156,4 +156,4 @@ The concept-driven approach: * Provides a single signature that accepts anything buffer-like * Follows proven STL design principles -Continue to xref:5b.types.adoc[Buffer Types] to learn about `const_buffer` and `mutable_buffer`. +Continue to xref:5.buffers/5b.types.adoc[Buffer Types] to learn about `const_buffer` and `mutable_buffer`. diff --git a/doc/modules/ROOT/pages/5.buffers/5b.types.adoc b/doc/modules/ROOT/pages/5.buffers/5b.types.adoc index 1f181df6..dc759112 100644 --- a/doc/modules/ROOT/pages/5.buffers/5b.types.adoc +++ b/doc/modules/ROOT/pages/5.buffers/5b.types.adoc @@ -4,7 +4,7 @@ This section introduces Capy's fundamental buffer types: `const_buffer` and `mut == Prerequisites -* Completed xref:5a.overview.adoc[Why Concepts, Not Spans] +* Completed xref:5.buffers/5a.overview.adoc[Why Concepts, Not Spans] * Understanding of why concept-driven buffers enable composition == Why Not std::byte? @@ -197,4 +197,4 @@ auto e = end(multi); // Returns multi.end() | Buffer creation utilities |=== -You have now learned about `const_buffer` and `mutable_buffer`. Continue to xref:5c.sequences.adoc[Buffer Sequences] to understand how these types compose into sequences. +You have now learned about `const_buffer` and `mutable_buffer`. Continue to xref:5.buffers/5c.sequences.adoc[Buffer Sequences] to understand how these types compose into sequences. diff --git a/doc/modules/ROOT/pages/5.buffers/5c.sequences.adoc b/doc/modules/ROOT/pages/5.buffers/5c.sequences.adoc index bf44a3e5..9cec279f 100644 --- a/doc/modules/ROOT/pages/5.buffers/5c.sequences.adoc +++ b/doc/modules/ROOT/pages/5.buffers/5c.sequences.adoc @@ -4,7 +4,7 @@ This section explains buffer sequences—the concept that enables zero-allocatio == Prerequisites -* Completed xref:5b.types.adoc[Buffer Types] +* Completed xref:5.buffers/5b.types.adoc[Buffer Types] * Understanding of `const_buffer` and `mutable_buffer` == What Is a Buffer Sequence? @@ -172,4 +172,4 @@ If your custom buffer sequence only provides forward iteration, wrap it in a typ | Incremental consumption wrapper |=== -You have now learned how buffer sequences enable zero-allocation composition. Continue to xref:5d.system-io.adoc[System I/O Integration] to see how buffer sequences interface with operating system I/O. +You have now learned how buffer sequences enable zero-allocation composition. Continue to xref:5.buffers/5d.system-io.adoc[System I/O Integration] to see how buffer sequences interface with operating system I/O. diff --git a/doc/modules/ROOT/pages/5.buffers/5d.system-io.adoc b/doc/modules/ROOT/pages/5.buffers/5d.system-io.adoc index a46350b1..8be48d0e 100644 --- a/doc/modules/ROOT/pages/5.buffers/5d.system-io.adoc +++ b/doc/modules/ROOT/pages/5.buffers/5d.system-io.adoc @@ -4,7 +4,7 @@ This section explains how buffer sequences interface with operating system I/O o == Prerequisites -* Completed xref:5c.sequences.adoc[Buffer Sequences] +* Completed xref:5.buffers/5c.sequences.adoc[Buffer Sequences] * Understanding of buffer sequence concepts == The Virtual Boundary @@ -202,4 +202,4 @@ The buffer sequence concepts and translation utilities are in: OS-specific I/O is handled by Corosio, which builds on Capy's buffer model. -You have now learned how buffer sequences integrate with operating system I/O. Continue to xref:5e.algorithms.adoc[Buffer Algorithms] to learn about measuring and copying buffers. +You have now learned how buffer sequences integrate with operating system I/O. Continue to xref:5.buffers/5e.algorithms.adoc[Buffer Algorithms] to learn about measuring and copying buffers. diff --git a/doc/modules/ROOT/pages/5.buffers/5e.algorithms.adoc b/doc/modules/ROOT/pages/5.buffers/5e.algorithms.adoc index 13ef8e5a..f5c35611 100644 --- a/doc/modules/ROOT/pages/5.buffers/5e.algorithms.adoc +++ b/doc/modules/ROOT/pages/5.buffers/5e.algorithms.adoc @@ -4,7 +4,7 @@ This section covers algorithms for measuring and manipulating buffer sequences. == Prerequisites -* Completed xref:5c.sequences.adoc[Buffer Sequences] +* Completed xref:5.buffers/5c.sequences.adoc[Buffer Sequences] * Understanding of `ConstBufferSequence` and iteration == Measuring Buffers @@ -259,4 +259,4 @@ public: | Copy algorithm |=== -You have now learned how to measure and copy buffer sequences. Continue to xref:5f.dynamic.adoc[Dynamic Buffers] to learn about growable buffer storage. +You have now learned how to measure and copy buffer sequences. Continue to xref:5.buffers/5f.dynamic.adoc[Dynamic Buffers] to learn about growable buffer storage. diff --git a/doc/modules/ROOT/pages/5.buffers/5f.dynamic.adoc b/doc/modules/ROOT/pages/5.buffers/5f.dynamic.adoc index 9b111447..3c0f8ca7 100644 --- a/doc/modules/ROOT/pages/5.buffers/5f.dynamic.adoc +++ b/doc/modules/ROOT/pages/5.buffers/5f.dynamic.adoc @@ -4,7 +4,7 @@ This section introduces dynamic buffers—growable storage that adapts to data f == Prerequisites -* Completed xref:5e.algorithms.adoc[Buffer Algorithms] +* Completed xref:5.buffers/5e.algorithms.adoc[Buffer Algorithms] * Understanding of buffer sequences and copying == The Producer/Consumer Model diff --git a/doc/modules/ROOT/pages/6.streams/6a.overview.adoc b/doc/modules/ROOT/pages/6.streams/6a.overview.adoc index c573500d..fd14790d 100644 --- a/doc/modules/ROOT/pages/6.streams/6a.overview.adoc +++ b/doc/modules/ROOT/pages/6.streams/6a.overview.adoc @@ -196,4 +196,4 @@ echo(s3); Same code, different transports—compile once, link anywhere. -Continue to xref:6b.streams.adoc[Streams (Partial I/O)] to learn the `ReadStream` and `WriteStream` concepts in detail. +Continue to xref:6.streams/6b.streams.adoc[Streams (Partial I/O)] to learn the `ReadStream` and `WriteStream` concepts in detail. diff --git a/doc/modules/ROOT/pages/6.streams/6b.streams.adoc b/doc/modules/ROOT/pages/6.streams/6b.streams.adoc index 23c90b27..5e6bc2ae 100644 --- a/doc/modules/ROOT/pages/6.streams/6b.streams.adoc +++ b/doc/modules/ROOT/pages/6.streams/6b.streams.adoc @@ -4,7 +4,7 @@ This section explains the `ReadStream` and `WriteStream` concepts for partial I/ == Prerequisites -* Completed xref:6a.overview.adoc[Stream Concepts Overview] +* Completed xref:6.streams/6a.overview.adoc[Stream Concepts Overview] * Understanding of the six stream concept categories == ReadStream @@ -233,4 +233,4 @@ The implementation doesn't know the concrete stream type. It compiles once and w | Type-erased bidirectional stream wrapper |=== -You have now learned the stream concepts for partial I/O. Continue to xref:6c.sources-sinks.adoc[Sources and Sinks] to learn about complete I/O with EOF signaling. +You have now learned the stream concepts for partial I/O. Continue to xref:6.streams/6c.sources-sinks.adoc[Sources and Sinks] to learn about complete I/O with EOF signaling. diff --git a/doc/modules/ROOT/pages/6.streams/6c.sources-sinks.adoc b/doc/modules/ROOT/pages/6.streams/6c.sources-sinks.adoc index 8f8f4ac0..73b0627c 100644 --- a/doc/modules/ROOT/pages/6.streams/6c.sources-sinks.adoc +++ b/doc/modules/ROOT/pages/6.streams/6c.sources-sinks.adoc @@ -4,7 +4,7 @@ This section explains the `ReadSource` and `WriteSink` concepts for complete I/O == Prerequisites -* Completed xref:6b.streams.adoc[Streams (Partial I/O)] +* Completed xref:6.streams/6b.streams.adoc[Streams (Partial I/O)] * Understanding of partial I/O with `ReadStream` and `WriteStream` == ReadSource @@ -238,4 +238,4 @@ Same `send_body` function, different transfer encodings—the library handles th | Type-erased write sink wrapper |=== -You have now learned about sources and sinks for complete I/O. Continue to xref:6d.buffer-concepts.adoc[Buffer Sources and Sinks] to learn about the callee-owns-buffers pattern. +You have now learned about sources and sinks for complete I/O. Continue to xref:6.streams/6d.buffer-concepts.adoc[Buffer Sources and Sinks] to learn about the callee-owns-buffers pattern. diff --git a/doc/modules/ROOT/pages/6.streams/6d.buffer-concepts.adoc b/doc/modules/ROOT/pages/6.streams/6d.buffer-concepts.adoc index 90bae549..7941f736 100644 --- a/doc/modules/ROOT/pages/6.streams/6d.buffer-concepts.adoc +++ b/doc/modules/ROOT/pages/6.streams/6d.buffer-concepts.adoc @@ -4,7 +4,7 @@ This section explains the `BufferSource` and `BufferSink` concepts for zero-copy == Prerequisites -* Completed xref:6c.sources-sinks.adoc[Sources and Sinks] +* Completed xref:6.streams/6c.sources-sinks.adoc[Sources and Sinks] * Understanding of caller-owns-buffers patterns == Callee-Owns-Buffers Pattern @@ -263,4 +263,4 @@ task<> decompress_stream(any_buffer_source& compressed, any_write_sink& output) | Type-erased buffer sink wrapper |=== -You have now learned about buffer sources and sinks for zero-copy I/O. Continue to xref:6e.algorithms.adoc[Transfer Algorithms] to learn about composed read/write operations. +You have now learned about buffer sources and sinks for zero-copy I/O. Continue to xref:6.streams/6e.algorithms.adoc[Transfer Algorithms] to learn about composed read/write operations. diff --git a/doc/modules/ROOT/pages/6.streams/6e.algorithms.adoc b/doc/modules/ROOT/pages/6.streams/6e.algorithms.adoc index 270c683a..e8340e7e 100644 --- a/doc/modules/ROOT/pages/6.streams/6e.algorithms.adoc +++ b/doc/modules/ROOT/pages/6.streams/6e.algorithms.adoc @@ -4,7 +4,7 @@ This section explains the composed read/write operations and transfer algorithms == Prerequisites -* Completed xref:6d.buffer-concepts.adoc[Buffer Sources and Sinks] +* Completed xref:6.streams/6d.buffer-concepts.adoc[Buffer Sources and Sinks] * Understanding of all six stream concepts == Composed Read/Write @@ -250,4 +250,4 @@ else if (ec.failed()) | ReadSource/ReadStream → BufferSink transfer |=== -You have now learned about transfer algorithms. Continue to xref:6f.isolation.adoc[Physical Isolation] to learn how type erasure enables compilation firewalls. +You have now learned about transfer algorithms. Continue to xref:6.streams/6f.isolation.adoc[Physical Isolation] to learn how type erasure enables compilation firewalls. diff --git a/doc/modules/ROOT/pages/6.streams/6f.isolation.adoc b/doc/modules/ROOT/pages/6.streams/6f.isolation.adoc index a493c2c9..a519334b 100644 --- a/doc/modules/ROOT/pages/6.streams/6f.isolation.adoc +++ b/doc/modules/ROOT/pages/6.streams/6f.isolation.adoc @@ -4,7 +4,7 @@ This section explains how type-erased wrappers enable compilation firewalls and == Prerequisites -* Completed xref:6e.algorithms.adoc[Transfer Algorithms] +* Completed xref:6.streams/6e.algorithms.adoc[Transfer Algorithms] * Understanding of type-erased wrappers == The Compilation Firewall Pattern diff --git a/doc/modules/ROOT/pages/7.examples/7a.hello-task.adoc b/doc/modules/ROOT/pages/7.examples/7a.hello-task.adoc index 9aa68cac..22eaa170 100644 --- a/doc/modules/ROOT/pages/7.examples/7a.hello-task.adoc +++ b/doc/modules/ROOT/pages/7.examples/7a.hello-task.adoc @@ -100,4 +100,4 @@ Hello from Capy! == Next Steps -* xref:7b.producer-consumer.adoc[Producer-Consumer] — Multiple tasks communicating +* xref:7.examples/7b.producer-consumer.adoc[Producer-Consumer] — Multiple tasks communicating diff --git a/doc/modules/ROOT/pages/7.examples/7b.producer-consumer.adoc b/doc/modules/ROOT/pages/7.examples/7b.producer-consumer.adoc index 8c1fd0f9..697b0f9a 100644 --- a/doc/modules/ROOT/pages/7.examples/7b.producer-consumer.adoc +++ b/doc/modules/ROOT/pages/7.examples/7b.producer-consumer.adoc @@ -11,7 +11,7 @@ Two tasks communicating via an async event, with strand serialization. == Prerequisites -* Completed xref:7a.hello-task.adoc[Hello Task] +* Completed xref:7.examples/7a.hello-task.adoc[Hello Task] * Understanding of basic task creation and launching == Source Code @@ -171,4 +171,4 @@ Consumer: received value 42 == Next Steps -* xref:7c.buffer-composition.adoc[Buffer Composition] — Zero-allocation buffer composition +* xref:7.examples/7c.buffer-composition.adoc[Buffer Composition] — Zero-allocation buffer composition diff --git a/doc/modules/ROOT/pages/7.examples/7c.buffer-composition.adoc b/doc/modules/ROOT/pages/7.examples/7c.buffer-composition.adoc index 44fe509e..b8410c1c 100644 --- a/doc/modules/ROOT/pages/7.examples/7c.buffer-composition.adoc +++ b/doc/modules/ROOT/pages/7.examples/7c.buffer-composition.adoc @@ -10,7 +10,7 @@ Composing buffer sequences without allocation for scatter/gather I/O. == Prerequisites -* Completed xref:7b.producer-consumer.adoc[Producer-Consumer] +* Completed xref:7.examples/7b.producer-consumer.adoc[Producer-Consumer] * Understanding of buffer types from xref:../5.buffers/5b.types.adoc[Buffer Types] == Source Code @@ -228,4 +228,4 @@ Prepared 2 buffers with 128 bytes total capacity == Next Steps -* xref:7d.mock-stream-testing.adoc[Mock Stream Testing] — Unit testing with mock streams +* xref:7.examples/7d.mock-stream-testing.adoc[Mock Stream Testing] — Unit testing with mock streams diff --git a/doc/modules/ROOT/pages/7.examples/7d.mock-stream-testing.adoc b/doc/modules/ROOT/pages/7.examples/7d.mock-stream-testing.adoc index a5df2c05..287d14f7 100644 --- a/doc/modules/ROOT/pages/7.examples/7d.mock-stream-testing.adoc +++ b/doc/modules/ROOT/pages/7.examples/7d.mock-stream-testing.adoc @@ -10,7 +10,7 @@ Unit testing protocol code with mock streams and error injection. == Prerequisites -* Completed xref:7c.buffer-composition.adoc[Buffer Composition] +* Completed xref:7.examples/7c.buffer-composition.adoc[Buffer Composition] * Understanding of streams from xref:../6.streams/6b.streams.adoc[Streams] == Source Code @@ -258,4 +258,4 @@ All tests passed! == Next Steps -* xref:7e.type-erased-echo.adoc[Type-Erased Echo] — Compilation firewall pattern +* xref:7.examples/7e.type-erased-echo.adoc[Type-Erased Echo] — Compilation firewall pattern diff --git a/doc/modules/ROOT/pages/7.examples/7e.type-erased-echo.adoc b/doc/modules/ROOT/pages/7.examples/7e.type-erased-echo.adoc index 7ff5a573..afdd6857 100644 --- a/doc/modules/ROOT/pages/7.examples/7e.type-erased-echo.adoc +++ b/doc/modules/ROOT/pages/7.examples/7e.type-erased-echo.adoc @@ -10,7 +10,7 @@ Echo server demonstrating the compilation firewall pattern. == Prerequisites -* Completed xref:7d.mock-stream-testing.adoc[Mock Stream Testing] +* Completed xref:7.examples/7d.mock-stream-testing.adoc[Mock Stream Testing] * Understanding of type erasure from xref:../6.streams/6f.isolation.adoc[Physical Isolation] == Source Code @@ -192,4 +192,4 @@ Echo output: Hello, World! == Next Steps -* xref:7f.timeout-cancellation.adoc[Timeout with Cancellation] — Stop tokens for timeout +* xref:7.examples/7f.timeout-cancellation.adoc[Timeout with Cancellation] — Stop tokens for timeout diff --git a/doc/modules/ROOT/pages/7.examples/7f.timeout-cancellation.adoc b/doc/modules/ROOT/pages/7.examples/7f.timeout-cancellation.adoc index 7e5ce778..fa55a43b 100644 --- a/doc/modules/ROOT/pages/7.examples/7f.timeout-cancellation.adoc +++ b/doc/modules/ROOT/pages/7.examples/7f.timeout-cancellation.adoc @@ -10,7 +10,7 @@ Using stop tokens to implement operation timeouts. == Prerequisites -* Completed xref:7e.type-erased-echo.adoc[Type-Erased Echo] +* Completed xref:7.examples/7e.type-erased-echo.adoc[Type-Erased Echo] * Understanding of stop tokens from xref:../4.coroutines/4e.cancellation.adoc[Cancellation] == Source Code @@ -238,4 +238,4 @@ Cancelled (returned nullopt) == Next Steps -* xref:7g.parallel-fetch.adoc[Parallel Fetch] — Concurrent operations with when_all +* xref:7.examples/7g.parallel-fetch.adoc[Parallel Fetch] — Concurrent operations with when_all diff --git a/doc/modules/ROOT/pages/7.examples/7g.parallel-fetch.adoc b/doc/modules/ROOT/pages/7.examples/7g.parallel-fetch.adoc index e2aeb18b..db92a072 100644 --- a/doc/modules/ROOT/pages/7.examples/7g.parallel-fetch.adoc +++ b/doc/modules/ROOT/pages/7.examples/7g.parallel-fetch.adoc @@ -10,7 +10,7 @@ Running multiple operations concurrently with `when_all`. == Prerequisites -* Completed xref:7f.timeout-cancellation.adoc[Timeout with Cancellation] +* Completed xref:7.examples/7f.timeout-cancellation.adoc[Timeout with Cancellation] * Understanding of `when_all` from xref:../4.coroutines/4f.composition.adoc[Composition] == Source Code @@ -258,4 +258,4 @@ Caught error: B failed! == Next Steps -* xref:7h.custom-dynamic-buffer.adoc[Custom Dynamic Buffer] — Implementing your own buffer +* xref:7.examples/7h.custom-dynamic-buffer.adoc[Custom Dynamic Buffer] — Implementing your own buffer diff --git a/doc/modules/ROOT/pages/7.examples/7h.custom-dynamic-buffer.adoc b/doc/modules/ROOT/pages/7.examples/7h.custom-dynamic-buffer.adoc index 15a38bc1..10bc0a0d 100644 --- a/doc/modules/ROOT/pages/7.examples/7h.custom-dynamic-buffer.adoc +++ b/doc/modules/ROOT/pages/7.examples/7h.custom-dynamic-buffer.adoc @@ -10,7 +10,7 @@ Implementing the DynamicBuffer concept for a custom allocation strategy. == Prerequisites -* Completed xref:7g.parallel-fetch.adoc[Parallel Fetch] +* Completed xref:7.examples/7g.parallel-fetch.adoc[Parallel Fetch] * Understanding of dynamic buffers from xref:../5.buffers/5f.dynamic.adoc[Dynamic Buffers] == Source Code @@ -300,4 +300,4 @@ Buffer statistics: == Next Steps -* xref:7i.echo-server-corosio.adoc[Echo Server with Corosio] — Real networking +* xref:7.examples/7i.echo-server-corosio.adoc[Echo Server with Corosio] — Real networking diff --git a/doc/modules/ROOT/pages/7.examples/7i.echo-server-corosio.adoc b/doc/modules/ROOT/pages/7.examples/7i.echo-server-corosio.adoc index c0bfbe89..873afdad 100644 --- a/doc/modules/ROOT/pages/7.examples/7i.echo-server-corosio.adoc +++ b/doc/modules/ROOT/pages/7.examples/7i.echo-server-corosio.adoc @@ -10,7 +10,7 @@ A complete echo server using Corosio for real network I/O. == Prerequisites -* Completed xref:7h.custom-dynamic-buffer.adoc[Custom Dynamic Buffer] +* Completed xref:7.examples/7h.custom-dynamic-buffer.adoc[Custom Dynamic Buffer] * Corosio library installed * Understanding of TCP networking basics @@ -239,4 +239,4 @@ Server output: == Next Steps -* xref:7j.stream-pipeline.adoc[Stream Pipeline] — Data transformation chains +* xref:7.examples/7j.stream-pipeline.adoc[Stream Pipeline] — Data transformation chains diff --git a/doc/modules/ROOT/pages/7.examples/7j.stream-pipeline.adoc b/doc/modules/ROOT/pages/7.examples/7j.stream-pipeline.adoc index 9a1323fb..6f7453c0 100644 --- a/doc/modules/ROOT/pages/7.examples/7j.stream-pipeline.adoc +++ b/doc/modules/ROOT/pages/7.examples/7j.stream-pipeline.adoc @@ -10,7 +10,7 @@ Data transformation through a pipeline of sources and sinks. == Prerequisites -* Completed xref:7i.echo-server-corosio.adoc[Echo Server with Corosio] +* Completed xref:7.examples/7i.echo-server-corosio.adoc[Echo Server with Corosio] * Understanding of buffer sources/sinks from xref:../6.streams/6d.buffer-concepts.adoc[Buffer Concepts] == Source Code diff --git a/doc/modules/ROOT/pages/8.design/8d.ReadSource.adoc b/doc/modules/ROOT/pages/8.design/8d.ReadSource.adoc index 4b8c364d..7a00f512 100644 --- a/doc/modules/ROOT/pages/8.design/8d.ReadSource.adoc +++ b/doc/modules/ROOT/pages/8.design/8d.ReadSource.adoc @@ -348,7 +348,7 @@ Examples of types that satisfy `ReadSource`: == Why `read_some` Returns No Data on EOF -The `read_some` contract (inherited from `ReadStream`) requires that when `ec == cond::eof`, `n` is always 0. Data and EOF are delivered in separate calls. See xref:8a.ReadStream.adoc#_design_foundations_why_errors_exclude_data[ReadStream: Why Errors Exclude Data] for the full rationale. The key points: +The `read_some` contract (inherited from `ReadStream`) requires that when `ec == cond::eof`, `n` is always 0. Data and EOF are delivered in separate calls. See xref:8.design/8a.ReadStream.adoc#_design_foundations_why_errors_exclude_data[ReadStream: Why Errors Exclude Data] for the full rationale. The key points: - The clean trichotomy (success/EOF/error, where data implies success) eliminates an entire class of bugs where callers accidentally drop the final bytes of a stream. - Write-side atomicity (`write_eof(buffers)`) serves correctness for protocol framing. Read-side piggybacking would be a minor optimization with significant API cost. diff --git a/doc/modules/ROOT/pages/8.design/8j.any_buffer_sink.adoc b/doc/modules/ROOT/pages/8.design/8j.any_buffer_sink.adoc index 3e94d72f..fe31e5bc 100644 --- a/doc/modules/ROOT/pages/8.design/8j.any_buffer_sink.adoc +++ b/doc/modules/ROOT/pages/8.design/8j.any_buffer_sink.adoc @@ -153,7 +153,7 @@ The serializer never allocates a scratch buffer for the formatted output. The by == Awaitable Caching -`any_buffer_sink` uses the split vtable pattern described in xref:8h.TypeEraseAwaitable.adoc[Type-Erasing Awaitables]. Multiple async operations (`commit`, `commit_eof`, plus the four `WriteSink` operations when the concrete type supports them) share a single cached awaitable storage region. +`any_buffer_sink` uses the split vtable pattern described in xref:8.design/8h.TypeEraseAwaitable.adoc[Type-Erasing Awaitables]. Multiple async operations (`commit`, `commit_eof`, plus the four `WriteSink` operations when the concrete type supports them) share a single cached awaitable storage region. The constructor computes the maximum size and alignment across all awaitable types that the concrete type can produce and allocates that storage once. This reserves all virtual address space at construction time, so memory usage is measurable at server startup rather than growing piecemeal as requests arrive. diff --git a/doc/modules/ROOT/pages/8.design/8k.Executor.adoc b/doc/modules/ROOT/pages/8.design/8k.Executor.adoc index 82468506..1060fa8b 100644 --- a/doc/modules/ROOT/pages/8.design/8k.Executor.adoc +++ b/doc/modules/ROOT/pages/8.design/8k.Executor.adoc @@ -358,7 +358,7 @@ start(op); // -- too late For coroutines, this ordering is fatal. Coroutine frame allocation happens _before_ the coroutine body executes. The compiler calls `operator new` first, then constructs the promise, then begins execution. Any mechanism that provides the allocator _after_ the coroutine call -- receiver queries, `await_transform`, explicit method calls -- arrives after the frame is already allocated with the wrong (or default) allocator. -Capy's model flows context _forward_ from launcher to task. The `run_async(ex, alloc)(my_task())` two-phase invocation sets the thread-local allocator _before_ the task expression is evaluated, so `operator new` reads it in time. This is described in detail in xref:8l.RunApi.adoc[Run API]. +Capy's model flows context _forward_ from launcher to task. The `run_async(ex, alloc)(my_task())` two-phase invocation sets the thread-local allocator _before_ the task expression is evaluated, so `operator new` reads it in time. This is described in detail in xref:8.design/8l.RunApi.adoc[Run API]. The same forward-flowing model applies to executors. The launcher binds the executor before the task runs. The task's promise stores the executor and propagates it to nested awaitables via `await_transform`. Context flows from caller to callee at every level, never backward.