Repository navigation
Example Language fixtures
One small program, written once per language, with a planted lost-update race. Each version reports through its language's guest SDK. They exist to check that a language's runtime, its SDK and the process backend work together. They are test subjects, not examples of good concurrent code.
Files: examples/language-fixtures (C, C++, Go, Python, Java, .NET) and sdks/rust/fixtures (Rust). Full contract: the README in that directory. Language status: the support matrix, summarised on Running-Your-Own-Software.
Build the fixture in a language you use, run it natively in its three modes, read the SDK's report, and understand what the language's status under Hermit means (and does not mean).
Every language follows one contract:
- Four workers each do 1,000 times: read a shared counter, run a busy loop (the window), write back the value read plus one. The read and the write are separate atomic operations, so there is no data race in the language's memory model, but two workers can read the same value and an update is lost.
- A start barrier makes the four windows overlap from the first iteration.
- The final value should be 4,000. The property is
<lang>.counter_exact(analways: the final counter equals 4,000), with the witness values[final, 4000, 4, 1000]. A second property,<lang>.all_started, is a coverage marker. - One program takes its mode as its only argument:
-
buggy: the planted race, no lock. -
fixed: the same program with a mutex held across the read-modify-write. It cannot lose an update. -
wide:buggywith a busy loop ten times longer. Nothing else differs.
-
- It prints exactly one line on standard output:
LANGAT v1 lang=<id> mode=<mode> final=<20 digits> expect=<20 digits> order=<16 hex> rand=<16 hex>. It exits 0 whatever the property says: the verdict is the SDK's report, not the exit status. Exit 3 is an internal failure, 64 a usage error (and then nothing is printed on stdout).
| Language | Build with | Needs |
|---|---|---|
| C |
make -C examples/language-fixtures/c CC=clang (or gcc) |
a C compiler |
| C++ | make -C examples/language-fixtures/cpp CXX=clang++ |
clang++ (the project recommends it) or g++ |
| Go | make -C examples/language-fixtures/go |
Go 1.24 or newer |
| Rust | cargo run --release -p hairspring-sdk --bin at-rust -- buggy |
a Rust toolchain |
| Python | nothing to build: python3 examples/language-fixtures/python/at_py.py buggy
|
CPython 3.12 or newer |
| Java | make -C examples/language-fixtures/java at-jar |
a JDK 21 |
| .NET | make -C examples/language-fixtures/dotnet at-build |
the .NET 10 SDK; its own checks also want a pinned runtime |
Under Hermit: Linux x86-64 plus everything in Installation. To avoid writing into your clone, copy examples/ and sdks/ somewhere else first, as we did.
make -C examples/language-fixtures/c CC=clang
./examples/language-fixtures/c/build/clangO2/at-c buggyOur output (stdout line, then the exit status):
LANGAT v1 lang=c mode=buggy final=00000000000000001016 expect=00000000000000004000 order=630d370242506f87 rand=37e5c1e81ad51ea3
Exit status 0. The counter ended at 1,016, not 4,000: about three quarters of the updates were lost. The rand= field comes from the system's entropy source, so it differs every run; the program carries it so that any entropy leaking into output is visible.
Now the report, on standard error:
./examples/language-fixtures/c/build/clangO2/at-c buggy 2>&1 >/dev/null | grep '"assert"'HAIRSPRING_EVENT {"v":1,"kind":"assert","proc":"p1","id":"c.counter_exact","hits":1,"trues":0,"falses":1,"first_false":{"thread":"t#5","ord":1,"vals":[1016,4000,4,1000]},"first_true":null}
HAIRSPRING_EVENT {"v":1,"kind":"assert","proc":"p1","id":"c.all_started","hits":1,"trues":1,"falses":0,"first_false":null,"first_true":{"thread":"t#5","ord":1,"vals":[4,0,0,0]}}
(Padding spaces inside the numbers are removed here.) The property c.counter_exact was evaluated once and was false; the witness values say the final value was 1,016 against an expected 4,000. fixed gives final=...4000 and a true property; wide lost most of the updates too (final=1000 in our run).
| Language | Command | What we saw in one buggy run |
|---|---|---|
| Go | ./go/build/at-go buggy |
final=...1061 |
| Rust | cargo run -q --release -p hairspring-sdk --bin at-rust -- buggy |
final=...1002 |
| Python | python3 python/at_py.py buggy |
final=...1178 |
| Java | java -jar java/build/at/*.jar buggy |
final=...1055 |
The exact number varies from run to run and from machine to machine. The fixtures document says explicitly that the native rates should not be compared across languages: the programs are not instruction-for-instruction equivalent (Go's atomics, for instance, are sequentially consistent).
Each language has a make test that builds the artifact, checks the sources do not read the seed, /proc, the CPU count or the clock, checks the argument handling (no argument, an unknown mode, a spare argument: exit 64, nothing on stdout), and runs the modes many times, requiring that:
-
fixednever fires and always ends at 4,000; -
buggyfires at least once; - the detector and the program agree on every run (the property is false exactly when the final value is not 4,000);
- and that the check itself can fail: it is run again on a stand-in whose
fixedmode really runsbuggy, and must reject it.
We ran these on an Apple silicon Mac:
make -C examples/language-fixtures/c test CC=clangc buggy: property false in 50 of 50 native runs
c fixed: property false in 0 of 50 native runs, final exact in 50
c wide: property false in 10 of 10 native runs
ok the self-check rejects a fixed mode that is really the buggy one
C++ with clang++ gave the same shape (cxx buggy: ... 50 of 50, fixed ... 0 of 50). Go, run with make -C go test, gave 50 of 50, 0 of 50 and 10 of 10, with one skip: line about closing stdout (this machine has no /dev/full). The Python check took nearly six minutes and printed:
py buggy: property false in 50 of 50 native runs, final exact in 0; final min/median/max 1000/1127/1346
py fixed: property false in 0 of 50 native runs, final exact in 50; final min/median/max 4000/4000/4000
py wide: property false in 50 of 50 native runs, final exact in 0; final min/median/max 993/1008.5/1075
py buggy --switch=1.0 (informational): property false in 0 of 50 native runs, final exact in 50; final min/median/max 4000/4000/4000
The last line is a Python detail worth knowing: CPython's interpreter lock hands over every few milliseconds inside the busy loop, and setting the thread switch interval to 1.0 s (--switch=1.0) removes the race. The Java check (make -C java at-test) also ran and reported, for its second flag profile, that buggy lost an update in 5 of 5 runs.
These are native counts on one machine. They show the race exists and that the detector can see it. They say nothing about how any scheduler behaves and are not rates for any other setting.
We did not run the .NET fixture's checks. The .NET fixture's own README says it has not been run under Hermit.
This step is copied from docs/quickstart.md. We could not run it here. at-c takes its mode as the only argument.
make -C examples/language-fixtures/c CC=gcc # builds build/gccO2/at-c
mkdir -p /tmp/hs-demo && cd /tmp/hs-demo
hairspring initAdd the target to hairspring.toml, with the absolute path of the program you built:
[target.at-c-buggy]
kind = "process"
command = ["/path/to/hairspring/examples/language-fixtures/c/build/gccO2/at-c", "buggy"]
trial_timeout_secs = 120
[target.at-c-buggy.budget]
max_trials = 20hairspring test at-c-buggy --seed 1Each trial runs the program under Hermit with a different scheduler seed. The program always exits 0; the verdict comes from the property reported through the SDK. A trial that does not finish within trial_timeout_secs is reported as inconclusive, never as a pass. A small budget may or may not hit the race, so a pass with a small budget says only that those seeds did not fail. Raise max_trials, or run fixed for comparison. Replay a bundle with hairspring replay .hairspring/bundles/<bundle>.hairspring.
Alongside the bare race, examples/language-fixtures/java/svc holds a Java program shaped more like a small service (svc.jar, class langsvc.Main, the Java SDK built in). It takes the same arguments as the Java fixture (buggy, fixed, wide and --k=N, default 1,000) and prints the same final line.
- What it does. Four client threads each send K transfers. Every transfer is sent twice, and a client that times out sends another copy with a longer deadline. A pool of three worker threads applies the copies to a small in-memory ledger behind a lock, with an idempotency table that should make a repeated transfer harmless. A timer thread samples the queue depth. Request deadlines read the monotonic clock in one file only.
-
The planted bug. In
buggy, the idempotency check and the write of the key are separate steps, so two copies handled at the same moment can both be applied and the total ends above 4 x K.fixedclaims the key atomically first.wideisbuggywith a ten times longer gap. -
The property is
java.counter_exact: the ledger applied exactly 4 x K transfers. -
Try it natively (needs a JDK 21; run from
examples/language-fixtures):make -C java svc-test. On our Mac it took about a minute and a half. With the default flags and with the second flag profile,buggyfailed the property in 50 of 50 runs andfixedin 0 of 50. - What it is not. There is no network, file or database traffic, the bug is planted and known in advance, and the property is still a count equality. Running it under Hermit needs Linux x86-64; that was not run here, and it is not a statement about how Java behaves under Hermit.
- The status of each language is in the support matrix: C, C++, Go and Rust are "Supported: passed our acceptance test on one configuration (Ubuntu 24.04, one Xeon host, pinned Hermit build); not tested elsewhere."; Java is supported only on a Java-specific configuration (see Guest-SDKs-by-Language); Python and .NET are "Not supported on this build: the probe program did not complete under Hermit." That is a statement about running those runtimes under Hermit, not about the SDKs, which work natively.
- Compilers. For C++, clang++ is the recommended compiler; g++ builds and reports too because every SDK call in the fixture is in an ordinary function, not in a template or other inline function.
-
Why
exit 0. The verdict is the report, so a harness can tell a property failure from a crash.
If you built inside a copy, delete the copy. If you built inside your clone, make -C examples/language-fixtures/<lang> clean removes the build output for c, cpp, go, java and dotnet (each has a clean target; Python has nothing to build).
examples/language-fixtures/README.md (the contract, the build records, the probes), and the per-language SDK documents listed on Guest-SDKs-by-Language. Next: Examples-Overview.
Understand
- What-is-Hairspring
- Concepts-and-Vocabulary
- How-Deterministic-Simulation-Works
- Sweeps-and-Confirmation
- Limits-and-Honesty
Use
- Installation
- Your-First-Run
- Running-Your-Own-Software
- Guest-SDKs-by-Language
- Examples-Overview
- Hairspring-in-CI
- Operate-a-Server
- Upgrading-and-Versions
- Troubleshooting
Reference