8359919: Minor java.util.concurrent doc improvements

[DougLea]

This collects miscellaneous open issues that can be resolved with documentation updates; each indicated by adding JDK issue numbers

---

Progress

• Change must be properly reviewed (1 review required, with at least 1 Reviewer)
• Change must not contain extraneous whitespace
• Commit message must refer to an issue

Issues

• JDK-8359919: Minor java.util.concurrent doc improvements (Bug - P4)
• JDK-8187775: AtomicReferenceFieldUpdater does not support static fields (Bug - P4)
• JDK-8254060: SubmissionPublisher close hangs if a publication is pending (Bug - P4)
• JDK-8210149: Example in JavaDoc for java.util.concurrent.Flow violates Reactive Streams spec (Enhancement - P4)
• JDK-8199501: Improve documentation of CompletableFuture, CompletionStage (Enhancement - P4)
• JDK-8233050: CompletableFuture whenComplete and thenApply change exceptional result (Bug - P4)
• JDK-8210312: JavaDoc example in SubmissionPublisher will potentially crash (Enhancement - P4)
• JDK-8292365: CompletableFuture and CompletionStage should document Memory Model guarantees (Enhancement - P4)
• JDK-8356304: Define "enabled" in ScheduledExecutorService (Bug - P4)
• JDK-8353155: FutureTask#run(): doc implies synchronous, implementation is async (Enhancement - P4)
• JDK-8186959: Clarify that Executors.newScheduledThreadPool() is fixed-size (Bug - P3)
• JDK-8190889: TimeUnit.wait should document IllegalMonitorStateException (Bug - P4)
• JDK-6351533: CyclicBarrier reset() should return the number of awaiters (Enhancement - P4)
• JDK-6317534: CyclicBarrier should have a cancel() method (Enhancement - P3)
• JDK-8195628: Documentation for lock(), trylock(), lockInterruptibly​() of ReentrantReadWriteLock.WriteLock needs to be corrected (Bug - P4)
• JDK-8333172: Document a recommendation to use VarHandles instead of java.util.concurrent.atomic.*FieldUpdater (Enhancement - P4)
• JDK-6374942: Improve thread safety of collection .equals() methods (Bug - P3)
• JDK-7176957: ExecutorService submit method javaDoc enhancement (Enhancement - P4)
• JDK-8172177: Improve documentation for CompletionException handling (Bug - P4)
• JDK-6714849: ReentrantReadWriteLock: Abnormal behavior in non-fair mode (Bug - P4)
• JDK-6625724: Allow ReentrantReadWriteLock to not track per-thread read holds (Enhancement - P3)
• JDK-6526284: Improve AbstractExecutorService javadoc (Enhancement - P4)
• JDK-8137156: Javadoc for Future is misleading with respect to cancellation (Enhancement - P4)
• JDK-6663476: FutureTask.get() may return null if set() is not called from run() (Bug - P4)
• JDK-8311131: ConcurrentHashMap.forEachKey parallelismThreshold description could be clearer (Enhancement - P4)

Reviewers

• Alan Bateman (@AlanBateman - Reviewer)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/25880/head:pull/25880
$ git checkout pull/25880

Update a local copy of the PR:
$ git checkout pull/25880
$ git pull https://git.openjdk.org/jdk.git pull/25880/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 25880

View PR using the GUI difftool:
$ git pr show -t 25880

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/25880.diff

Using Webrev

Link to Webrev Comment

[DougLea]

/issue JDK-8187775

[DougLea]

/issue JDK-8254060

[bridgekeeper]

👋 Welcome back dl! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

[openjdk]

@DougLea This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8359919: Minor java.util.concurrent doc improvements
8187775: AtomicReferenceFieldUpdater does not support static fields
8254060: SubmissionPublisher close hangs if a publication is pending
8210149: Example in JavaDoc for java.util.concurrent.Flow violates Reactive Streams spec
8199501: Improve documentation of CompletableFuture, CompletionStage
8233050: CompletableFuture `whenComplete` and `thenApply` change exceptional result
8210312: JavaDoc example in SubmissionPublisher will potentially crash
8292365: CompletableFuture and CompletionStage should document Memory Model guarantees
8356304: Define "enabled" in ScheduledExecutorService
8353155: FutureTask#run(): doc implies synchronous, implementation is async
8186959: Clarify that Executors.newScheduledThreadPool() is fixed-size
8190889: TimeUnit.wait should document IllegalMonitorStateException
6351533: CyclicBarrier reset() should return the number of awaiters
6317534: CyclicBarrier should have a cancel() method
8195628: Documentation for lock(), trylock(), lockInterruptibly​()  of ReentrantReadWriteLock.WriteLock needs to be corrected
8333172: Document a recommendation to use VarHandles instead of java.util.concurrent.atomic.*FieldUpdater
6374942: Improve thread safety of collection .equals() methods
7176957: ExecutorService submit method javaDoc enhancement
8172177: Improve documentation for CompletionException handling
6714849: ReentrantReadWriteLock: Abnormal behavior in non-fair mode
6625724: Allow ReentrantReadWriteLock to not track per-thread read holds
6526284: Improve AbstractExecutorService javadoc
8137156: Javadoc for Future is misleading with respect to cancellation
6663476: FutureTask.get() may return null if set() is not called from run()
8311131: ConcurrentHashMap.forEachKey parallelismThreshold description could be clearer

