Code Tools: jcstress

The Java Concurrency Stress tests (jcstress) is an experimental harness and a suite of tests to aid the research in the correctness of concurrency support in the JVM, class libraries, and hardware.

Quick start

You should have Mercurial and Maven installed to check out and build the tests. You will need JDK 8 to compile all the tests. Most tests are runnable on JDK 6+ afterwards.

  1. Check out the jcstress source:
    $ hg clone jcstress
    $ cd jcstress/         
  2. Build jcstress. Since jcstress is a large project, you may want to build only the minimal subset of it:
    $ mvn clean install -pl tests-custom -am
    $ java -jar tests-custom/target/jcstress.jar

Run the JAR with -h to get the help.


Understanding the tests and Interpreting the results

The tests are similar to what Litmus tests look like, where few threads are executing the test concurrently, sometimes rendez-vous'ing over the shared state. There are multiple state objects generated per each run. Threads then either mutate or observe that state object. Test harness is collecting statistics on the observed states. In many cases this is enough to catch the reorderings or contract violations for concurrent code.

The console output can be used to track progress and debugging. Ordinary users should use generated HTML report, which has the full interpretation of the results.

Developing tests

Please consider contributing the interesting tests back. We follow the OpenJDK policy on contributions.

If you want to develop a test, you are encouraged to get familiar with existing set of tests first. You will have to have a class annotated with jcstress annotations, see the harness API. Read up their Javadocs to understand the conditions that are guaranteed for those tests. If you need some other test interface/harness support, please don't hesitate to raise the issue and describe the scenario you want to test.

You are encouraged to provide the thorough explanation why particular test outcome is acceptable/forbidden/special. Even though harness will print the debug output into the console if no description is given.

Project layout