{"id":25776827,"url":"https://github.com/openjdk/jcstress","last_synced_at":"2025-06-17T14:06:12.483Z","repository":{"id":38834117,"uuid":"298223290","full_name":"openjdk/jcstress","owner":"openjdk","description":"https://openjdk.org/projects/code-tools/jcstress","archived":false,"fork":false,"pushed_at":"2025-06-10T09:14:02.000Z","size":1902,"stargazers_count":449,"open_issues_count":7,"forks_count":62,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-06-11T23:15:27.264Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openjdk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP","authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-24T08:56:18.000Z","updated_at":"2025-06-10T09:14:06.000Z","dependencies_parsed_at":"2024-03-14T11:35:44.944Z","dependency_job_id":"5c690295-86ea-46bb-9c72-12a4e92d856e","html_url":"https://github.com/openjdk/jcstress","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/openjdk/jcstress","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openjdk%2Fjcstress","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openjdk%2Fjcstress/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openjdk%2Fjcstress/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openjdk%2Fjcstress/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openjdk","download_url":"https://codeload.github.com/openjdk/jcstress/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openjdk%2Fjcstress/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260375258,"owners_count":22999488,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-02-27T06:01:31.833Z","updated_at":"2025-06-17T14:06:07.445Z","avatar_url":"https://github.com/openjdk.png","language":"Java","funding_links":[],"categories":["测试"],"sub_categories":[],"readme":"# Java Concurrency Stress (jcstress)\n\nThe Java Concurrency Stress (jcstress) is the experimental harness and\na suite of tests to aid the research in the correctness of concurrency support\nin the JVM, class libraries, and hardware.\n\n## Usage\n\n### Samples\n\nIn order to understand jcstress tests and maybe write your own, it might be useful\nto work through the [jcstress-samples](https://github.com/openjdk/jcstress/tree/master/jcstress-samples/src/main/java/org/openjdk/jcstress/samples). The samples come in three groups:\n * **APISample** target to explain the jcstress API;\n * **JMMSample** target to explain the basics of Java Memory Model;\n * **ConcurrencySample** show the interesting concurrent behaviors of standard library.\n\nSee the test comments for run instructions. Most tests can be run like this:\n\n     $ mvn clean verify -pl jcstress-samples -am\n     $ java -jar jcstress-samples/target/jcstress.jar -t \u003ctest-name\u003e\n\n### Running The Existing Tests\n\nThe quickest way to start running jcstress is to use a prebuilt JAR, for example from [here](https://builds.shipilev.net/jcstress/).\n\n     $ java -jar jcstress.jar\n\nRun the JAR with `-h` to see available options.\n\nOtherwise, you can build the entire test suite yourself:\n\n     $ mvn clean verify\n     $ java -jar tests-all/target/jcstress.jar\n\nThe project requires JDK 11+ to build. It can reference the APIs from\nthe future releases, as the jcstress harness will fail gracefully on API\nmismatches, and the mismatched tests will be just skipped.\n\n\n### Extending The Tests\n\nPlease consider contributing the interesting tests back.\n\nIf you want to develop a test, you are encouraged to get familiar with existing set of\ntests first. You will have to have a class annotated with jcstress annotations, see the\nharness API. Read up their Javadocs to understand the conditions that are guaranteed for\nthose tests. If you need some other test interface/harness support, please don't hesitate\nto raise the issue and describe the scenario you want to test.\n\nYou are encouraged to provide the thorough explanation why particular test outcome is\nacceptable/forbidden/special. Even though harness will print the debug output into the\nconsole if no description is given.\n\nYou should have Git and Maven installed to check out and build the tests.\nYou will need JDK 17+ to compile all the tests. Most tests are runnable on JDK 8+\nafterwards.\n\nThe vast majority of jcstress tests are auto-generated. The custom/hand-written tests\nusually go to `tests-custom`. This also allows building the smaller subset of tests:\n\n    $ mvn clean verify -pl tests-custom -am\n    $ java -jar tests-custom/target/jcstress.jar\n\n### Using jcstress As Separate Dependency\n\nIf you want to use jcstress as separate dependency in your project, then you are recommended\nto create the submodule with the jcstress tests, which would use jcstress libraries and build\nsteps.\n\n[Maven Central](https://repo.maven.apache.org/maven2/org/openjdk/jcstress/jcstress-core/) contains\nthe latest releases of jcstress libraries. Using jcstress as the library requires special build configuration.\nThe easiest way to bootstrap the project with jcstress is to use the archetype:\n\n    $ mvn archetype:generate \\\n     -DinteractiveMode=false \\\n     -DarchetypeGroupId=org.openjdk.jcstress \\\n     -DarchetypeArtifactId=jcstress-java-test-archetype \\\n     -DgroupId=org.sample \\\n     -DartifactId=test \\\n     -Dversion=1.0\n\nThen you can build and use it:\n\n    $ cd test\n    $ mvn clean verify\n    $ java -jar target/jcstress.jar\n\n\n## Interpreting The Results\n\nThe tests are arranged so that a few threads are executing the test concurrently, sometimes\nrendezvous'ing over the shared state. There are multiple state objects generated per each run.\nThreads then either mutate or observe that state object. Test harness is collecting statistics on\nthe observed states. In many cases this is enough to catch the reorderings or contract violations\nfor concurrent code.\n\nThe console output can be used to track progress and debugging. Ordinary users should\nuse generated HTML report, which has the full interpretation of the results.\n\nMost of the tests are probabilistic, and require substantial time to catch all the cases.\nIt is highly recommended to run tests longer to get reliable results. Since the tests are\ntime-bound, the faster CPUs the machine has the more samples jcstress collects. There is\na tradeoff between the number of samples harness collects and the suite run time.\nThere are a few preset modes that set sensible test durations, see `-m`. Many\nCIs run jcstress with `-m quick` for quicker turnaround.\n\nTest failure does not immediately mean the implementation bug. The usual\nsuspects are the bugs in test infrastructure, test grading error, bugs in\nhardware, or something else. Share your results, discuss them, we will figure\nout what's wrong. Discuss the result on the relevant mailing lists first.\n\nTwo usual options are:\n  * concurrency-interest@cs.oswego.edu: general discussion on concurrency\n  * jcstress-dev@openjdk.java.net: to discuss jcstress issues\n\n## Reporting Harness and Test Bugs\n\nIf you have the access to [JDK Bug System](https://bugs.openjdk.org/), please submit the bug there:\n * Project: CODETOOLS\n * Component: tools\n * Sub-component: jcstress\n\n## Development\n\njcstress project accepts pull requests, like other OpenJDK projects.\nIf you have never contributed to OpenJDK before, then bots would require you to [sign OCA first](https://openjdk.org/contribute/).\nNormally, you don't need to post patches anywhere else, or post to mailing lists, etc.\nIf you do want to have a wider discussion about jcstress, please refer to [jcstress-dev](https://mail.openjdk.org/mailman/listinfo/jcstress-dev).\n\nCompile and run internal tests:\n\n    $ mvn clean install\n\nRun the quick tests:\n\n    $ java -jar tests-all/target/jcstress.jar -m quick\n\nGitHub workflow \"JCStress Pre-Integration Tests\" should pass on the changes. It would be triggered\nfor PRs. You can also trigger it manually for your branch.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenjdk%2Fjcstress","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenjdk%2Fjcstress","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenjdk%2Fjcstress/lists"}