RFR: 8279031: Add API note to ToolProvider about being reusable/reentrant [v2]

[Anthony Vanelverdinghe]

On Tue, 24 May 2022 04:50:58 GMT, Jaikiran Pai <jpai at openjdk.org> wrote:

>> Christian Stein has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Update src/java.base/share/classes/java/util/spi/ToolProvider.java
>>   
>>   Co-authored-by: Anthony Vanelverdinghe <dev at anthonyv.be>
>
> src/java.base/share/classes/java/util/spi/ToolProvider.java line 59:
> 
>> 57:  * a tool may be the target of multiple {@code run} method invocations,
>> 58:  * and reentrant means that multiple invocations of {@code run} may occur
>> 59:  * concurrently.
> 
> Hello @sormuras,
> 
>> reentrant means that multiple invocations of {@code run} may occur
>> concurrently.
> 
> My understanding of re-entrant was that the same method could be re-invoked on the same thread while the current method execution is in progress (a recursion). Whereas "multiple invocations may occur concurrently" sounds more like multiple threads invoking this concurrently (i.e. thread-safety). Which of these 2 characteristics are we recommending here?

I agree with @jaikiran that reentrant is much more common in the sense of "on the same thread". Plus that the JDK itself uses "ReentrantLock" in this meaning. The JDK uses either "thread-safe" or "synchronized" for the "multiple threads" meaning.

Actually, being thread-safe implies being reusable, so I'd just phrase it as:

> It is recommended that tools implementing this interface are either
> thread-safe, or clearly document any limitations and restrictions.

Also: should this be an `@implNote`, rather than an `@apiNote`, since it's about "tools implementing this interface"?

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

PR: https://git.openjdk.java.net/jdk/pull/8833