comparison README @ 405:04bd0247edbb

7901946: javadoc cannot be generated with the latest jdk9-ea build Summary: Only generate the Javadocs for the "safe" parts of API, including jcstress annotations.
author shade
date Mon, 08 May 2017 16:37:41 +0200
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:63bf1b42bfa5
1 The Java Concurrency Stress tests (jcstress) is an experimental harness and
2 a suite of tests to aid the research in the correctness of concurrency support
3 in the JVM, class libraries, and hardware.
4
5 === Quick start
6
7 You should have Mercurial and Maven installed to check out and build the tests.
8 You will need JDK 9+ to compile all the tests. Most tests are runnable on JDK 6+
9 afterwards.
10
11 Check out the jcstress source:
12 $ hg clone http://hg.openjdk.java.net/code-tools/jcstress/ jcstress
13 $ cd jcstress/
14
15 Build jcstress. Since jcstress is a large project, you may want to build only
16 the minimal subset of it:
17 $ mvn clean install -pl tests-custom -am
18 $ java -jar tests-custom/target/jcstress.jar
19
20 Run the JAR with -h to get the help.
21
22 == Caveats
23
24 *) The harness and tests are heavily experimental, and can change without notice
25 as we understand the methodology better, fix issues, and improve the test
26 reliability and correctness.
27
28 *) The project requires JDK 9+ to build and run. It can reference the APIs from
29 the future releases, as the jcstress harness will fail gracefully on API
30 mismatches, and the mismatched tests will be just skipped.
31
32 *) Most of the tests are probabilistic, and require substantial time to catch
33 all the cases. It is highly recommended to run tests longer to get reliable
34 results.
35
36 *) Most of the tests require at least 2 online CPUs. Low CPU count machines could
37 also use these tests, but harness will force yielding there.
38
39 *) Test failure does not immediately mean the implementation bug. The usual
40 suspects are the bugs in test infrastructure, test grading error, bugs in
41 hardware, or something else. Share your results, discuss them, we will figure
42 out what's wrong. Discuss the result on the relevant mailing lists first.
43
44 Two usual options are:
45 concurrency-interest@cs.oswego.edu: general discussion on concurrency
46 jcstress-dev@openjdk.java.net: to discuss jcstress issues
47
48 == Understanding the tests and Interpreting the results
49
50 The tests are similar to what Litmus tests look like, where few threads are
51 executing the test concurrently, sometimes rendezvous'ing over the shared state.
52 There are multiple state objects generated per each run. Threads then either mutate
53 or observe that state object. Test harness is collecting statistics on the observed
54 states. In many cases this is enough to catch the reorderings or contract violations
55 for concurrent code.
56
57 The console output can be used to track progress and debugging. Ordinary users should
58 use generated HTML report, which has the full interpretation of the results.
59
60 == Developing tests
61
62 Please consider contributing the interesting tests back. We follow the OpenJDK policy
63 on contributions: http://openjdk.java.net/contribute/
64
65 If you want to develop a test, you are encouraged to get familiar with existing set of
66 tests first. You will have to have a class annotated with jcstress annotations, see the
67 harness API. Read up their Javadocs to understand the conditions that are guaranteed for
68 those tests. If you need some other test interface/harness support, please don't hesitate
69 to raise the issue and describe the scenario you want to test.
70
71 You are encouraged to provide the thorough explanation why particular test outcome is
72 acceptable/forbidden/special. Even though harness will print the debug output into the
73 console if no description is given.
74
75 == Project layout
76
77 *) jcstress-core: jcstress infrastructure itself. Every jcstress-driven project should
78 depend on this module. If you have the standalone jcstress tests, you may depend on this
79 module alone.
80
81 *) jcstress-test-gen: Generator which builds the autogenerated tests in the suite.
82
83 *) tests-chapter-*: Generated tests for JDK. The build of this module will invoke the
84 test generator, and compile the generated tests.
85
86 *) tests-custom: Custom tests, not coming from the generator. You can use this module to
87 add your own custom tests. Use the JAR for this module to only run the custom tests.
88
89 *) tests-all: Aggregates all the tests. The build of this module will merge the tests available
90 in other modules.