8359919: Minor java.util.concurrent doc improvements #25880

DougLea · 2025-06-18T17:51:20Z

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)

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

…59919

DougLea · 2025-06-18T17:51:54Z

/issue JDK-8187775

DougLea · 2025-06-18T17:52:16Z

/issue JDK-8254060

bridgekeeper · 2025-06-18T17:52:17Z

👋 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 · 2025-06-18T17:52:27Z

❗ This change is not yet ready to be integrated.
See the Progress checklist in the description for automated requirements.

DougLea · 2025-06-18T17:52:34Z

/issue JDK-8210149

DougLea · 2025-06-18T17:52:54Z

/issue JDK-8199501

openjdk · 2025-06-18T17:52:54Z

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

DougLea · 2025-06-18T17:53:10Z

/issue JDK-8233050

openjdk · 2025-06-18T17:53:18Z

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

DougLea · 2025-06-18T17:53:26Z

/issue JDK-8210312

DougLea · 2025-06-18T17:53:42Z

/issue JDK-8292365

openjdk · 2025-06-18T17:53:45Z

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

DougLea · 2025-06-18T17:53:54Z

/issue JDK-8356304

openjdk · 2025-06-18T17:54:26Z

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

openjdk · 2025-06-18T17:55:05Z

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

openjdk · 2025-06-18T17:55:47Z

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

openjdk · 2025-06-18T17:56:29Z

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

openjdk · 2025-06-18T17:57:38Z

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

openjdk · 2025-06-18T17:58:24Z

@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 · 2025-06-18T18:02:11Z

Webrevs

liach · 2025-06-18T18:20:51Z

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.

src/java.base/share/classes/java/util/concurrent/ForkJoinPool.java

src/java.base/share/classes/java/util/concurrent/Flow.java

DougLea · 2025-06-19T22:44:45Z

/issue JDK-8333172

openjdk · 2025-06-19T22:45:21Z

@DougLea
Adding additional issue to issue list: 8333172: Document a recommendation to use VarHandles instead of java.util.concurrent.atomic.*FieldUpdater.

src/java.base/share/classes/java/util/concurrent/TimeUnit.java

AlanBateman · 2025-06-20T12:19:47Z

src/java.base/share/classes/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.java

+ *     return LEFT.compareAndSet(this, expect, update);
+ *   }
+ *   // ... and so on
+ * }}</pre>


I wonder if this should be convert to a {@snippet ..} and have it handle the checked exceptions thrown by findVarHandle. I'm just thinking of someone seeing VarHandle usage for first time, then reporting a bug that the example doesn't compile.

I made it compilable, in the lest ugly way I could think of. Not sure if either or both should now be snippets? @pavelrappo any thoughts?

Up to you. Currently, in addition to what <pre>{@code ...}</pre> does, a snippet provides a copy-paste facility. Other than that, there isn't much it would buy you here.

In JDK 25 even pre-code is highlighted ¹: https://cr.openjdk.org/~hannesw/8348282/api.00/java.base/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.html

Footnotes

https://mail.openjdk.org/pipermail/javadoc-dev/2025-April/008809.html ↩

src/java.base/share/classes/java/util/concurrent/locks/ReentrantReadWriteLock.java

AlanBateman · 2025-06-20T12:47:43Z

src/java.base/share/classes/java/util/concurrent/ScheduledExecutorService.java

+ * behave in accord with other {@link ExecutorService} tasks, except
+ * that {@code scheduleAtFixedRate} and {@code scheduleWithFixedDelay}
+ * methods create and execute tasks that run periodically until
+ * cancelled.


I think this wording, and use of "enabled", is good.

In passing, the first paragraph schedule "tasks" but returns "a task object". It might be saying that it returns task objects.

Thanks. Reworded as:
The {@code schedule} methods create tasks with various delays

and return {@link ScheduledFuture} objects that can be used to cancel or check

execution.

src/java.base/share/classes/java/util/concurrent/SubmissionPublisher.java

DougLea · 2025-06-20T13:57:15Z

/issue JDK-6374942

openjdk · 2025-06-20T13:58:57Z

@DougLea
Adding additional issue to issue list: 6374942: Improve thread safety of collection .equals() methods.

DougLea · 2025-06-20T15:50:09Z

/issue JDK-7176957

openjdk · 2025-06-20T15:50:39Z

@DougLea
Adding additional issue to issue list: 7176957: ExecutorService submit method javaDoc enhancement.

pavelrappo · 2025-06-20T18:16:08Z

