From 8235cf2b7a76b4dc789af807eec759e3d34983c9 Mon Sep 17 00:00:00 2001 From: Andrzej Krzemienski Date: Fri, 11 Sep 2026 23:53:13 +0200 Subject: [PATCH] Docs: remove the "Why Capy?" page The comparison with ASIO moved to a separate page. The incorrect statement about same-executor-guarantee was removed. --- doc/.pa11yci.json | 1 - doc/.vale.ini | 4 +- doc/lint/baseline.json | 60 +++++++++---------- doc/modules/ROOT/nav.adoc | 8 +-- .../pages/4.coroutines/4a.flow-control.adoc | 9 +++ doc/modules/ROOT/pages/9.design/9.intro.adoc | 7 ++- .../9m.WhyNotAsio.adoc} | 26 +------- ...WhyNotCobalt.adoc => 9n.WhyNotCobalt.adoc} | 4 +- ...epts.adoc => 9o.WhyNotCobaltConcepts.adoc} | 12 ++-- .../{9o.WhyNotTMC.adoc => 9p.WhyNotTMC.adoc} | 8 +-- ...y_not_cobalt.cpp => 9n_why_not_cobalt.cpp} | 2 +- ...pts.cpp => 9o_why_not_cobalt_concepts.cpp} | 2 +- ...{9o_why_not_tmc.cpp => 9p_why_not_tmc.cpp} | 4 +- test/doc/snippets/why_capy.cpp | 34 ----------- 14 files changed, 66 insertions(+), 115 deletions(-) rename doc/modules/ROOT/pages/{why-capy.adoc => 9.design/9m.WhyNotAsio.adoc} (91%) rename doc/modules/ROOT/pages/9.design/{9m.WhyNotCobalt.adoc => 9n.WhyNotCobalt.adoc} (99%) rename doc/modules/ROOT/pages/9.design/{9n.WhyNotCobaltConcepts.adoc => 9o.WhyNotCobaltConcepts.adoc} (97%) rename doc/modules/ROOT/pages/9.design/{9o.WhyNotTMC.adoc => 9p.WhyNotTMC.adoc} (98%) rename test/doc/snippets/{9m_why_not_cobalt.cpp => 9n_why_not_cobalt.cpp} (91%) rename test/doc/snippets/{9n_why_not_cobalt_concepts.cpp => 9o_why_not_cobalt_concepts.cpp} (98%) rename test/doc/snippets/{9o_why_not_tmc.cpp => 9p_why_not_tmc.cpp} (95%) delete mode 100644 test/doc/snippets/why_capy.cpp diff --git a/doc/.pa11yci.json b/doc/.pa11yci.json index 7895d467b..dbca90d74 100644 --- a/doc/.pa11yci.json +++ b/doc/.pa11yci.json @@ -12,7 +12,6 @@ }, "urls": [ "http://localhost:8088/capy/index.html", - "http://localhost:8088/capy/why-capy.html", "http://localhost:8088/capy/quick-start.html", "http://localhost:8088/capy/4.coroutines/4b.tasks.html", "http://localhost:8088/capy/reference/boost/capy.html" diff --git a/doc/.vale.ini b/doc/.vale.ini index f78aa00a7..d9c625168 100644 --- a/doc/.vale.ini +++ b/doc/.vale.ini @@ -35,7 +35,7 @@ BasedOnStyles = Vale, Google, Capy ; Two known-affected spots as of the fix-round-1 report, neither currently flagged live by ; Vale, both still real defects to fix from the worklist rather than from a fresh Vale run: ; `stop_token` bare in prose at 9l.RunApi.adoc:171, and `Intentionally` after a colon at -; 9o.WhyNotTMC.adoc:68. If you are tempted to re-add a BlockIgnores line for source blocks: +; 9p.WhyNotTMC.adoc:68. If you are tempted to re-add a BlockIgnores line for source blocks: ; don't. Confirm first, with an isolated fixture, that Vale is actually failing to skip ; something. ; Ignore inline code spans (backticks) AND `cpp:target[...]` reference macros @@ -53,7 +53,7 @@ BasedOnStyles = Vale, Google, Capy ; phrase-exact form left exposed while suppressing its 16 siblings. ; This is NOT a Google.Colons demotion, on purpose: demoting the rule would also ; hide the genuine non-idiom Colons hits. Measured after: 11 survive (8 .adoc, all -; in 9o.WhyNotTMC/9b.Separation/3b.synchronization; 3 docstring "Pass ..." hits in +; in 9p.WhyNotTMC/9b.Separation/3b.synchronization; 3 docstring "Pass ..." hits in ; io/any_*_stream.hpp). 30 - 16 does not equal 11 because the Vocab above also ; removed 3 .adoc Colons hits — Vale treats vocabulary terms as capitalisation ; exceptions, and "Capy"/"Corosio"/"Coroutine" after a colon were never defects. diff --git a/doc/lint/baseline.json b/doc/lint/baseline.json index 932510712..38d6ed262 100644 --- a/doc/lint/baseline.json +++ b/doc/lint/baseline.json @@ -73,28 +73,28 @@ "modules/ROOT/pages/9.design/9i.TypeEraseAwaitable.adoc:#5:Vale.Spelling", "modules/ROOT/pages/9.design/9k.Executor.adoc:#1:Capy.NoFluff", "modules/ROOT/pages/9.design/9k.Executor.adoc:#1:Google.OxfordComma", - "modules/ROOT/pages/9.design/9n.WhyNotCobaltConcepts.adoc:#1:Capy.SimpleTense", - "modules/ROOT/pages/9.design/9n.WhyNotCobaltConcepts.adoc:#1:Google.OxfordComma", - "modules/ROOT/pages/9.design/9n.WhyNotCobaltConcepts.adoc:#1:Google.Will", - "modules/ROOT/pages/9.design/9n.WhyNotCobaltConcepts.adoc:#1:Vale.Spelling", - "modules/ROOT/pages/9.design/9n.WhyNotCobaltConcepts.adoc:#2:Capy.SimpleTense", - "modules/ROOT/pages/9.design/9n.WhyNotCobaltConcepts.adoc:#2:Google.Will", - "modules/ROOT/pages/9.design/9o.WhyNotTMC.adoc:#10:Vale.Spelling", - "modules/ROOT/pages/9.design/9o.WhyNotTMC.adoc:#1:Google.Colons", - "modules/ROOT/pages/9.design/9o.WhyNotTMC.adoc:#1:Vale.Spelling", - "modules/ROOT/pages/9.design/9o.WhyNotTMC.adoc:#2:Google.Colons", - "modules/ROOT/pages/9.design/9o.WhyNotTMC.adoc:#2:Vale.Spelling", - "modules/ROOT/pages/9.design/9o.WhyNotTMC.adoc:#3:Google.Colons", - "modules/ROOT/pages/9.design/9o.WhyNotTMC.adoc:#3:Vale.Spelling", - "modules/ROOT/pages/9.design/9o.WhyNotTMC.adoc:#4:Google.Colons", - "modules/ROOT/pages/9.design/9o.WhyNotTMC.adoc:#4:Vale.Spelling", - "modules/ROOT/pages/9.design/9o.WhyNotTMC.adoc:#5:Google.Colons", - "modules/ROOT/pages/9.design/9o.WhyNotTMC.adoc:#5:Vale.Spelling", - "modules/ROOT/pages/9.design/9o.WhyNotTMC.adoc:#6:Google.Colons", - "modules/ROOT/pages/9.design/9o.WhyNotTMC.adoc:#6:Vale.Spelling", - "modules/ROOT/pages/9.design/9o.WhyNotTMC.adoc:#7:Vale.Spelling", - "modules/ROOT/pages/9.design/9o.WhyNotTMC.adoc:#8:Vale.Spelling", - "modules/ROOT/pages/9.design/9o.WhyNotTMC.adoc:#9:Vale.Spelling" + "modules/ROOT/pages/9.design/9o.WhyNotCobaltConcepts.adoc:#1:Capy.SimpleTense", + "modules/ROOT/pages/9.design/9o.WhyNotCobaltConcepts.adoc:#1:Google.OxfordComma", + "modules/ROOT/pages/9.design/9o.WhyNotCobaltConcepts.adoc:#1:Google.Will", + "modules/ROOT/pages/9.design/9o.WhyNotCobaltConcepts.adoc:#1:Vale.Spelling", + "modules/ROOT/pages/9.design/9o.WhyNotCobaltConcepts.adoc:#2:Capy.SimpleTense", + "modules/ROOT/pages/9.design/9o.WhyNotCobaltConcepts.adoc:#2:Google.Will", + "modules/ROOT/pages/9.design/9p.WhyNotTMC.adoc:#10:Vale.Spelling", + "modules/ROOT/pages/9.design/9p.WhyNotTMC.adoc:#1:Google.Colons", + "modules/ROOT/pages/9.design/9p.WhyNotTMC.adoc:#1:Vale.Spelling", + "modules/ROOT/pages/9.design/9p.WhyNotTMC.adoc:#2:Google.Colons", + "modules/ROOT/pages/9.design/9p.WhyNotTMC.adoc:#2:Vale.Spelling", + "modules/ROOT/pages/9.design/9p.WhyNotTMC.adoc:#3:Google.Colons", + "modules/ROOT/pages/9.design/9p.WhyNotTMC.adoc:#3:Vale.Spelling", + "modules/ROOT/pages/9.design/9p.WhyNotTMC.adoc:#4:Google.Colons", + "modules/ROOT/pages/9.design/9p.WhyNotTMC.adoc:#4:Vale.Spelling", + "modules/ROOT/pages/9.design/9p.WhyNotTMC.adoc:#5:Google.Colons", + "modules/ROOT/pages/9.design/9p.WhyNotTMC.adoc:#5:Vale.Spelling", + "modules/ROOT/pages/9.design/9p.WhyNotTMC.adoc:#6:Google.Colons", + "modules/ROOT/pages/9.design/9p.WhyNotTMC.adoc:#6:Vale.Spelling", + "modules/ROOT/pages/9.design/9p.WhyNotTMC.adoc:#7:Vale.Spelling", + "modules/ROOT/pages/9.design/9p.WhyNotTMC.adoc:#8:Vale.Spelling", + "modules/ROOT/pages/9.design/9p.WhyNotTMC.adoc:#9:Vale.Spelling" ] }, "vale_docstrings": { @@ -448,14 +448,14 @@ "advisory-C2:modules/ROOT/pages/9.design/9l.RunApi.adoc:#2:sentence over 25 words", "advisory-C2:modules/ROOT/pages/9.design/9l.RunApi.adoc:#3:sentence over 25 words", "advisory-C2:modules/ROOT/pages/9.design/9l.RunApi.adoc:#4:sentence over 25 words", - "advisory-C2:modules/ROOT/pages/9.design/9m.WhyNotCobalt.adoc:#1:sentence over 25 words", - "advisory-C2:modules/ROOT/pages/9.design/9m.WhyNotCobalt.adoc:#2:sentence over 25 words", - "advisory-C2:modules/ROOT/pages/9.design/9m.WhyNotCobalt.adoc:#3:sentence over 25 words", - "advisory-C2:modules/ROOT/pages/9.design/9n.WhyNotCobaltConcepts.adoc:#1:sentence over 25 words", - "advisory-C2:modules/ROOT/pages/9.design/9n.WhyNotCobaltConcepts.adoc:#2:sentence over 25 words", - "advisory-C2:modules/ROOT/pages/9.design/9n.WhyNotCobaltConcepts.adoc:#3:sentence over 25 words", - "advisory-C2:modules/ROOT/pages/9.design/9n.WhyNotCobaltConcepts.adoc:#4:sentence over 25 words", - "advisory-C2:modules/ROOT/pages/9.design/9n.WhyNotCobaltConcepts.adoc:#5:sentence over 25 words", + "advisory-C2:modules/ROOT/pages/9.design/9n.WhyNotCobalt.adoc:#1:sentence over 25 words", + "advisory-C2:modules/ROOT/pages/9.design/9n.WhyNotCobalt.adoc:#2:sentence over 25 words", + "advisory-C2:modules/ROOT/pages/9.design/9n.WhyNotCobalt.adoc:#3:sentence over 25 words", + "advisory-C2:modules/ROOT/pages/9.design/9o.WhyNotCobaltConcepts.adoc:#1:sentence over 25 words", + "advisory-C2:modules/ROOT/pages/9.design/9o.WhyNotCobaltConcepts.adoc:#2:sentence over 25 words", + "advisory-C2:modules/ROOT/pages/9.design/9o.WhyNotCobaltConcepts.adoc:#3:sentence over 25 words", + "advisory-C2:modules/ROOT/pages/9.design/9o.WhyNotCobaltConcepts.adoc:#4:sentence over 25 words", + "advisory-C2:modules/ROOT/pages/9.design/9o.WhyNotCobaltConcepts.adoc:#5:sentence over 25 words", "advisory-C2:modules/ROOT/pages/A.specification-methods/Ab.cancellation.adoc:#1:sentence over 25 words", "advisory-C2:modules/ROOT/pages/A.specification-methods/Ab.cancellation.adoc:#2:sentence over 25 words", "advisory-C2:modules/ROOT/pages/A.specification-methods/Ac.contingencies.adoc:#1:sentence over 25 words", diff --git a/doc/modules/ROOT/nav.adoc b/doc/modules/ROOT/nav.adoc index 52812b1d8..f904b43e6 100644 --- a/doc/modules/ROOT/nav.adoc +++ b/doc/modules/ROOT/nav.adoc @@ -1,5 +1,4 @@ * xref:index.adoc[Introduction] -* xref:why-capy.adoc[Why Capy?] * xref:quick-start.adoc[Quick Start] * xref:2.cpp20-coroutines/2.intro.adoc[Introduction To {cpp}20 Coroutines] ** xref:2.cpp20-coroutines/2a.foundations.adoc[Coroutine Foundations] @@ -53,9 +52,10 @@ ** xref:9.design/9i.TypeEraseAwaitable.adoc[Type-Erasing Awaitables] ** xref:9.design/9k.Executor.adoc[Executor] ** xref:9.design/9l.RunApi.adoc[Run API] -** xref:9.design/9m.WhyNotCobalt.adoc[Why Not Cobalt?] -** xref:9.design/9n.WhyNotCobaltConcepts.adoc[Why Not Cobalt Concepts?] -** xref:9.design/9o.WhyNotTMC.adoc[Why Not TooManyCooks?] +** xref:9.design/9m.WhyNotAsio.adoc[Why Not Asio?] +** xref:9.design/9n.WhyNotCobalt.adoc[Why Not Cobalt?] +** xref:9.design/9o.WhyNotCobaltConcepts.adoc[Why Not Cobalt Concepts?] +** xref:9.design/9p.WhyNotTMC.adoc[Why Not TooManyCooks?] * xref:A.specification-methods/A.intro.adoc[Methods of API Description] ** xref:A.specification-methods/Ab.cancellation.adoc[Cancellation] ** xref:A.specification-methods/Ac.contingencies.adoc[Contingencies] diff --git a/doc/modules/ROOT/pages/4.coroutines/4a.flow-control.adoc b/doc/modules/ROOT/pages/4.coroutines/4a.flow-control.adoc index 9c496f270..67abd519f 100644 --- a/doc/modules/ROOT/pages/4.coroutines/4a.flow-control.adoc +++ b/doc/modules/ROOT/pages/4.coroutines/4a.flow-control.adoc @@ -1,3 +1,12 @@ +// +// Copyright (c) 2026 Andrzej Krzemieński (akrzemi1@gmail.com) +// +// 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 +// + = Flow control :page-mode: explanation diff --git a/doc/modules/ROOT/pages/9.design/9.intro.adoc b/doc/modules/ROOT/pages/9.design/9.intro.adoc index f15056297..dfbf87ffd 100644 --- a/doc/modules/ROOT/pages/9.design/9.intro.adoc +++ b/doc/modules/ROOT/pages/9.design/9.intro.adoc @@ -23,6 +23,7 @@ Each page examines one concept or facility in depth: the rationale behind its de * xref:9.design/9i.TypeEraseAwaitable.adoc[Type-Erasing Awaitables] -- How the `any_*` wrappers achieve zero steady-state allocation. * xref:9.design/9k.Executor.adoc[Executor] -- The `Executor` concept's relationship to Asio, and why `dispatch` returns a coroutine handle. * xref:9.design/9l.RunApi.adoc[Run API] -- Why `run_async` and `run` use a two-phase `f(context)(task)` call syntax. -* xref:9.design/9m.WhyNotCobalt.adoc[Why Not Cobalt?] -- How Capy's foundation differs from Boost.Cobalt's Asio-based design. -* xref:9.design/9n.WhyNotCobaltConcepts.adoc[Why Not Cobalt Concepts?] -- A side-by-side look at type-erased write-stream algorithms in both libraries. -* xref:9.design/9o.WhyNotTMC.adoc[Why Not TooManyCooks?] -- Choosing between Capy and TooManyCooks by workload: network I/O versus compute. +* xref:9.design/9m.WhyNotAsio.adoc[Why Not Asio?] -- What Capy keeps from Boost.Asio, and what changes once the continuation is always a coroutine. +* xref:9.design/9n.WhyNotCobalt.adoc[Why Not Cobalt?] -- How Capy's foundation differs from Boost.Cobalt's Asio-based design. +* xref:9.design/9o.WhyNotCobaltConcepts.adoc[Why Not Cobalt Concepts?] -- A side-by-side look at type-erased write-stream algorithms in both libraries. +* xref:9.design/9p.WhyNotTMC.adoc[Why Not TooManyCooks?] -- Choosing between Capy and TooManyCooks by workload: network I/O versus compute. diff --git a/doc/modules/ROOT/pages/why-capy.adoc b/doc/modules/ROOT/pages/9.design/9m.WhyNotAsio.adoc similarity index 91% rename from doc/modules/ROOT/pages/why-capy.adoc rename to doc/modules/ROOT/pages/9.design/9m.WhyNotAsio.adoc index e7e6a38b3..09a66dc51 100644 --- a/doc/modules/ROOT/pages/why-capy.adoc +++ b/doc/modules/ROOT/pages/9.design/9m.WhyNotAsio.adoc @@ -1,26 +1,6 @@ -= Why Capy? += Capy and Boost.Asio: A Comparison :page-mode: explanation -Capy makes `co_await` the only way to do asynchronous work. There are no callbacks, no futures, and no sender/receiver layer to reconcile. - -That restriction buys a guarantee the hybrid libraries cannot make: *a coroutine always resumes on the executor it was started with.* State you touch between two suspension points needs no mutex, because nothing else can run there. An awaitable that could resume you on any thread is rejected at compile time. - -[source,cpp] ----- -include::example$snippets/why_capy.cpp[tag=invariant] ----- - -[NOTE] -==== -See xref:4.coroutines/4d.executors.adoc#the-same-executor-invariant[the same-executor invariant] for the rationale and xref:4.coroutines/4e.io-awaitable.adoc#bridging-a-foreign-awaitable[bridging a foreign awaitable] for the escape hatch. -==== - -== What Capy Is Not - -Capy is not a networking library. It has no sockets, no acceptors, no DNS, no TLS, and no platform event loop. Those belong to Corosio, which is built on Capy. - -Capy is the execution model and the byte-stream layer beneath them. It also stands alone for work that never touches the network: HTTP parsing, protocol state machines, serialization. - == Where Capy Advances Beyond Asio Boost.Asio is currently the world leader in portable asynchronous I/O. The standard is silent here. The global ecosystem offers nothing comparable. @@ -325,7 +305,3 @@ Meanwhile, the {cpp} standards committee has produced `std::execution`—a sende Boost has always been where the practical meets the principled. Where real-world feedback shapes design. Where code ships before papers standardize. Capy continues this tradition. This library advances beyond Asio in the domains where they overlap. Not by abandoning what works, but by building on it. Not by chasing theoretical purity, but by solving the problems that have frustrated {cpp} developers for years. Those problems are template explosion, compile-time costs, error message novels, ergonomic concurrency, and more. - -Capy is already the foundation for work that does not look alike. CERN's traccc project uses Capy without Corosio for GPU reconstruction pipelines. The Http parser is built entirely on Capy's byte streams. Corosio, Websocket, Beast2 and Burl build the networking stack on top of it. - -Capy has no external dependencies and does not require Boost. diff --git a/doc/modules/ROOT/pages/9.design/9m.WhyNotCobalt.adoc b/doc/modules/ROOT/pages/9.design/9n.WhyNotCobalt.adoc similarity index 99% rename from doc/modules/ROOT/pages/9.design/9m.WhyNotCobalt.adoc rename to doc/modules/ROOT/pages/9.design/9n.WhyNotCobalt.adoc index e32da10c0..c26e81cb2 100644 --- a/doc/modules/ROOT/pages/9.design/9m.WhyNotCobalt.adoc +++ b/doc/modules/ROOT/pages/9.design/9n.WhyNotCobalt.adoc @@ -78,7 +78,7 @@ Templates can achieve this by type-erasing every customization point. The cost m == Stream Concepts -Capy defines three coroutine-only stream concepts. Cobalt inherits Asio's `AsyncReadStream` and `AsyncWriteStream`, which are hybrid concepts supporting callbacks, futures, and coroutines. Cobalt's `cobalt::io` wrappers simplify the API, but still include full Asio headers. See xref:9.design/9n.WhyNotCobaltConcepts.adoc[Write Stream Design] for a detailed comparison of the two approaches. +Capy defines three coroutine-only stream concepts. Cobalt inherits Asio's `AsyncReadStream` and `AsyncWriteStream`, which are hybrid concepts supporting callbacks, futures, and coroutines. Cobalt's `cobalt::io` wrappers simplify the API, but still include full Asio headers. See xref:9.design/9o.WhyNotCobaltConcepts.adoc[Write Stream Design] for a detailed comparison of the two approaches. Capy's concepts form a small, flat set: cpp:ReadStream[] and cpp:WriteStream[] each define a single partial-transfer primitive (`read_some`, `write_some`); cpp:Stream[] requires both. There is no further refinement. @@ -222,7 +222,7 @@ Capy introduces the https://wg21.link/P4003[IoAwaitable protocol] and uses it fo [source,cpp] ---- -include::example$snippets/9m_why_not_cobalt.cpp[tag=await_suspend_env,indent=0] +include::example$snippets/9n_why_not_cobalt.cpp[tag=await_suspend_env,indent=0] ---- No thread-local state. No ambient context. The executor and stop token flow forward through the call chain via the cpp:io_env[] parameter. diff --git a/doc/modules/ROOT/pages/9.design/9n.WhyNotCobaltConcepts.adoc b/doc/modules/ROOT/pages/9.design/9o.WhyNotCobaltConcepts.adoc similarity index 97% rename from doc/modules/ROOT/pages/9.design/9n.WhyNotCobaltConcepts.adoc rename to doc/modules/ROOT/pages/9.design/9o.WhyNotCobaltConcepts.adoc index c876e8c85..b578e0dba 100644 --- a/doc/modules/ROOT/pages/9.design/9n.WhyNotCobaltConcepts.adoc +++ b/doc/modules/ROOT/pages/9.design/9o.WhyNotCobaltConcepts.adoc @@ -5,7 +5,7 @@ Both Capy and Cobalt allow you to write a non-template coroutine algorithm that [source,cpp] ---- -include::example$snippets/9n_why_not_cobalt_concepts.cpp[tag=capy_signature] +include::example$snippets/9o_why_not_cobalt_concepts.cpp[tag=capy_signature] ---- [source,cpp,role=external] @@ -121,7 +121,7 @@ Capy's cpp:IoAwaitable[] protocol passes the execution environment as an explici [source,cpp] ---- -include::example$snippets/9n_why_not_cobalt_concepts.cpp[tag=await_suspend_env,indent=0] +include::example$snippets/9o_why_not_cobalt_concepts.cpp[tag=await_suspend_env,indent=0] ---- The executor and stop token flow forward structurally through the call chain via cpp:io_env[]. If a task's machinery does not provide them, the code does not compile. There is no fallback. @@ -222,7 +222,7 @@ The type-erased wrapper cpp:any_write_stream[] also models the cpp:WriteStream[] [source,cpp] ---- -include::example$snippets/9n_why_not_cobalt_concepts.cpp[tag=any_write_some_template] +include::example$snippets/9o_why_not_cobalt_concepts.cpp[tag=any_write_some_template] ---- Type erasure does not narrow the interface. @@ -273,14 +273,14 @@ Capy's cpp:WriteStream[] concept includes semantic requirements in the concept's [source,cpp] ---- -include::example$snippets/9n_why_not_cobalt_concepts.cpp[tag=semantics_quote] +include::example$snippets/9o_why_not_cobalt_concepts.cpp[tag=semantics_quote] ---- The concept also includes a coroutine-specific warning about buffer lifetime: [source,cpp] ---- -include::example$snippets/9n_why_not_cobalt_concepts.cpp[tag=lifetime_warning] +include::example$snippets/9o_why_not_cobalt_concepts.cpp[tag=lifetime_warning] ---- [cols="1,1,1"] @@ -402,7 +402,7 @@ Capy's cpp:any_write_stream[] constructor preallocates storage sized exactly to [source,cpp] ---- -include::example$snippets/9n_why_not_cobalt_concepts.cpp[tag=ctor_prealloc] +include::example$snippets/9o_why_not_cobalt_concepts.cpp[tag=ctor_prealloc] ---- After construction, each `co_await stream.write_some(buf)` reuses this preallocated storage. There is no per-operation allocation and no fixed-size buffer in the coroutine frame. diff --git a/doc/modules/ROOT/pages/9.design/9o.WhyNotTMC.adoc b/doc/modules/ROOT/pages/9.design/9p.WhyNotTMC.adoc similarity index 98% rename from doc/modules/ROOT/pages/9.design/9o.WhyNotTMC.adoc rename to doc/modules/ROOT/pages/9.design/9p.WhyNotTMC.adoc index 921af7222..2faae15f3 100644 --- a/doc/modules/ROOT/pages/9.design/9o.WhyNotTMC.adoc +++ b/doc/modules/ROOT/pages/9.design/9p.WhyNotTMC.adoc @@ -141,7 +141,7 @@ HALO (Heap Allocation Lowering Optimization) lets compilers eliminate coroutine [source,cpp] ---- -include::example$snippets/9o_why_not_tmc.cpp[tag=arena,indent=0] +include::example$snippets/9p_why_not_tmc.cpp[tag=arena,indent=0] ---- *TMC provides:* @@ -160,7 +160,7 @@ When you write `co_await something`, what happens? [source,cpp] ---- -include::example$snippets/9o_why_not_tmc.cpp[tags=std_suspend_void;std_suspend_bool;std_suspend_handle,indent=0] +include::example$snippets/9p_why_not_tmc.cpp[tags=std_suspend_void;std_suspend_bool;std_suspend_handle,indent=0] ---- The awaitable receives a handle to resume. That's all. No information about where to resume, no cancellation mechanism. @@ -169,7 +169,7 @@ The awaitable receives a handle to resume. That's all. No information about wher [source,cpp] ---- -include::example$snippets/9o_why_not_tmc.cpp[tag=await_suspend_env,indent=0] +include::example$snippets/9p_why_not_tmc.cpp[tag=await_suspend_env,indent=0] ---- The awaitable receives: @@ -203,7 +203,7 @@ What happens when you `co_await` an awaitable that doesn't implement the extende [source,cpp] ---- -include::example$snippets/9o_why_not_tmc.cpp[tag=strict_static_assert,indent=0] +include::example$snippets/9p_why_not_tmc.cpp[tag=strict_static_assert,indent=0] ---- *TMC:* Wrap in a trampoline that captures current context. diff --git a/test/doc/snippets/9m_why_not_cobalt.cpp b/test/doc/snippets/9n_why_not_cobalt.cpp similarity index 91% rename from test/doc/snippets/9m_why_not_cobalt.cpp rename to test/doc/snippets/9n_why_not_cobalt.cpp index 4fe009d35..22c0316bd 100644 --- a/test/doc/snippets/9m_why_not_cobalt.cpp +++ b/test/doc/snippets/9n_why_not_cobalt.cpp @@ -8,7 +8,7 @@ // Official repository: https://github.com/cppalliance/capy // -// Compiled fragments shown in pages/9.design/9m.WhyNotCobalt.adoc. +// Compiled fragments shown in pages/9.design/9n.WhyNotCobalt.adoc. #include "../doc_warnings.hpp" diff --git a/test/doc/snippets/9n_why_not_cobalt_concepts.cpp b/test/doc/snippets/9o_why_not_cobalt_concepts.cpp similarity index 98% rename from test/doc/snippets/9n_why_not_cobalt_concepts.cpp rename to test/doc/snippets/9o_why_not_cobalt_concepts.cpp index a26029b5f..5ff512073 100644 --- a/test/doc/snippets/9n_why_not_cobalt_concepts.cpp +++ b/test/doc/snippets/9o_why_not_cobalt_concepts.cpp @@ -8,7 +8,7 @@ // Official repository: https://github.com/cppalliance/capy // -// Compiled fragments shown in pages/9.design/9n.WhyNotCobaltConcepts.adoc. +// Compiled fragments shown in pages/9.design/9o.WhyNotCobaltConcepts.adoc. #include "../doc_warnings.hpp" diff --git a/test/doc/snippets/9o_why_not_tmc.cpp b/test/doc/snippets/9p_why_not_tmc.cpp similarity index 95% rename from test/doc/snippets/9o_why_not_tmc.cpp rename to test/doc/snippets/9p_why_not_tmc.cpp index 4e4f942dc..f6c60a4c6 100644 --- a/test/doc/snippets/9o_why_not_tmc.cpp +++ b/test/doc/snippets/9p_why_not_tmc.cpp @@ -8,7 +8,7 @@ // Official repository: https://github.com/cppalliance/capy // -// Compiled fragments shown in pages/9.design/9o.WhyNotTMC.adoc. +// Compiled fragments shown in pages/9.design/9p.WhyNotTMC.adoc. #include "../doc_warnings.hpp" @@ -113,4 +113,4 @@ struct why_not_tmc_test } // namespace -TEST_SUITE(why_not_tmc_test, "boost.capy.doc.9o_why_not_tmc"); +TEST_SUITE(why_not_tmc_test, "boost.capy.doc.9p_why_not_tmc"); diff --git a/test/doc/snippets/why_capy.cpp b/test/doc/snippets/why_capy.cpp deleted file mode 100644 index 86ecb115c..000000000 --- a/test/doc/snippets/why_capy.cpp +++ /dev/null @@ -1,34 +0,0 @@ -// -// Copyright (c) 2026 Steve Gerbino -// Copyright (c) 2026 Michael Vandeberg -// -// 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 -// - -#include "../doc_warnings.hpp" - -// tag::invariant[] -#include -#include -#include - -namespace capy = boost::capy; - -// Every resumption happens on the executor this task was started with, so -// `count` needs no mutex: nothing else can run between the suspension -// points. -capy::task<> count_messages(capy::any_stream& stream, int& count) -{ - char buf[64]; - for(;;) - { - auto [ec, n] = co_await stream.read_some(capy::make_buffer(buf)); - if(ec) - break; - ++count; - } -} -// end::invariant[]