Summary

This CSR collects javadoc updates in java.util.concurrent to address submitted JBS issues expressing confusion, suggestions, not finding supported functionality, and/or alleged bugs that stemmed from misunderstandings. There are no implementation changes.

Problem

Dozens of small JBS issues that could have been simply resolved with javadoc updates had accumulated. The issues are:

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

Solution

Some updates in this CSR just provide better usage advice or ways to find it. Others make explicit statements about properties that had been left implicit (sometimes leading to alleged bugs), but restricted to cases in which these properties were already included in tck tests or otherwise relied on. When not obvious, comments to this effect are include in the corresponding JBS issues.

Specification

The associated PR (https://github.com/openjdk/jdk/pull/25880) links to each of the JBS issues (and webrevs), that in turn contain compatibility notes when applicable.

The diffs from the PR are also attached to this CSR.