Runnable companions to the tutorial.
Every claim made in the tutorial body has a demo behind it.
Each demo is a self-contained Podman project with its own
./demo.sh, its own Containerfile(s), and the
CMake / Conan plumbing to build hermetically. Read the
matching tutorial section for context, then run the demo
from its directory.
Demos
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 tutorial first if you'd rather poke at it directly.
Image strategy & PGO
UBI multi-stage vs UBI-micro vs single-stage-naive, plus a two-pass PGO build. hey drives load against each variant; the demo prints a p50/p95/p99 table side by side.
STL & layout
unordered_map vs map vs flat_map vs vector with a linear scan; Google Benchmark median timings under a baseline and a 128 MB cgroup memory cap, side-by-side.
io_uring & async gRPC
Direct liburing, an Asio io_uring executor, and an async gRPC server — three servers in one binary. Wired into the LGTM observability stack; ghz drives load and the demo writes results to disk.
Observability stack
A C++ HTTP service instrumented with OpenTelemetry grafana/otel-lgtm. Optional bpftrace probes add the kernel-side dimension above the application telemetry.
Noisy neighbor isolation
Twin-tenant scenario: a latency-sensitive HTTP service next to a CPU/memory-bound noisy neighbor. Compares baseline, unisolated, cpu.weight, and cpuset.cpus pinning.
Memory & allocators
Side-by-side latency comparison of std::allocator, std::pmr::synchronized_pool_resource, and mimalloc on an allocator-stressful workload. Layered with MAP_HUGETLB and cgroup memory.high pressure. OTel-instrumented; histograms reach the LGTM stack.
Quality & ABI pipeline
cppcheck and clang-tidy as build stages, gtest+gmock suite, abidiff against a checked-in ABI reference, plus a gdbserver sidecar for live debugging. Hermetic Conan 2 lockfile + CMake presets throughout.
Compendium examples
Runnable companions to the
statelessness compendium.
Each one makes a single pattern from the compendium concrete
and runnable; they share the main demos' one-command
./demo.sh shape.
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 for free 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 (capstone)
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 Podman 5.x rootless and a
handful of host tools (hey, jq,
curl) — see §1
Prerequisites for the full list.
git clone https://github.com/patterncatalyst/cpp-container-optimization-tutorial.git
cd cpp-container-optimization-tutorial/examples/demo-01-image-strategy
./demo.sh
# ... or run them all in sequence:
cd cpp-container-optimization-tutorial
./scripts/test-all-demos.sh
# ... or just the statelessness compendium examples:
./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.