docs: address the remaining mailing-list review feedback

From the review result:

Corosio: address the documentation comments in this review: https://lists.boost.org/archives/list/boost%40lists.boost.org/message/KHNY67ZNXFWT54EIWDOJPHN4KO6KJLN4

Source: Boost review result (conditional acceptance), Boost mailing list, September 2026. The linked message is "Some thoughts on Corosio" (July 2026).

Items from that message not already tracked in #324:

Dark mode: black text on dark-blue background is hard to read
UDP tutorial understates IP fragmentation: fragmented datagrams may be silently discarded (IPv4 practical limit as low as 576 bytes), so oversized datagrams are a correctness hazard, not just a performance note
Doc examples pervasively pass coroutine arguments by reference/string_view; establish and apply a safe-arguments convention for examples
"Opening and Closing TCP Connections" draws the branching TCP close sequence as a linear list
Document executor affinity (class-level thread safety is documented; affinity is not)
Document the rationale for io_context combining I/O waiting with coroutine execution
Hash Server tutorial: compute_fnv1a should be a plain function, not a coroutine

I’d like to work on this, happy to take it. (Can’t be assigned yet since I’m not in the org.)

@sgerbino

@sgerbino About this item:

Hash Server tutorial: compute_fnv1a should be a plain function, not a coroutine

capy::run(ex)(...) only accepts a task, so to run the hash on the thread pool something still has to be a coroutine. I see two ways to make compute_fnv1a a plain function in hash_server.cpp:

A thin named wrapper:

std::uint64_t
compute_fnv1a(char const* data, std::size_t len);   // plain

capy::task<std::uint64_t>
hash_task(char const* data, std::size_t len)
{
    co_return compute_fnv1a(data, len);
}

// in do_session
auto hash = co_await capy::run(pool.get_executor())(hash_task(buf, n));

A coroutine lambda inside do_session, the same pattern capy uses in test/unit/ex/run.cpp:

auto hash = co_await capy::run(pool.get_executor())(
    [](char const* data, std::size_t len) -> capy::task<std::uint64_t> {
        co_return compute_fnv1a(data, len);
    }(buf, n));

I lean towards 2, which is the "extra lambda" the review mentions: it keeps a single reusable plain function and shows the executor switch at the call site. The arguments are passed as parameters rather than captured, in line with the review's point about references in coroutines; data stays valid because do_session is suspended until the hash completes. Which do you prefer?

docs: keep the signals server example off a dead local

docs: let the acceptor example's accept loop own its acceptor

docs: say a started task's early reads can dangle too

docs: say the Hash Server session stays suspended during the hash

docs: drop "symmetric transfer" from the io_context rationale

Revert "docs: make description-list terms readable in dark mode"

docs: fix the examples and wording the PR review flagged

docs: correct the resume wording and other points the PR review flagged

docs: draw the TCP connection figures with Mermaid

docs: warn that fragmented UDP datagrams may never arrive

docs: pass started coroutines what they read by value

docs: show the two ways a TCP connection closes

docs: state which executor resumes an awaiting coroutine

docs: explain why io_context also runs coroutines

docs: make the Hash Server's compute_fnv1a a plain function

docs: fix the examples and wording the PR review flagged

docs: correct the resume wording and other points the PR review flagged

docs: draw the TCP connection figures with Mermaid

Resolved by #412

Navigation Menu

Repository navigation

docs: address the remaining mailing-list review feedback #353

12 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

docs: address the remaining mailing-list review feedback #353

Description

Activity

TheLingeringWill commented on Nov 4, 2026

TheLingeringWill commented on Nov 4, 2026

12 remaining items

sgerbino commented on Nov 9, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions