RFR: StructuredTaskScope Javadoc: consistently use the phrase "contained in the task scope"

[Alan Bateman]

On Sun, 13 Nov 2022 12:04:25 GMT, Anthony Vanelverdinghe <duke at openjdk.org> wrote:

> The class-level Javadoc of StructuredTaskScope contains the following:
> 
>> The phrase "threads contained in the task scope" in method descriptions means threads started in the task scope or descendant scopes.
> 
> However, the method-level Javadoc sometimes uses slightly different wordings.
> This PR updates the Javadoc to consistently use the phrase "contained in the task scope" (and fixes an unrelated typo).
> 
> PS: I'll need help from someone to create a JBS issue & sponsor this PR

src/jdk.incubator.concurrent/share/classes/jdk/incubator/concurrent/StructuredTaskScope.java line 629:

> 627:      * {@linkplain Future#get() waiting} on a result so that the waiting threads wakeup.
> 628:      * <li> {@linkplain Thread#interrupt() Interrupts} all unfinished threads contained in the
> 629:      * task scope.

The existing javadoc is correct. When you invoke scope.shutdown() it interrupts the unfinished threads in the task scope, it's just one level, not the tree. It might be that interrupting these threads leads to these threads invoking shutdown or close on other task scopes in the tree but that's an indirect effect that can't be specified here. Also, the reason it says "except the current thread" is because the shutdown method can be called from a thread started in the task scope and it would be confusing to interrupt self. So we shouldn't remove that from the javadoc.

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

PR: https://git.openjdk.org/loom/pull/194