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

[Alan Bateman]

On Tue, 11 Nov 2025 15:26:05 GMT, Pavel Rappo <prappo 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.
>
> 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?

I think that would be too much to try to put in the InterruptedException class description but we could potentially extend the sentence in the Thread Interruption section to include the case where someone chooses to add the InterruptedException as a suppressed exception.

I would prefer not get into further guidance for unwrapping, e.g.  catch FooException, get the InterruptedException cause, clear the interrupted status before re-throwing the cause.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/28216#discussion_r2515073463