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

[Pavel Rappo]

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

> This is docs only change to a add 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.

Thanks for taking care of this and for taking on board my earlier suggestion from a core-libs-dev thread not to use "reset" when talking about re-asserting interrupted status. I can see that you chose "restore" instead. This is much better and matches, for example, "Java Concurrency in Practice".

src/java.base/share/classes/java/lang/InterruptedException.java line 30:

> 28: /**
> 29:  * Thrown when a thread executing a blocking method is {@linkplain Thread#interrupt()
> 30:  * interrupted}. {@link Thread#sleep(long)}, {@link Object#wait()} and many other

I can see that you moved `Thread#sleep(long)` from `@see` to here. However, since the initial documentation was created, a few other `sleep` methods have been added. Consider using this "generic sleep" text instead (which is what you use in Thread anyway):

    {@link Thread#sleep(long) Thread.sleep}

src/java.base/share/classes/java/lang/InterruptedException.java line 40:

> 38:  * normally or handling it by throwing another type of exception. Code that throws a
> 39:  * different type of exception with the {@code InterruptedException} as {@linkplain
> 40:  * Throwable#getCause() cause} should also restore the interrupted status before

Here and in Thread: should we add that code that suppresses InterruptedException should also restore interrupted status before throwing the primary exception?

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

> 195:  * java.nio.channels.InterruptibleChannel} is interrupted then it causes the channel to be
> 196:  * closed, and the blocking I/O operation to throw {@link java.nio.channels.ClosedByInterruptException}
> 197:  * with the thread's interrupted status set. If a thread is blocked in a {@linkplain

Suggestion:

 * with the thread's interrupted status set. If a thread that is blocked in a {@linkplain

Otherwise that sentence reads really weird.

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

> 200:  *
> 201:  * <p> Code that doesn't invoke any interruptible methods can still respond to interrupt
> 202:  * by polling the current thread's interrupt status with

Suggestion:

 * by polling the current thread's interrupted status with

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

PR Review: https://git.openjdk.org/jdk/pull/28216#pullrequestreview-3448613289
PR Review Comment: https://git.openjdk.org/jdk/pull/28216#discussion_r2514740481
PR Review Comment: https://git.openjdk.org/jdk/pull/28216#discussion_r2514653869
PR Review Comment: https://git.openjdk.org/jdk/pull/28216#discussion_r2514793865
PR Review Comment: https://git.openjdk.org/jdk/pull/28216#discussion_r2514796925