Summary

Add a new section to the java.lang.Thread class description on Thread Interruption. The new section introduces the topic and provides guidance on handling InterruptedException. A subset of that guidance is also proposed for the InterruptedException class description.

Problem

Thread interruption is a low-level mechanism that allows code executing in one thread request code executing in another thread to "stop or cancel its current activity". The mechanism exists since JDK 1.0 but isn't widely understood. The introduction of Structured Concurrency and other APIs means that more developers will be directly exposed to thread interruption and InterruptedException than were previously exposed. The Thread API docs do not provide an overview of the mechanism, nor provide guidance on how to handle InterruptedException.

Solution

Add a new section on Thread Interruption to java.lang.Thread. The new section includes guidance on how to handle InterruptedException. InterruptedException is also updated to provide guidance on how to handle the exception.

Specification

See attached apidiffs.