docs: explain Capy's programming model

[akrzemi1]

No description provided.

[vinniefalco]

A thousand lines were replaced with 200 lines?

[cppalliance-bot]

An automated preview of the documentation is available at https://289.capy.prtest3.cppalliance.org/index.html

If more commits are pushed to the pull request, the docs will rebuild at the same URL.

2026-05-22 20:56:53 UTC

[akrzemi1]

A thousand lines were replaced with 200 lines?

Isn't this progress?

[cppalliance-bot]

GCOVR code coverage report https://289.capy.prtest3.cppalliance.org/gcovr/index.html
LCOV code coverage report https://289.capy.prtest3.cppalliance.org/genhtml/index.html
Coverage Diff Report https://289.capy.prtest3.cppalliance.org/diff-report/index.html

Build time: 2026-05-22 21:09:39 UTC

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.27%. Comparing base (1e16ca9) to head (b78b314).
⚠️ Report is 1 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #289      +/-   ##
===========================================
+ Coverage    92.24%   92.27%   +0.02%     
===========================================
  Files          164      164              
  Lines         8862     8862              
===========================================
+ Hits          8175     8177       +2     
+ Misses         687      685       -2     

Flag	Coverage Δ
linux	92.26% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.
see 1 file with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 1e16ca9...b78b314. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[vinniefalco]

The previous documentation was verbose, but it did introduce the reader to the concept of multi-threading

[akrzemi1]

I can certainly put that part back. But let me try to convince you why this would be suboptimal.

1. Having this chapter does not help the reader understand or use Capy better. In terms of documentation ergonomics the user looses.
2. The section is called "Introduction to concurrency" but in fact it describes C++ threads. This is the multi-threading model Capy doesn't use, and rightly so. ASIO can do concurrency on a single thread, and so can Capy, I would guess.
3. The C++ primitives -- std::thread, std::async, std::future -- are bug prone. It is practically impossible to use them correctly. See:
   • https://akrzemi1.wordpress.com/2012/11/14/not-using-stdthread/
   • https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3780.pdf

Keeping the section as is would inseminate bad practices. If we need to introduce the notion of concurrency, that would reqire a different approach, anyway.