Reviewed-by: alanb

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 7 new commits pushed to the master branch:

• cbcf401: 8360403: Disable constant pool ID assert during troubleshooting
• f8de5bc: 8328848: Inaccuracy in the documentation of the -group option
• 9a726df: 8359024: Accessibility bugs in API documentation
• ... and 4 more: https://git.openjdk.org/jdk/compare/28e96e333b61dfe60a84a48ff59bdf10c529f8be...master

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

[DougLea]

/issue JDK-8210149

[DougLea]

/issue JDK-8199501

[openjdk]

@DougLea
Adding additional issue to issue list: 8187775: AtomicReferenceFieldUpdater does not support static fields.

[DougLea]

/issue JDK-8233050

[openjdk]

@DougLea
Adding additional issue to issue list: 8254060: SubmissionPublisher close hangs if a publication is pending.

[DougLea]

/issue JDK-8210312

[DougLea]

/issue JDK-8292365

[openjdk]

@DougLea
Adding additional issue to issue list: 8210149: Example in JavaDoc for java.util.concurrent.Flow violates Reactive Streams spec.

[DougLea]

/issue JDK-8356304

[openjdk]

@DougLea
Adding additional issue to issue list: 8199501: Improve documentation of CompletableFuture, CompletionStage.

[openjdk]

@DougLea
Adding additional issue to issue list: 8233050: CompletableFuture whenCompleteandthenApply change exceptional result.

[openjdk]

@DougLea
Adding additional issue to issue list: 8210312: JavaDoc example in SubmissionPublisher will potentially crash.

[openjdk]

@DougLea
Adding additional issue to issue list: 8292365: CompletableFuture and CompletionStage should document Memory Model guarantees.

[openjdk]

@DougLea
Adding additional issue to issue list: 8356304: Define "enabled" in ScheduledExecutorService.

[openjdk]

@DougLea The following label will be automatically applied to this pull request:

• core-libs

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label pull request command.

[mlbridge]

Webrevs

• 17: Full - Incremental (2a62fc8f)
• 16: Full - Incremental (533304c0)
• 15: Full - Incremental (153b2b78)
• 14: Full - Incremental (944ddab2)
• 13: Full - Incremental (9d9239c5)
• 12: Full - Incremental (6fb5c3d4)
• 11: Full - Incremental (0b511a6c)
• 10: Full - Incremental (4279a791)
• 09: Full - Incremental (26d96b88)
• 08: Full - Incremental (044d8dcd)
• 07: Full - Incremental (93ece642)
• 06: Full - Incremental (c85698c7)
• 05: Full - Incremental (b10114e5)
• 04: Full - Incremental (4ef7649a)
• 03: Full - Incremental (bd543fc5)
• 02: Full - Incremental (18ea3e7b)
• 01: Full - Incremental (cadb2c91)
• 00: Full (519c981f)

[liach]

I think the problem in AtomicReferenceFieldUpdater being passed a static field exists for the other kinds of field updaters too. Currently the IAE is thrown by Unsafe, which is a hidden contract and can be inadvertently changed and affect the APIs; we might consider throwing IAE for static fields explicitly instead to avoid this pitfall.

[DougLea]

/issue JDK-6663476

[openjdk]

⚠️ @DougLea This pull request contains merges that bring in commits not present in the target repository. Since this is not a "merge style" pull request, these changes will be squashed when this pull request in integrated. If this is your intention, then please ignore this message. If you want to preserve the commit structure, you must change the title of this pull request to Merge <project>:<branch> where <project> is the name of another project in the OpenJDK organization (for example Merge jdk:master).

[openjdk]

@DougLea
Adding additional issue to issue list: 6663476: FutureTask.get() may return null if set() is not called from run().

[DougLea]

/issue JDK-8311131

[openjdk]

@DougLea
Adding additional issue to issue list: 8311131: ConcurrentHashMap.forEachKey parallelismThreshold description could be clearer.

[AlanBateman]

Latest version (with the "bulk" update to CHM) looks good.