Repository navigation
Guest SDKs by Language
A guest SDK lets a program under test declare properties in its own source: things that must always hold, must hold at least once, must be reached, or must never be reached. The program reports once at exit, as HAIRSPRING_EVENT lines on standard error, and Hairspring reads them. It is optional: a program without an SDK is still run, and a non-zero exit status still counts as a failure. See Running-Your-Own-Software for where this fits.
All the SDKs speak the same protocol (the guest protocol) and offer the same five kinds of property:
| Kind | Fails a trial when | Run-level gap ("UNMET") when |
|---|---|---|
always |
any evaluation is false | never evaluated |
always_or_unreachable |
any evaluation is false | never |
sometimes |
never | never true in any trial |
reachable |
never | never hit in any trial |
unreachable |
hit at least once | never |
The command line and the server say "UNMET" for a run-level gap. The web UI, in builds made from the current source, says "Never reached".
Each evaluation can carry up to four integer witness values, kept from the first true and the first false evaluation.
Two things apply to every SDK.
- None of these SDKs is published to a package registry. You use them from a clone of the repository (or, for Go, a
go getof the repository'smainbranch). -
The status of a language under Hermit is separate from whether its SDK works. Every example on this page was compiled and run natively on a Mac, and each printed an
assertline showing the property was evaluated. That says the SDK works natively. It says nothing about running under Hermit, which is what the support matrix is about, and which needs Linux x86-64. The status shown with each language is copied exactly from the support matrix; "supported" means one configuration and no other (Ubuntu 24.04, one Xeon host, pinned Hermit build). See Limits-and-Honesty.
All the examples below use the same tiny program: two threads each do an unprotected read, add one, write. The property is that the counter ends at 2. The examples are racy on purpose; in a given native run the race may or may not lose an update.
Status: Supported: passed our acceptance test on one configuration (Ubuntu 24.04, one Xeon host, pinned Hermit build); not tested elsewhere.
Install. Build the static library and link it into your executable. Link statically: the SDK finds its catalogue through the executable's own section, and shared objects are not supported.
make -C sdks/c lib CC=clang # builds sdks/c/build/clangO2/libhairspring.a
cc -O1 -pthread -Isdks/c/include demo.c sdks/c/build/clangO2/libhairspring.a -o demo(We ran the build with an explicit BUILD= directory so as not to write into the checkout; the default output directory is build/<compiler><optimisation> as in the comment above.)
#include <pthread.h>
#include "hairspring.h"
static long counter;
static void *bump(void *arg) { long v = counter; counter = v + 1; return arg; }
int main(void) {
pthread_t a, b;
pthread_create(&a, 0, bump, 0);
pthread_create(&b, 0, bump, 0);
pthread_join(a, 0);
pthread_join(b, 0);
HS_ALWAYS(counter == 2, "app.counter_exact", "no update was lost", counter, 2);
return 0;
}The id and message must be string literals; ids are 1 to 128 bytes of [A-Za-z0-9._:/-]. The other macros are HS_ALWAYS_OR_UNREACHABLE, HS_SOMETIMES, HS_REACHABLE, HS_UNREACHABLE and HS_WORK. Docs: docs/c-sdk.md.
Status: Supported: passed our acceptance test on one configuration (Ubuntu 24.04, one Xeon host, pinned Hermit build); not tested elsewhere. The matrix notes: passed separately with clang++ and with g++.
Install. C++ uses the C SDK; the macros work from C++ (-std=gnu++11 or later). With g++ on x86-64 and aarch64 Linux the call sites are written with inline assembly (a change that is in review and may not be in the SDK you have yet), so an id, message or file name containing %, {, }, |, a double quote, a backslash or a control character is a compile error there. Text outside ASCII is accepted on every target, if it is valid UTF-8. Clang accepts all but the quote and backslash. Once the SDK includes that change, call sites inside templates are collected with both compilers. Tested with g++ 13.3 and clang++ 18 only; not run here under Hermit.
make -C sdks/c lib CC=clang
clang++ -std=c++17 -O1 -pthread -Isdks/c/include demo.cc sdks/c/build/clangO2/libhairspring.a -o demo#include <thread>
#include "hairspring.h"
static long counter;
int main() {
auto bump = [] { long v = counter; counter = v + 1; };
std::thread a(bump), b(bump);
a.join();
b.join();
HS_ALWAYS(counter == 2, "app.counter_exact", "no update was lost", counter, 2);
return 0;
}Compiler caution. With an SDK copy that does not yet have the inline-assembly change, g++ 13.3 does not collect call sites inside C++ function templates, and a file mixing a call site in an inline function with one in an ordinary function does not compile; the C SDK document then recommends clang for C++. With such a copy and g++, keep call sites in ordinary non-inline, non-template functions, as above. Docs: docs/c-sdk.md.
Status: Supported: passed our acceptance test on one configuration (Ubuntu 24.04, one Xeon host, pinned Hermit build); not tested elsewhere. The matrix notes that 3 of the 400 trials in the acceptance run (1 in the failing arm, 2 in the passing arm) gave no verdict and are not counted.
Install. A pure Go module with no dependencies outside the standard library; it needs Go 1.24 or newer.
go get does not work outside a module (go: go.mod file not found ... 'go get' is no longer supported outside a module), so make your project one first:
go mod init example.com/demo
go get github.com/spiculedata/hairspring/sdks/go@mainThe SDK is not tagged, so this pins a pseudo-version of the main branch; go mod tidy removes the // indirect comment go get leaves. Both steps and the program below were run in an empty directory on a Mac.
package main
import (
"os"
"sync"
"sync/atomic"
hs "github.com/spiculedata/hairspring/sdks/go"
)
var counterExact = hs.Always("app.counter_exact", "no update was lost")
func main() { os.Exit(hs.Main(run)) }
func run() int {
var counter atomic.Int64
var wg sync.WaitGroup
for i := 0; i < 2; i++ {
wg.Add(1)
go func() { defer wg.Done(); v := counter.Load(); counter.Store(v + 1) }()
}
wg.Wait()
counterExact.Check(counter.Load() == 2, hs.Vals{counter.Load(), 2})
return 0
}Declare each site once, before the workload starts, then call Check or Hit. Run the workload inside hs.Main and return your exit status from the function: os.Exit and a panic bypass the report. Goroutines are not threads, so the SDK sends no thread lines. Docs: sdks/go/README.md (there is no separate page under docs/).
Status: Supported: passed our acceptance test on one configuration (Ubuntu 24.04, one Xeon host, pinned Hermit build); not tested elsewhere.
Install. The crate is hairspring-sdk, has no dependencies, and is not published to a registry. Use a path dependency. The snippet below needs a package around it, so the complete Cargo.toml is:
[package]
name = "demo"
version = "0.1.0"
edition = "2021"
[dependencies]
hairspring-sdk = { path = "../hairspring/sdks/rust" }Put the program in src/main.rs and run cargo run. (Run on a Mac with this Cargo.toml. If your directory is inside another Cargo workspace, add an empty [workspace] table to keep it standalone.)
use hairspring_sdk::always;
use std::sync::atomic::{AtomicU64, Ordering};
use std::thread;
static COUNTER: AtomicU64 = AtomicU64::new(0);
fn bump() { let v = COUNTER.load(Ordering::SeqCst); COUNTER.store(v + 1, Ordering::SeqCst); }
fn main() {
let (a, b) = (thread::spawn(bump), thread::spawn(bump));
a.join().unwrap();
b.join().unwrap();
let total = COUNTER.load(Ordering::SeqCst);
always!(total == 2, "app.counter_exact", "no update was lost", total, 2);
}The macros are always!, always_or_unreachable!, sometimes!, reachable! and unreachable_point!. Ids and messages are checked at compile time. To run under Hermit you will want a static Linux build (the project's own fixture uses the x86_64-unknown-linux-musl target). A runnable example ships with the crate: cargo run -p hairspring-sdk --example quickstart. Docs: docs/rust-sdk.md.
Status: Not supported on this build: the probe program did not complete under Hermit.
The SDK works natively and its tests pass; the status is about running Python under Hermit. Read it as: do not expect a Python program to run as a process target on this build. It supports CPython 3.12 or newer on Linux and macOS and has no dependencies.
Install.
pip install ./sdks/python # or: PYTHONPATH=sdks/python/src python3 demo.pyThe pip install writes sdks/python/build/ and sdks/python/src/hairspring.egg-info/ into the clone. The repository ignores both, and you can delete them afterwards.
import threading
import hairspring as hs
counter = 0
def bump():
global counter
v = counter
counter = v + 1
threads = [threading.Thread(target=bump) for _ in range(2)]
for t in threads: t.start()
for t in threads: t.join()
hs.always(counter == 2, "app.counter_exact", "no update was lost", counter, 2)Two cautions from the SDK document. A site that never runs is invisible, not unmet, because Python cannot see a call site before it executes: call hs.declare(hs.Kind.REACHABLE, id, msg) once, at import time, for every site whose absence matters. And evaluations made in a forked child are silently lost; use the spawn or forkserver start method for workers that assert. Docs: docs/python-sdk.md.
Status: Supported on a Java-specific configuration: passed our acceptance test on one configuration (Ubuntu 24.04, one Xeon host, pinned Hermit build) with skid_margin = 35 (the other languages: 25), JVM flags -Xint -XX:+UseSerialGC -XX:ActiveProcessorCount=1 -XX:-UsePerfData -Xshare:auto, Temurin 21.0.12.1, and a reduced fixture (50 iterations per worker instead of 1,000); not tested elsewhere. The matrix notes: Trials take about 210 s as run (up to three at once; about 105 s alone); suited to nightly runs. Replaying a recorded run matched only from the same paths as the recording (JDK install, program jar and working directory). At skid_margin = 25 the probe program did not complete under Hermit.
The SDK is pure Java 21 with no dependencies (no agent, no JNI), on Linux and macOS.
Install.
make -C sdks/java jar # writes sdks/java/build/hairspring-sdk.jar
javac -cp sdks/java/build/hairspring-sdk.jar Demo.java
java -cp sdks/java/build/hairspring-sdk.jar:. Demoimport static hairspring.Hairspring.*;
public class Demo {
static long counter;
public static void main(String[] args) throws InterruptedException {
Runnable bump = () -> { long v = counter; counter = v + 1; };
Thread a = new Thread(bump), b = new Thread(bump);
a.start(); b.start();
a.join(); b.join();
always(counter == 2, "app.counter_exact", "no update was lost", counter, 2);
}
}The SDK starts when its class is first used; a program that never touches it reports nothing, not even a hello. As in Python, call declare(Kind.REACHABLE, id, msg) early for sites that might never run. Docs: docs/java-sdk.md.
Status: SDK and fixture available. Not supported on this build: the probe program did not complete under Hermit.
The SDK is managed C# for net10.0, using only the base class library. The document says plainly that everything in it was checked natively (Linux and macOS, no Hermit).
Install. Reference the project from yours, or build the assembly with make -C sdks/dotnet dll. The snippet below is a top-level program, so the complete demo.csproj is:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>
<ItemGroup>
<ProjectReference Include="../hairspring/sdks/dotnet/src/Hairspring.csproj" />
</ItemGroup>
</Project>Put the program in Program.cs and run dotnet run (run on a Mac with SDK 10.0.400). net10.0 is the SDK's own target framework, so yours must match; ImplicitUsings supplies the using System.Threading; the snippet relies on. You need a .NET 10 SDK; inside a clone of the repository the root global.json accepts 10.0.100 or any later 10.0 SDK, so an SDK such as 10.0.400 works. The Linux build record uses exactly 10.0.402.
using static Hairspring.Hs;
long counter = 0;
void Bump() { long v = counter; counter = v + 1; }
var a = new Thread(Bump);
var b = new Thread(Bump);
a.Start(); b.Start();
a.Join(); b.Join();
Always(counter == 2, "app.counter_exact", "no update was lost", [counter, 2]);Call Hs.Start() first thing in Main if the first use of the SDK could be on a thread the end of the process can cut off. Docs: docs/dotnet-sdk.md.
For any of the examples above, running the program natively prints the protocol on standard error. The line to look for is the assert line for your id:
HAIRSPRING_EVENT {"v":1,"kind":"assert","proc":"p1","id":"app.counter_exact","hits":1,"trues":1,"falses":0,"first_false":null,"first_true":{"thread":"t#1","ord":1,"vals":[2,2,0,0]}}
hits is how often the site was evaluated; trues and falses split them; vals are the witness values. (We removed the padding spaces the SDK writes inside numbers.) The race in these snippets is real but narrow. In our native runs on a Mac the property was false in 0 of 50 runs for each of C, C++, Rust, Python and Java and 0 of 20 for .NET; for Go it was false in the first run we tried and in 0 of 300 after that. So a plain native run will almost always pass: this is exactly the kind of bug that needs a scheduler that can steer threads, and also why a pass proves little.
If you see no HAIRSPRING_EVENT lines at all, the SDK did not start (Java, .NET), the program bypassed the report (os.Exit in Go), or HAIRSPRING_EVENTS=off is set in your environment.
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