Before JEP 428: Structured Concurrency (Incubator), the importance of the interrupt mechanism for the driver was based mostly on the potentiality of user code to use the following pieces of the Java SE API:

• Future.cancel
• ExecutorService.shutdownNow

and on a few occasions when the driver uses this mechanism directly. Structured concurrency adds new functionality that relies on interrupts: "Any fork in a scope, their own transitive forks, or the scope's owner, can call StructuredTaskScope.shutdown at any time to signify that the task is complete, even while other forks are still running. shutdown causes the threads of all forks that are still active in the scope to be interrupted; all forks should, therefore, be written in a way that is responsive to interruption. In effect, shutdown is the concurrent analog of the break statement in sequential code.". This gives us one more reason to make sure the driver code is responsive to interruption.

We discussed this with jeff.yemin@mongodb.com, and so far the agreement is that we need to make sure driver's code satisfies the following set of rules:

1. If a method throws InterruptedException (this implies it is declared as throwing Throwable/Exception/InterruptedException), then the interrupted flag must not be raised by the driver.
2. If a synchronous method prohibits an InterruptedException from being propagated through the call stack, for example, by throwing another exception instead (even if it is MongoInterruptedException), then the flag must be raised by the driver, unless
   1. this is a Thread.run method, or a similar method acting as the bottom/end of a call stack;
   2. this is an thread managed by the driver, in which case the driver is free to handle interrupts differently, as it cannot surprise the user code, unless this thread may execute user code and the driver documented guarantees regarding threads that may execute it and how they react to interrupts (currently, we don't expose such guarantees).

These rules mean, for example, that in situations when we catch Throwable/Exception in synchronous code and do not re-throw it as is, we must catch InterruptedException separately and then either throw it as is, or raise the flag. In asynchronous code, when we catch Throwable/Exception only to propagate it to a callback because exceptions in asynchronous code are not propagated through the call stack, we must not treat InterruptedException specially.