Runnable companions to the compendium.
Every claim made in the compendium has a demo behind it.
Each demo is a self-contained Docker project with its own
./demo.sh, its own Containerfile(s), and the
CMake / Conan plumbing to build hermetically. Read the
matching compendium chapter for context, then run the demo
from its directory.
Runnable examples
Runnable companions to the statelessness compendium. Each one makes a single pattern from the compendium concrete and runnable with one command. Each card links to the demo's page on this site (a rendering of the README with cross-references), and each page links to the source on GitHub. Each demo also stands alone — run it without reading the compendium first if you'd rather poke at it directly.
RequestContext RAII
A gRPC handler builds a RequestContext on entry and takes one of three exit paths — normal return, early return, and throw — proving the destructor fires on all three. RAII cleanup made visible.
PMR request arena
The layered monotonic + pool arena, per-request allocation freed in bulk, the release-cost asymmetry, and the lifetime trap caught live by AddressSanitizer.
Process-scoped state
The composition root in main(), dependency injection by reference, a bounded LRU cache sized against the cgroup budget, and correct reverse-order teardown from RAII.
Threading & CPU budget
hardware_concurrency() lies under a cgroup quota. A cgroup-aware probe and a pool-size sweep under --cpus=2 show oversubscription buys no throughput and wrecks tail latency via CFS throttling.
State externalization
Authoritative order state in PostgreSQL: a hand-rolled connection pool with ScopedConnection RAII checkout, DB-authoritative idempotency via ON CONFLICT, and gRPC deadline propagation to the database.
Outbox pattern
Atomic DB write plus event emission: an order and its event written in one transaction, a relay that publishes the outbox to Kafka with FOR UPDATE SKIP LOCKED, and an idempotent consumer — at-least-once delivery plus idempotent apply gives an exactly-once effect.
Ephemeral filesystem
The read-only rootfs as a forcing function: spdlog's basic_logger_mt EROFS trap and the stdout-sink fix, ephemerality across restarts, and why scratch belongs on an explicitly-mounted tmpfs.
Health checks
The three probes (startup, liveness, readiness) via the gRPC standard health protocol: HTTP liveness on a separate port, gRPC readiness, a SIGUSR1 readiness toggle, and the signal-safe graceful-shutdown sequence to a clean exit.
gRPC microservices (end-to-end example)
The integration example: an order-pricing service composing every prior pattern — Config, process-scoped pools and a channel cache, a per-request PMR arena, deadline-propagated PostgreSQL and an outbound gRPC tax call, idempotency, and the staged health/shutdown sequence.
Build tooling (vendored helpers)
The vendored helpers made runnable: cgroup_helper + psi_reader as static libs, a GoogleTest suite over their pure parsers, and a binary swept under --cpus/--memory caps so cpu_limit_cores() is shown tracking the cgroup while hardware_concurrency() does not.
Running every demo
Clone the repo and invoke each demo.sh from its
directory. The scripts assume Docker and a
handful of host tools (hey, jq,
curl).
git clone https://github.com/patterncatalyst/cpp-statelessness.git
cd cpp-statelessness/examples/statelessness/02-raii
./demo.sh
# ... or run every example in sequence:
cd cpp-statelessness
./scripts/test-all-stateless-demos.sh
If a demo fails
Most failures are kernel-feature gaps (io_uring
multishot needs ≥ 5.19) or rootless cgroup limits. The
reconciliation plan
tracks every demo's verification state per host class. If
your host isn't covered, an entry there is the right
contribution.