Fault injection

.github/workflows/ci.yml

@@ -861,6 +861,7 @@ jobs:
             cd boost-root
             cmake -S . -B build \
               -DCMAKE_BUILD_TYPE=Release \
+              -DBUILD_TESTING=ON \
               -DBOOST_INCLUDE_LIBRARIES="${{ steps.patch.outputs.module }}" \
               -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
             cmake --build build --target tests -j$(sysctl -n hw.ncpu)

doc/error-handling-rulebook.md

@@ -26,6 +26,16 @@ by classifying its failures:
   would be an attractive nuisance: the retry it invites is a
   double-close hazard, because POSIX leaves descriptor release under
   `EINTR` unspecified.
+- **No caller at all** — an internal wakeup (`interrupt_reactor()`,
+  `wake_self()`) has nobody to report to, but swallowing the failure
+  must not swallow every later wake too: a coalescing flag stands for
+  a byte a failed write never sent, so the failure path disarms it.
+  The cost is then the wakes already in flight rather than every wake
+  after them. Never throw from a wake path.
+- A service's `shutdown()` is the same shape. Handing process-wide
+  state back (`sigaction`/`signal` restored to `SIG_DFL`) has no
+  channel and no caller left to act on one, so its result is
+  `std::ignore`d deliberately.
 - Never both channels for one operation. Never `std::error_code&`
   out-params. Never a throwing/non-throwing overload pair.
 
@@ -62,6 +72,17 @@ as `std::system_error` carrying the code the piecewise spelling
 returns); and root setup for which no code-returning spelling can
 exist (`io_context` backend creation, allocation).
 
+Root setup is everything the backend needs — completion port, ring,
+wakeup channel, thread pool — and all of it is built during
+construction, so a system that refuses any of it throws from the
+constructor instead of from the first operation, and the failed
+construction leaves nothing open. An initiator may then assume that
+infrastructure exists, which is what makes "initiators never throw"
+reachable at all. The one piece held back is the thread pool's
+workers, which start on the first blocking operation: a thread the
+system refuses there is reported through that operation's own channel,
+never thrown.
+
 ## 3. The Classification Test
 
 Ask: **can the caller reliably prevent the failure by checking state
@@ -125,6 +146,23 @@ second channel:
 - `tls_context` setters record configuration that is applied when a
   handshake first configures the engine; application failures surface
   through that handshake's completion.
+- A failure with no operation to attach to is latched on the object
+  and pre-answers the operations that follow, until the step it
+  belongs to succeeds again: a multishot arming the ring never took
+  reports to every accept until the next arming clears it.
+- A completion queued into a scheduler that spends a
+  `work_finished()` on everything it dispatches needs a matching
+  `work_started()`. An operation nothing counted reports through its
+  owner's channel instead of the completion queue.
+- Infrastructure an operation needs but does not own — the
+  blocking-I/O pool's worker threads, the wait reactor's polling
+  thread — is created on the first operation that needs it, and a
+  system that refuses it answers through that operation's completion.
+  The refusal is that operation's alone: the next one asks again. A
+  refusal the initiator learns of on its own thread, before any part of
+  the operation is cross-thread, completes there — the same exit the
+  closed-object and zero-length contracts take a few lines above it,
+  not a completion posted back through the scheduler.
 
 ## 6. Attributes and Spelling
 
@@ -139,8 +177,11 @@ second channel:
   functions with a `-DBOOST_COROSIO_DYN_LINK -DBOOST_COROSIO_SOURCE`
   syntax check.
 - Deliberate discards use `std::ignore = expr;`, never `(void)`
