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

[Hendrik Schreiber]

On Tue, 9 Nov 2021 00:31:36 GMT, Brent Christian <bchristi at openjdk.org> wrote:

>> 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.
>
> The new example Cleaner instance _is_ shared, though on a pretty small scale (just among instances of CleaningExample).  A demonstration of larger scale sharing of a Cleaner instance would be out of scope for this example.

Let me add, why I have raised this issue.

I was going to migrate some older code which uses the `finalize()` method to the `Cleaner` mechanism. New it it, there seemed to be two pitfalls:

1. Understanding the whole "don't capture an instance reference in your state object"
2. Copying the example (which was in a non-working state, due to pseudo code) and making it work for me

With the improvement suggestions, I was trying help people who *only* read the code sample (many do), to become aware of 1. and help them getting going with 2, simply because it's something they can copy and run.

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

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