Thank you, Alan. I've read the proposed documentation and it reads good. One minor, personal nit is that I would use "re-set" instead of "reset" to disambiguate and be extra clear. In my mind, "reset" sets something to its default or initial state. If read cursorily, it may be interpreted as Thread.interrupted() rather than Thread.interrupt(). FWIW, other parts of documentation use "re-assert".
Back to the main topic. I'm sure you know that AutoCloseable.close() has a paragraph [^1] that warns developers against throwing InterruptedException from that method, and that there's a relevant javac warning [^2]: > Implementers of this interface are also strongly advised to not have the > close method throw InterruptedException. This exception interacts with a > thread's interrupted status, and runtime misbehavior is likely to occur if an > InterruptedException is suppressed. More generally, if it would cause > problems for an exception to be suppressed, the AutoCloseable.close method > should not throw it. Given how easy it is to get interruption wrong, would it be helpful to provide similar verbiage directly in Throwable? Maybe in its constructors, initCause, and addSuppressed? Perhaps we can even add more relevant warnigns to javac. Now, I do understand that javac is not a code-quality tool, and that the aforementioned warning [^2] was added only because AutoCloseable.close() interacts with the language feature, try-with-resources. But given how important interruption is, maybe javac could still warn on explicit calls such as addSuppressed(InterruptedException), initCause(InterruptedException), or calls to an exception constructor with InterruptedException as a cause. Just a thought. [^1]: https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/AutoCloseable.html#:~:text=Implementers%20of%20this%20interface%20are%20also%20strongly%20advised [^2]: https://bugs.openjdk.org/browse/JDK-7027157 On Wed, Nov 5, 2025 at 11:41 AM Alan Bateman <[email protected]> wrote: > > On 05/11/2025 11:10, Pavel Rappo wrote: > > I've seen code that wraps InterruptedException in some other exception > prior to throwing that other exception; for example: > > catch (InterruptedException e) { > throw new IOException(e); > } > > I wonder if there are any legitimate cases for this, because I cannot > think of any. In my mind, it's always InterruptedException itself that > should be thrown; and if it cannot be done, then the interrupted > status should be set. > > Right, if you catch InterruptedException then you should re-throw it, or > reset the interrupted status if continuing or throwing a different exception. > As it happens, I am hoping to adding "Thread Interruption" section to the > Thread class description that includes guidance on this, and also gives us a > place to link to from other parts of the API docs. Work in progress [1], not > a PR as it's ready for review. > > -Alan > > [1] > https://github.com/openjdk/jdk/compare/master...AlanBateman:jdk:JDK-8371226
