Skip to content

Example Language fixtures

Tom Barber edited this page Oct 30, 2026 · 3 revisions

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.

Goal

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).

The program

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 (an always: 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: buggy with 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).

Prerequisites

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.

Steps (all run natively; none needs Hermit)

1. Build and run the C fixture

make -C examples/language-fixtures/c CC=clang
./examples/language-fixtures/c/build/clangO2/at-c buggy

Our 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).

2. Run the same in the other languages

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).

3. Run the native self-check

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:

  • fixed never fires and always ends at 4,000;
  • buggy fires 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 fixed mode really runs buggy, and must reject it.

We ran these on an Apple silicon Mac:

make -C examples/language-fixtures/c test CC=clang
c 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.

4. Under Hermit (Linux x86-64 only)

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 init

Add 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 = 20
hairspring test at-c-buggy --seed 1

Each 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.

A second Java fixture: a small service

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. fixed claims the key atomically first. wide is buggy with 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, buggy failed the property in 50 of 50 runs and fixed in 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.

What to look at

  • 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.

Cleanup

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).

Where the full write-up lives

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.

Clone this wiki locally