RFR: 8371226: Thread class description needs section on Thread Interruption

[Viktor Klang]

On Mon, 10 Nov 2025 14:37:12 GMT, Alan Bateman <alanb at openjdk.org> wrote:

> This is docs only change to a new section to the Thread class description on Thread Interruption.  The new section provides guidance on handling InterruptedException. A subset of that guidance is also proposed for the InterruptedException class description.

src/java.base/share/classes/java/lang/Thread.java line 157:

> 155:  * }
> 156:  *
> 157:  * <h2><a id="inheritance">Inheritance When Creating Threads</a></h2>

Detected an inconsistency: Capital "W" on When but not capital "A" on "and" in the previous heading

src/java.base/share/classes/java/lang/Thread.java line 185:

> 183:  * <p> If a thread executing {@link #sleep(long) Thread.sleep} or {@link Object#wait()
> 184:  * Object.wait} is interrupted then it causes the method to return early and throw
> 185:  * {@link InterruptedException}. Methods that throw {@code InterruptedException} do so after

I think something like this is clearer:

Suggestion:

 * Object.wait} is interrupted then it causes the method to exit early by throwing an
 * {@link InterruptedException}. Methods that throw {@code InterruptedException} do so after

src/java.base/share/classes/java/lang/Thread.java line 189:

> 187:  * should rethrow the exception, or restore the current thread's interrupted status, with
> 188:  * {@link #currentThread() Thread.currentThread()}.{@link #interrupt()}, before continuing
> 189:  * normally or handling it by throwing another type of exception.

Perhaps add "even if wrapping the InterruptedException"?

src/java.base/share/classes/java/lang/Thread.java line 205:

> 203:  * {@code Thread} also defines the static {@link #interrupted() Thread.interrupted()}
> 204:  * method to test the current thread's interrupted status and clear it. It should be rare
> 205:  * to need to use this method.

I wonder if we can give clearer instructions/examples as to when to use this method?

src/java.base/share/classes/java/lang/Thread.java line 1643:

> 1641:      * to test if interrupted and clear the interrupted status to allow the code
> 1642:      * retry the <em>interruptible</em> method. The <em>uninterruptible</em> method
> 1643:      * should restore the interrupted status before it completes.

👍

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/28216#discussion_r2511026652
PR Review Comment: https://git.openjdk.org/jdk/pull/28216#discussion_r2511057549
PR Review Comment: https://git.openjdk.org/jdk/pull/28216#discussion_r2511072080
PR Review Comment: https://git.openjdk.org/jdk/pull/28216#discussion_r2511164109
PR Review Comment: https://git.openjdk.org/jdk/pull/28216#discussion_r2511944188