Phenolphthalein is an experimental concurrency test runner that:
- can run fixed-input, fixed-threading C11 concurrency tests
- is reasonably agnostic as to how those tests are implemented, requiring some common stub code but nothing more
- is based on the model of a fairly heavyweight standalone test runner interfacing with separately compiled test code, rather than integrated test harnesses
While still quite new, inefficient, and rough against the edges, it has the following features:
- handles
SIGTERM
by returning partial results - run tests indefinitely (or until the test fails or passes)
- output in machine-readable JSON as well as traditional histograms
Phenolphthalein is written in Rust (with some C interfacing code) and licenced under the MIT licence.
You probably don't yet - it's early beta-grade software. But the intention is that it'll be useful when you want something like Litmus, but:
- you need to support things that aren't, or don't fit well in, Litmus tests
- you'd prefer most of the test running infrastructure concentrated in one program, rather than being duplicated into test binaries
- you can somehow compile/run Rust binaries but not OCaml ones
- you need some of the above exotic features phenolphthalein has
- you don't need native support for assembly, cross-compilation, Litmus test ingestion, etc.
Using either the example test given in main.c
or your own variant thereof, do
something like:
$ clang -dynamiclib -std=c11 -pedantic -O3 -o test.dylib test.c
$ cargo run --release [OPTIONS] test.dylib
phph
accepts several arguments:
These can also be set globally using a TOML config file: pass
--dump-config-path
instead of a test file to see where phph
is looking for
one, and --dump-config
to get the current config in the right format.
--iterations=N
: runN
many iterations in total (set to0
to disable iteration cap)--period=N
: join and re-create threads everyN
iterations (set to0
to disable thread rotation)--check=TYPE
: control how phenolphthalein checks states against the test's postcondition:disable
checks entirely;report
the check outcomes per state; orexit-on-pass
,exit-on-fail
, orexit-on-unknown
to abort the test when a particular outcome arrives--permute=TYPE
: control the order in which phenolphthalein launches threads: eitherstatic
orrandom
--sync=TYPE
: synchronise threads with a spinlock (spinner
, default) or a full Rust barrier (barrier
);spinner
is faster and tends to show more weak behaviour, butbarrier
is perhaps 'safer'
--output-type=TYPE
: control the output format, with possibilities being a litmus7-stylehistogram
, or a semi-machine-readablejson
serialisation
All contributions are welcome! Check the GitHub issues page for specific things that need work. General areas of development include:
- feature parity with litmus7 (though we don't intend to support every litmus7 feature, given the different focus for phenolphthalein);
- speed of test turnaround (likely taking hints from litmus7);
- ability to discover weak behaviours (likely also taking hints from litmus7);
- reducing test boilerplate, to make it straightforward to write hand-written tests against phenolphthalein;
- supporting boilerplate and ABIs for more languages (C++, Rust, Go?)
Similar purpose to Litmus, but different execution. Also, the incredibly long and difficult to spell name is a conscious effort to suggest to the potential user that they should probably be using Litmus instead.