RFR: 8276700: Improve java.lang.ref.Cleaner javadocs

[Roger Riggs]

On Mon, 8 Nov 2021 19:40:20 GMT, Hendrik Schreiber <hschreiber at openjdk.org> wrote:

>> src/java.base/share/classes/java/lang/ref/Cleaner.java line 90:
>> 
>>> 88:  * public class CleaningExample implements AutoCloseable {
>>> 89:  *        // A cleaner, preferably one shared within a library
>>> 90:  *        private static final Cleaner cleaner = Cleaner.create();
>> 
>> Now the code (creating a private instance) goes against what the comment advises (using a shared instance), doesn't it?
>
> You have a point.
> 
> BUT, at least it's a working example and not some pseudo code. We do want to move to working example code long term, don't we?
> 
> When I see <cleaner>, I'm just wondering what those <> type operators are good for here...

A cleaner can/should be shared within some scope and purpose, in this case the example class .
Each cleaner has a dedicated Thread so its not a lightweight object and should not be proliferated.
(Loom may be able to use Virtual Threads).

The reasons to not share are a Cleaner are based on possible interference between the cleanup callbacks.
If they share a thread and are non-trivial, it might slow other cleaners. If the cleaner is created and shared
for a particular purpose it will share the thread resource and still be efficient.

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

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