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)

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

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

viktorklang-ora · 2025-06-19T09:39:05Z

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


Suggested change

* <i>happen-before</I> that computation begins. And actions taken by

* <i>happen-before</i> that computation begins. And actions taken by

viktorklang-ora · 2025-06-19T09:42:01Z

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

+ * submission of a computation producing a {@code CompletionStage}
+ * <i>happen-before</I> that computation begins. And actions taken by
+ * a {@code CompletionStage} <i>happen-before</i> actions of any
+ * dependent stage subsequent to its completion.


I found "its" ambiguous in that sentence, does it mean:

Suggested change

* dependent stage subsequent to its completion.

* dependent stage subsequent to that stage's completion.

🤔

Changed to:
And actions taken by

{@code CompletionStage x} happen-before actions of any

dependent stage subsequent to {@code x}'s completion.

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

viktorklang-ora · 2025-06-19T10:01:37Z

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

 *     submit(function.apply(item));
+ *     subscription.request(1);


viktorklang-ora · 2025-06-19T10:02:59Z

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

@@ -46,7 +46,7 @@

 /**
 * A reflection-based utility that enables atomic updates to
- * designated {@code volatile} reference fields of designated
+ * designated non-static {@code volatile} reference fields of designated


Wouldn't this change also apply to the other AtomicXFieldUpdaters?

Yes. Will do. Also, as mentioned by @liach we could trap violations by throwing a better exception. But considering that people should be using VarHandles instead anyway these days, and old uses might depend on current behavior, it doesn't seem worthwhile to add? (line 338)

if (Modifier.isStatic(modifiers))

throw new IllegalArgumentException("Must not be static");

DougLea · 2025-06-19T11:27:26Z

/issue JDK-8353155

openjdk · 2025-06-19T11:39:58Z

@DougLea
Adding additional issue to issue list: 8353155: FutureTask#run(): doc implies synchronous, implementation is async.

DougLea · 2025-06-19T11:40:37Z

/issue JDK-8186959

openjdk · 2025-06-19T11:50:21Z

@DougLea
Adding additional issue to issue list: 8186959: Clarify that Executors.newScheduledThreadPool() is fixed-size.

DougLea · 2025-06-19T11:55:32Z

/issue JDK-8190889

openjdk · 2025-06-19T12:00:42Z

@DougLea
Adding additional issue to issue list: 8190889: TimeUnit.wait should document IllegalMonitorStateException.

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

DougLea · 2025-06-19T17:25:11Z

/issue JDK-6351533

DougLea · 2025-06-19T17:25:31Z

/issue JDK-6317534

openjdk · 2025-06-19T17:25:31Z

@DougLea
Adding additional issue to issue list: 6351533: CyclicBarrier reset() should return the number of awaiters.

openjdk · 2025-06-19T17:26:26Z

@DougLea
Adding additional issue to issue list: 6317534: CyclicBarrier should have a cancel() method.

DougLea · 2025-06-19T18:26:03Z

/issue JDK-8195628

openjdk · 2025-06-19T18:27:02Z

@DougLea
Adding additional issue to issue list: 8195628: Documentation for lock(), trylock(), lockInterruptibly() of ReentrantReadWriteLock.WriteLock needs to be corrected.

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.

AlanBateman · 2025-06-20T12:10:42Z

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

@@ -398,6 +398,8 @@ else if (s == MICRO_SCALE)
     * @param obj the object to wait on
     * @param timeout the maximum time to wait. If less than
     * or equal to zero, do not wait at all.
+     * @throws  IllegalMonitorStateException  if the current thread is not
+     *               the owner of this object's monitor.


This should probably use "the object's monitor" rather than "the object's monitor" as "this" is the TimeUnit instance.

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.

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

viktorklang-ora reviewed Jun 19, 2025

View reviewed changes

DougLea added 2 commits June 19, 2025 07:03

Address review comments

cadb2c9

Add JDK-8353155 doc improvement

18ea3e7

Add JDK-8186959 docfix

bd543fc

Add JDK-8190889 docfix

4ef7649

viktorklang-ora reviewed Jun 19, 2025

View reviewed changes

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

Add JDK-6317534 and JDK-6351533 doc improvements

b10114e

Add JDK-8195628 doc fix

c85698c

Adding JDK-8333172 to doc improvements

93ece64

AlanBateman reviewed Jun 20, 2025

View reviewed changes

	* <i>happen-before</I> that computation begins. And actions taken by
	* <i>happen-before</i> that computation begins. And actions taken by

	* dependent stage subsequent to its completion.
	* dependent stage subsequent to that stage's completion.

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

Uh oh!

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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DougLea commented Jun 19, 2025

Uh oh!

openjdk bot commented Jun 19, 2025

Uh oh!

DougLea commented Jun 19, 2025

Uh oh!

openjdk bot commented Jun 19, 2025

Uh oh!

DougLea commented Jun 19, 2025

DougLea commented Jun 18, 2025 •

edited by openjdk bot

Loading

mlbridge bot commented Jun 18, 2025 •

edited

Loading