-  casts. Reserve them for calls whose outcome is asserted downstream
-  (hostile-input tests, best-effort bench teardown).
+  casts and never `[[maybe_unused]]` on a named result. Reserve them
+  for calls whose outcome is asserted downstream (hostile-input tests,
+  best-effort bench teardown), whose failure is impossible by
+  construction at that site, or which have no channel to report on at
+  all (§1's wake and `shutdown()` paths).
 - Unused names — parameters kept for signature clarity, structured
   bindings partially consumed, `#if`-gated uses — are declared
   `[[maybe_unused]]`, never silenced with a void cast.
@@ -157,14 +198,20 @@ second channel:
   `filename_too_long`,
   `already_connected` (`connect_pair` on an open socket),
   `no_such_device_or_address` (`corosio::connect` with no viable
-  candidate).
+  candidate),
+  `resource_unavailable_try_again` (io_uring submission queue
+  exhausted, for a submitted op, for the signal reader, and for a
+  multishot arming that never reached the kernel, latched on the
+  object until an arming succeeds; and a polling thread the system
+  would not start).
 - Portable comparison comes from **normalizing at the boundary**: the
   Windows `make_err` maps the contracted WSA/Win32 codes to
   generic-category `errc` values (`WSAEOPNOTSUPP`, `WSAENOTSOCK`,
   `WSAEAFNOSUPPORT`, `WSAEPROTOTYPE`, `WSAEADDRINUSE`,
-  `WSAEADDRNOTAVAIL`, `ERROR_NEGATIVE_SEEK`; `iocp_make_err` adds the
-  async condition set and `WSAEBADF`/`ERROR_INVALID_HANDLE`). On
-  POSIX, raw errno satisfies `errc` comparison with one exception:
+  `WSAEADDRNOTAVAIL`, `ERROR_NEGATIVE_SEEK`, `ERROR_MAX_THRDS_REACHED`;
+  `iocp_make_err` adds the async condition set and
+  `WSAEBADF`/`ERROR_INVALID_HANDLE`). On POSIX, raw errno satisfies
+  `errc` comparison with one exception:
   `make_err` normalizes `ENOTSUP` so platforms where it differs from
   `EOPNOTSUPP` still compare equal to
   `errc::operation_not_supported`.
@@ -175,10 +222,23 @@ second channel:
   AF_INET sockets; Darwin's `getsockopt(TCP_NODELAY)` on AF_UNIX);
   Windows reports `not_a_socket` where POSIX validation reports
   `EBADF` for garbage (non-sentinel) handles.
+- A failing call that leaves a zero last error must not become an
+  empty `error_code`: read the last error before anything that can
+  clobber it, and substitute rather than report success. Prefer a
+  contracted condition to a plausible-looking raw platform value,
+  which is indistinguishable from a code the provider really gave.
 - Conditions the standard cannot spell come from capy:
   `capy::cond::eof`, `capy::cond::canceled` (a stop token, not
   `errc::operation_canceled`), `capy::cond::timeout` (our deadline,
   not a kernel `ETIMEDOUT`).
+- A background thread that dies mid-flight owes one answer, not two:
+  the error that killed it, latched, both to the operations it was
+  holding and to the ones that arrive afterwards. `canceled` is a
+  stop token and belongs only to operations something cancelled — a
+  thread that never started is the same rule from the other end: the
+  operation that asked for it reports the code the system gave
+  (`resource_unavailable_try_again` where the refusal carries no code
+  of its own), never `canceled`.
 
 ## 8. Testing
 

doc/modules/ROOT/pages/4.guide/4c2.configuration.adoc

@@ -134,8 +134,12 @@ On POSIX platforms, file I/O (`stream_file`, `random_access_file`)
 and DNS resolution use a shared thread pool.
 
 * *Concurrent file operations*: increase to match expected
-  parallelism (e.g. 4 for four concurrent file reads).
-* *No file I/O*: leave at 1 (the pool is created lazily).
+  parallelism (e.g. 4 for four concurrent file reads).  The whole set
+  starts at once, on the first file or resolver call, so a larger pool
+  makes that one call more expensive and no other.
+* *No file I/O*: leave at 1; the pool is created with the context, but
+  its workers start on the first file or resolver operation, so a pool
+  nothing uses costs nothing.
 
 [#single-threaded-mode]
 === Locking Tiers (`locking`)