Examples

Complete, buildable programs -- each explained, with the software that inspired it, how it differs, and what libxtc made easy or hard.

---
  1. The server examples
  2. The teaching programs (01–04)
    1. 01_hello_async – the core contract
    2. 02_proc_pingpong – message passing
    3. 03_supervised_app – an OTP application
    4. 04_lockmgr_demo – deadlock detection
  3. Continuous batching
  4. Finding a lock convoy and a lost reply with probes
  5. Reading suggestion

The examples/ directory ships complete, buildable programs. The small ones isolate a single idea; the large ones are real servers modelled on well-known systems – Redis, SQLite, Kafka, Seastar/Tina, PostgreSQL – rebuilt on libxtc. Each server has its own page below covering the software that inspired it, how the libxtc version is similar and different, how it works, and the advantages and challenges of building it on libxtc. The standalone teaching examples (01–04, 10) are built and run by make check itself, and the larger systems (06 sqlxtc, 07 kaka, 11 lorb) are built and exercised by the CI examples job – so none of it rots. (08 tnt binds a fixed TCP port and is timing-fragile, so it is built but not run automatically; see its target comment in dist/Makefile.in.)

Build them against a configured tree:

cd build && make examples      # small ones -> ./01_hello, ./02_pingpong, ...
# the larger examples build in their own directories, e.g.
cd examples/05_rexis && make XTC_BUILD=../../build

The server examples

Example Modelled on What it shows
rexis Redis / Valkey A drop-in RESP server with hard resource budgets; connection-per-process.
sqlxtc SQLite A from-scratch SQL engine: parser, vectorized executor, B-link/buffer-pool/WAL storage.
kaka Apache Kafka / Redpanda A partitioned append-only log broker with credit-based backpressure.
tnt Seastar / Tina The stackless Isolate layer – the deliberate alternative to fibers.
pgmock PostgreSQL A mock PG backend proving the no-fork runtime seam, with zero PG source.

rexis vs DragonFly and Valkey compares rexis with a shard-per-thread server and a single-executor one, measured on the same host, and sketches the shard-per-loop shape on libxtc.

The teaching programs (01–04)

These four are small and map directly onto the Guide chapters; read them side by side.

01_hello_async – the core contract

A ~30-line program that spawns one coroutine, yields once, and awaits the result. It exists to prove the async/await contract end to end and to be the first thing a newcomer reads. It is the basis of Getting started. Source: examples/01_hello_async.c.

02_proc_pingpong – message passing

Two processes bounce a counter back and forth. It shows that the xtc_send / xtc_recv surface is enough to build request/reply RPC, and it establishes the idiom of encoding the reply-to pid in the payload (libxtc deliberately does not attach an implicit sender – why). Source: examples/02_proc_pingpong.c.

03_supervised_app – an OTP application

An xtc_app with a root supervisor (one_for_all), two workers, and an external watcher that can request an orderly shutdown. It demonstrates that the supervisor stack composes: the app owns the loop, registry, and root supervisor; the supervisor owns children with a restart policy. This is the skeleton of a real service. Source: examples/03_supervised_app.c.

04_lockmgr_demo – deadlock detection

Two transactions deadlock on a heavyweight lock manager; the detector finds the circular wait and aborts the younger transaction. It is the counterpoint to the process model: when you do want shared, lock-ordered state, the lock manager provides it – with deadlock detection, which hand-rolled pthread_mutex ordering does not. Source: examples/04_lockmgr_demo.c.

Continuous batching

12_continuous_batching compares static cohorts with continuous refill using the same numerical vector kernel. Two groups share a loop with a heartbeat; the self-test checks exact results, bounded admission, cancellation, BLOCKED/resume, and late-short completion order under both scheduling policies. It requires --enable-sched-policy; in an enabled build, root make check and the CI sched-policy job run its self-test.

Finding a lock convoy and a lost reply with probes

examples/15_usdt/convoy.c is buggy on purpose. In convoy mode eight fibers sleep while holding one xtc_amutex; fixed does the same work with the sleep outside the lock; lostwake has a server that drops one reply in ten. Each mode exits 0 and differs only in how long it takes, which is the kind of bug a tracer finds and a debugger does not. The tracing guide runs tools/dtrace/xtc_lock_contention.d and xtc_park_latency.d against it. Source: examples/15_usdt/convoy.c.

Reading suggestion

Read 01–04 alongside the Guide – each maps to a chapter. Then read rexis for a complete, approachable server, and sqlxtc when you want to see libxtc under real storage-engine pressure.

Table of contents