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,
- Check out the jcstress source:
$ hg clone http://hg.openjdk.java.net/code-tools/jcstress/ jcstress $ cd jcstress/
- 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.
- The harness and tests are heavily experimental, and can change without notice as we understand the methodology better, fix issues, and improve the test reliability and correctness.
- The project requires JDK 8+ to build and run. It can reference the APIs from future releases, as the jcstress harness will fail gracefully on API mismatches, and the mismatched tests will be just skipped.
- Most of the tests are probabilistic, and require substantial time to catch all the cases. It is highly recommended to run tests longer to get reliable results.
- Most of the tests require at least 2 online CPUs. Low CPU count machines could also use these tests, but harness will force yielding there.
- Test failure does not immediately mean the implementation bug. The usual suspects are the bugs in test infrastructure, test grading error, bugs in hardware, or something else. Share your results, discuss them, we will figure out what's wrong. Discuss the result on the relevant mailing lists first. Two usual options are:
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.
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.
- jcstress-core: jcstress infrastructure itself. Any jcstress-driven project should depend on this module. If you have the standalone jcstress tests, you may depend on this module alone.
- jcstress-test-gen: Generator which builds the autogenerated tests in the suite.
- tests-generated: Generated tests. The build of this module will invoke the test generator, and compile the generated tests.
- tests-custom: Custom tests, not coming from the generator. You can use this module to add your own custom tests. Use the JAR for this module to only run the custom tests.
- tests-all: Aggregates all the tests. The build of this module will merge the tests available in other modules.