changeset 350:878eae7a1f23

Add README.
author shade
date Fri, 20 Jan 2017 14:22:55 +0100
parents 8b81e94d0a28
children d561a2727cb1
files README
diffstat 1 files changed, 90 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README	Fri Jan 20 14:22:55 2017 +0100
@@ -0,0 +1,90 @@
+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 9+ to compile all the tests. Most tests are runnable on JDK 6+
+afterwards.
+
+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.
+
+== Caveats
+
+ *) 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 9+ to build and run. It can reference the APIs from
+    the 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:
+        concurrency-interest@cs.oswego.edu: general discussion on concurrency
+        jcstress-dev@openjdk.java.net: to discuss jcstress issues
+
+== 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 rendezvous'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: http://openjdk.java.net/contribute/
+
+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
+
+ *) jcstress-core: jcstress infrastructure itself. Every 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-chapter-*: Generated tests for JDK. 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.
\ No newline at end of file