Examples for TestFlows Machine

Programs that hold a concurrency bug with a known shape, two stress
programs, a hello world, and Compose projects, published under
Apache 2.0.

- hello/hello-world.c: the smallest disk that boots and runs a program.
- races/, starvation/, stress/: the programs. Plans in their comments use
  the syntax at testflows.com/docs/machine/steering-programs.md and name
  /examples/<name>, the path in the testflows/machine-examples image.
- compose/: two-services, clickhouse and clickhouse-regression. The
  regression suite is used at a pinned commit of its main, with
  prepare-env.patch, Altinity PR 170, applied.
- make builds every program static and x86_64 into bin/; make check proves
  it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BJu3r5JhoqtUHitojYU7xh

Author: vzakaznikov

.gitignore

@@ -0,0 +1,2 @@
+bin/
+.*.swp

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2026 Katteli Inc.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

Makefile

@@ -0,0 +1,63 @@
+# Builds every example program as a static x86_64 binary in bin/, which is what
+# `machine disks build --binary` takes, and what the testflows/machine-examples
+# image carries.
+#
+# Copyright 2026 Katteli Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+CC = gcc
+# -static because `--binary` refuses anything asking for an interpreter: the
+# image it writes has no loader and no libraries. -pthread because most of
+# these programs are about what threads do to each other.
+CFLAGS = -O2 -static -pthread
+
+# One directory per kind of example. compose/ holds projects, not programs.
+GROUPS = hello races starvation stress
+
+SOURCES = $(wildcard $(addsuffix /*.c,$(GROUPS)))
+BINARIES = $(patsubst %.c,bin/%,$(notdir $(SOURCES)))
+
+.PHONY: all clean check list
+
+all: $(BINARIES)
+	@echo "Built: $(BINARIES)"
+
+# One rule per group, because the sources are in several directories and the
+# binaries land in one.
+define build_group
+bin/%: $(1)/%.c | bin
+	$$(CC) $$(CFLAGS) $$< -o $$@
+endef
+$(foreach group,$(GROUPS),$(eval $(call build_group,$(group))))
+
+bin:
+	mkdir -p bin
+
+# What `--binary` checks before it packs anything, asked here so a binary that
+# would be refused is caught by the build that made it rather than by the
+# upload that carries it.
+check: all
+	@for b in $(BINARIES); do \
+	  file -b "$$b" | grep -q "statically linked" \
+	    || { echo "$$b: not static"; exit 1; }; \
+	  file -b "$$b" | grep -q "x86-64" \
+	    || { echo "$$b: not x86_64"; exit 1; }; \
+	  echo "$$b: static x86_64"; \
+	done
+
+list:
+	@echo $(SOURCES) | tr ' ' '\n'
+
+clean:
+	rm -rf bin

README.md

@@ -0,0 +1,102 @@
+# TestFlows Machine Examples
+
+Programs and Compose projects to run on [TestFlows Machine](https://testflows.com/machine/).
+
+## ✨ Getting Started
+
+```bash
+git clone https://github.com/testflows/Machine-Examples.git
+cd Machine-Examples
+```
+
+## 🧪 Programs
+
+The programs are small and written to be run many times. Most hold a
+concurrency bug with a known shape, and what they print depends on how their
+threads interleaved, which is the thing a machine decides, records and can
+replay. The two in `stress/` hold no bug at all: they drive the kernel hard
+enough that a replay either matches or does not.
+
+| Example | What it does | The bug |
+|---|---|---|
+| [hello/hello-world.c](hello/hello-world.c) | Prints a greeting and the kernel it runs on | None. The smallest disk that boots and runs a program |
+| [races/data-race.c](races/data-race.c) | N threads increment one shared counter with no lock | Lost update. The read-add-write is three steps and another thread lands between two of them, so the total comes out short |
+| [starvation/timeout-starve.c](starvation/timeout-starve.c) | Main arms a timeout and waits; the worker must publish before it fires | The worker is starved for the whole wait and the timeout expires with nothing published. It is the ONLY runnable thread while main sleeps, so no pick-next policy finds this |
+| [starvation/pipe-wakeup.c](starvation/pipe-wakeup.c) | A reader blocks on a pipe, main writes one byte then waits | The reader is starved after becoming runnable and misses the timeout. Both threads are runnable after the write, so a scheduler can pick the reader |
+| [starvation/futex-wakeup.c](starvation/futex-wakeup.c) | A waiter blocks on a locked mutex, main unlocks then waits | The waiter is starved after the unlock. Same shape as pipe-wakeup with a futex instead of a pipe |
+| [starvation/narrow-window.c](starvation/narrow-window.c) | A producer raises a flag for a few iterations, then lowers it for a long gap | The consumer is starved through every window and never sees the flag up. Needs frequent short delays, not long ones |
+| [starvation/missed-wakeup.c](starvation/missed-wakeup.c) | A waiter checks a predicate, then waits on it, with no loop around the check | Missed wakeup. Held between the check and the wait, the signaler signals into nobody and the waiter sleeps through it. The timeout expires with the predicate already true |
+| [starvation/lease.c](starvation/lease.c) | Main waits on a lease long enough for the worker's fixed work | The lease expires before the worker publishes. Nobody is starved: virtual time jumps while the work is still running, so the timer fires early |
+| [stress/memstress.c](stress/memstress.c) | Allocates close to the VM's memory limit across threads, with madvise, fork/COW and fault cycles | Not a bug of its own. It drives the kernel's memory management hard, which is the work a replay has to reproduce exactly |
+| [stress/memswapstress.c](stress/memswapstress.c) | Allocates 150% of RAM against a swap file, forcing swap-out, swap-in and swap cache | Not a bug of its own. Same purpose one layer down, through swap |
+
+## 🚀 Run One From the Image
+
+Every program is in one image, `testflows/machine-examples`, at
+`/examples/<name>`. Pull it, then build a disk with `--entrypoint` naming the
+program; arguments go after `--`. A machine is x86_64, so ask for
+`linux/amd64` even on an ARM computer:
+
+```bash
+docker pull --platform linux/amd64 testflows/machine-examples
+machine disks build --image testflows/machine-examples --entrypoint /examples/hello-world hello
+machine disks build --image testflows/machine-examples --entrypoint /examples/data-race race -- 8
+machine create --disk race
+```
+
+Each program's arguments and defaults are at the top of its source.
+
+## 🔨 Build Them Yourself
+
+`make` compiles every program static and x86_64, which is what a disk built
+from a binary requires:
+
+```bash
+make            # every program, into bin/
+make check      # and prove each one is static x86_64
+make list       # what would be built
+```
+
+```bash
+machine disks build --binary bin/data-race race -- 8
+machine create --disk race
+```
+
+## 🐳 Compose Environments
+
+`compose/` holds whole environments rather than programs: a docker compose
+project that `machine disks build --compose` turns into a disk. The machine
+runs the project with `--abort-on-container-exit`, so it ends when a service
+exits.
+
+| Environment | What it does | What it shows |
+|---|---|---|
+| [compose/two-services](compose/two-services/docker-compose.yml) | A busybox server and a client that fetches from it by service name | Services reach each other by name, over the network Docker gives the project, the same as on any host |
+| [compose/clickhouse](compose/clickhouse/docker-compose.yml) | A ClickHouse server and a client that queries it | A real database server in a machine. `config.xml` replaces the image's: IPv4 only, because the machine's kernel has no IPv6, and every background pool capped, because the defaults hang startup in a small VM without an error |
+| [compose/clickhouse-regression](compose/clickhouse-regression/README.md) | Altinity's ClickHouse regression suite, which brings up its own Compose project inside the machine | A test suite that drives Docker Compose itself. The runner binds the machine's Docker socket, the sources sit at one path both sides of it agree on, and `scale: 0` carries the images the suite starts but no service here names |
+
+```
+machine disks build --compose compose/clickhouse ch
+machine create --disk ch
+```
+
+Each project is also runnable on the host, which is how to fix one without
+waiting for a boot:
+
+```
+cd compose/clickhouse && docker compose up --abort-on-container-exit
+```
+
+## 📚 Learn More
+
+- 🌐 **Website:** [testflows.com/machine](https://testflows.com/machine/)
+- 📖 **Documentation:** [testflows.com/docs/machine](https://testflows.com/docs/machine/)
+- ⬇️ **Download:** [testflows.com/machine/download](https://testflows.com/machine/download/)
+
+## 📜 License
+
+Apache 2.0; see [LICENSE](LICENSE).
+
+---
+
+Learn to write test programs, not just tests 👽

compose/clickhouse-regression/.gitignore

@@ -0,0 +1,2 @@
+# The suite is someone else's code, copied in and never tracked.
+suite/

compose/clickhouse-regression/README.md

@@ -0,0 +1,105 @@
+# clickhouse-regression
+
+Altinity's [ClickHouse regression suite](https://github.com/Altinity/clickhouse-regression)
+in a machine. It is a test suite that drives Docker Compose itself:
+`regression.py` brings up its own project inside the machine, runs its tests
+against it and tears it down. So the disk holds two projects: this one, which
+the machine starts at boot, and the suite's, which the suite starts.
+
+Only this project is here. The suite is copied into `suite/`, which
+`.gitignore` keeps untracked.
+
+## 📦 1. The Sources
+
+The suite is used at a pinned commit of its `main`, with
+[prepare-env.patch](prepare-env.patch) applied. The patch is Altinity
+[PR 170](https://github.com/Altinity/clickhouse-regression/pull/170), which
+adds `--prepare-env`; when it is merged, the patch goes.
+
+```bash
+cd compose/clickhouse-regression
+git clone https://github.com/Altinity/clickhouse-regression.git /tmp/clickhouse-regression
+git -C /tmp/clickhouse-regression checkout 5f7decbac4a3896931be5cfe1882ab1ad1e72fab
+git -C /tmp/clickhouse-regression apply "$PWD/prepare-env.patch"
+mkdir -p suite
+cp -a /tmp/clickhouse-regression/helpers \
+      /tmp/clickhouse-regression/docker-compose \
+      /tmp/clickhouse-regression/requirements.txt \
+      /tmp/clickhouse-regression/example \
+      suite/
+```
+
+Four entries, not the repository: `disks build` packs the whole project
+directory, and that repository is 2.1GB of tracked files. A suite needs
+`helpers/`, the shared `docker-compose/`, `requirements.txt` and its own
+directory, which is about 1MB. `helpers` has to stay a sibling of the suite,
+because `regression.py` finds it at `..`.
+
+## 🐳 2. The Runner Image
+
+```bash
+docker build -t regression-runner:local runner/
+```
+
+## 🗂️ 3. The Images the Suite Starts
+
+A machine reaches no registry, so everything the suite will run has to be in
+the local Docker under the names it asks for. `--prepare-env` builds and pulls
+them and runs no tests:
+
+```bash
+docker run --rm \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  -v "$PWD/suite:$PWD/suite" -w "$PWD/suite" \
+  regression-runner:local \
+  python3 example/regression.py \
+    --clickhouse docker://clickhouse/clickhouse-server:24.8.14.39-alpine \
+    --prepare-env
+```
+
+The `carried_*` services in `docker-compose.yml` name those images so the build
+packs them. They never start.
+
+## 💾 4. The Disk
+
+```bash
+machine disks build --compose . chreg --dry-run
+machine disks build --compose . chreg --size 6144
+machine sessions create --cpus 6 --mem 24G
+machine create --disk chreg --mem 8192 --cpus 2 --daemon
+until machine --timeout 0 wait <run> --for halted; do
+    machine run <run> --iters 200000000 --mode free
+done
+machine console <run> -f
+```
+
+`--dry-run` reports what the disk holds and builds nothing:
+
+```
+content
+  rootfs           285MB
+  images (tar)     422MB
+  images (loaded)  896MB
+  project          1MB
+size
+  used             1604MB
+  capacity         3072MB
+```
+
+Leaving `--size` out takes `used` plus a gigabyte, rounded up to a whole GB; a
+smaller `--size` is refused before anything uploads. The 6144 here is for what
+the suite itself writes, which no footprint predicts: it copies the 600MB
+clickhouse binary out of its own container.
+
+The 8192MB machine needs a session with at least 24GB. `run` returns several
+times while the machine boots, so the loop keeps it running until the machine
+halts. The machine runs the project with `--abort-on-container-exit`, so it
+powers off when the suite exits and the run lands in `halted`.
+
+## ➕ Another Suite
+
+Copy that suite's directory into `suite/` as well and change `command:`. A
+suite whose environment names the same two images needs nothing else; one that
+starts ZooKeeper, Keeper or MinIO needs another `carried_*` entry and more
+memory. Run it on your own computer first: a suite that fails there fails in a
+machine for the same reason.

compose/clickhouse-regression/docker-compose.yml

@@ -0,0 +1,44 @@
+# Copyright 2026 Katteli Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# A test suite that drives docker compose ITSELF. `regression.py` brings up its
+# own project inside the guest, so the runner needs this machine's docker, and
+# the sources at the SAME path the daemon sees: compose resolves a bind source
+# on the daemon's filesystem, not in the container that asked for it.
+services:
+  regression:
+    image: regression-runner:local
+    working_dir: /opt/compose
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - ./:/opt/compose
+    command:
+      - python3
+      - suite/example/regression.py
+      - --clickhouse
+      - docker://clickhouse/clickhouse-server:24.8.14.39-alpine
+
+  # Carried, never started. The images the suite starts are named by no service
+  # here, so `scale: 0` is how they reach the disk: the build packs every image
+  # the project names, and compose starts none of these. Another suite that
+  # needs ZooKeeper or MinIO adds another entry.
+  carried_prepared:
+    image: clickhouse-regression/clickhouse/clickhouse-server:24.8.14.39-alpine
+    scale: 0
+  carried_server:
+    image: clickhouse/clickhouse-server:24.8.14.39-alpine
+    scale: 0
+  carried_ready:
+    image: hello-world:latest
+    scale: 0