src/java.base/share/classes/java/util/concurrent/CompletionStage.java

 * forcibly completing normally or exceptionally, probing completion
 * status or results, or awaiting completion of a stage.
 * Implementations of CompletionStage may provide means of achieving
 * such effects, as appropriate.  Method {@link #toCompletableFuture}
 * enables interoperability among different implementations of this
 * interface by providing a common conversion type.
 *
+ * <p>Memory consistency effects: Actions in a thread prior to the
+ * submission of a computation producing a {@code CompletionStage}
+ * <i>happen-before</i> that computation begins. And actions taken by


Considering that it's the only occurrence of happen(s)-before in this file, it makes sense to link it to its definition similarly to how it is done in other places.

Thanks, done.

DougLea · 2025-06-21T11:26:50Z

/issue JDK-8172177

openjdk · 2025-06-21T11:28:26Z

@DougLea
Adding additional issue to issue list: 8172177: Improve documentation for CompletionException handling.

DougLea · 2025-06-21T11:44:43Z

/issue JDK-6714849

openjdk · 2025-06-21T11:45:42Z

@DougLea
Adding additional issue to issue list: 6714849: ReentrantReadWriteLock: Abnormal behavior in non-fair mode.

DougLea · 2025-06-21T12:16:08Z

/issue JDK-6625724

openjdk · 2025-06-21T12:16:55Z

@DougLea
Adding additional issue to issue list: 6625724: Allow ReentrantReadWriteLock to not track per-thread read holds.

DougLea · 2025-06-21T12:41:12Z

/issue JDK-6526284

openjdk · 2025-06-21T12:42:10Z

@DougLea
Adding additional issue to issue list: 6526284: Improve AbstractExecutorService javadoc.

liach · 2025-06-21T15:06:44Z

Do we need a CSR to check some of these specification updates?

AlanBateman · 2025-06-21T18:28:37Z

Do we need a CSR to check some of these specification updates?

There is at least one new testable assertion in TimeUnit.timedWait that will need a CSR. I'll look out for others.

AlanBateman · 2025-06-22T06:38:56Z

I did a pass over the latest changes (9d9239c) and all looks good.

There are several classes where the advice for developers could move to an apiNote in the class (or method) description but it would be disruptive given that it's inline with the existing text.

The only change that I think we will need a CSR is the update to TimeUnit as exception is a new testable assertion.

DougLea added 5 commits May 26, 2025 08:11

Reduce branchiness of Exchanger

d3bf00f

Merge branch 'openjdk:master' into JDK-8355026

336fb83

Initial set of doc updates

954c5a1

Merge remote-tracking branch 'refs/remotes/origin/master' into JDK-83…

02e1908

…59919

Revert

519c981

openjdk bot added the rfr Pull request is ready for review label Jun 18, 2025

openjdk bot added the core-libs [email protected] label Jun 18, 2025

pavelrappo reviewed Jun 18, 2025

View reviewed changes

src/java.base/share/classes/java/util/concurrent/ForkJoinPool.java Outdated Show resolved Hide resolved

pavelrappo reviewed Jun 18, 2025

View reviewed changes

src/java.base/share/classes/java/util/concurrent/Flow.java Outdated Show resolved Hide resolved

Adding JDK-8333172 to doc improvements

93ece64

AlanBateman reviewed Jun 20, 2025

View reviewed changes

src/java.base/share/classes/java/util/concurrent/TimeUnit.java Outdated Show resolved Hide resolved

AlanBateman reviewed Jun 20, 2025

View reviewed changes

src/java.base/share/classes/java/util/concurrent/locks/ReentrantReadWriteLock.java Outdated Show resolved Hide resolved

AlanBateman reviewed Jun 20, 2025

View reviewed changes

src/java.base/share/classes/java/util/concurrent/SubmissionPublisher.java Outdated Show resolved Hide resolved

Address review comments; add JDK-6374942

044d8dc

Fix ARFU type; add JDK-7176957

26d96b8

pavelrappo reviewed Jun 20, 2025

View reviewed changes

Address review comments; add JDK-8172177

4279a79

Add JDK-6714849 doc update

0b511a6

Add JDK-6625724 as docfix

6fb5c3d

Add JDK-6526284 doc update

9d9239c

8359919: Minor java.util.concurrent doc improvements #25880

Are you sure you want to change the base?

8359919: Minor java.util.concurrent doc improvements #25880

Conversation

DougLea commented Jun 18, 2025 • edited by openjdk bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Progress

Issues

Reviewing

Uh oh!

DougLea commented Jun 18, 2025

Uh oh!

DougLea commented Jun 18, 2025

Uh oh!

bridgekeeper bot commented Jun 18, 2025

Uh oh!

openjdk bot commented Jun 18, 2025

Uh oh!

DougLea commented Jun 18, 2025

Uh oh!

DougLea commented Jun 18, 2025

Uh oh!

openjdk bot commented Jun 18, 2025

Uh oh!

DougLea commented Jun 18, 2025

Uh oh!

openjdk bot commented Jun 18, 2025

Uh oh!

DougLea commented Jun 18, 2025

Uh oh!

DougLea commented Jun 18, 2025

Uh oh!

openjdk bot commented Jun 18, 2025

Uh oh!

DougLea commented Jun 18, 2025

Uh oh!

openjdk bot commented Jun 18, 2025

Uh oh!

openjdk bot commented Jun 18, 2025

Uh oh!

openjdk bot commented Jun 18, 2025

Uh oh!

openjdk bot commented Jun 18, 2025

Uh oh!

openjdk bot commented Jun 18, 2025

Uh oh!

openjdk bot commented Jun 18, 2025

Uh oh!

mlbridge bot commented Jun 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Webrevs

Uh oh!

liach commented Jun 18, 2025

Uh oh!

Uh oh!

Uh oh!

DougLea commented Jun 19, 2025

Uh oh!

openjdk bot commented Jun 19, 2025

Uh oh!

Uh oh!

AlanBateman Jun 20, 2025

Choose a reason for hiding this comment

Uh oh!

DougLea Jun 20, 2025

Choose a reason for hiding this comment

Uh oh!

pavelrappo Jun 20, 2025

Choose a reason for hiding this comment

Footnotes

Uh oh!

Uh oh!

AlanBateman Jun 20, 2025

Choose a reason for hiding this comment

Uh oh!

DougLea Jun 20, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

DougLea commented Jun 20, 2025

DougLea commented Jun 18, 2025 •

edited by openjdk bot

Loading

mlbridge bot commented Jun 18, 2025 •

edited

Loading