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

[Alan Bateman]

On Mon, 10 Nov 2025 15:31:31 GMT, Viktor Klang <vklang 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

These headings are in in title case so "When" is capitalised but not "and".

> 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

The previous paragraph establishes the phrase "return early" so this is why it is re-used here maybe "method to exit" would be better here, I'll play with it.

> 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"?

I've added a sentence for this.

> 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?

That's good idea, I've put a first version in interrupted() as an apiNote.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/28216#discussion_r2511850457
PR Review Comment: https://git.openjdk.org/jdk/pull/28216#discussion_r2511858145
PR Review Comment: https://git.openjdk.org/jdk/pull/28216#discussion_r2511859774
PR Review Comment: https://git.openjdk.org/jdk/pull/28216#discussion_r2511852468