RFR 9: 8138696 : java.lang.ref.Cleaner - an easy to use alternative to finalization

[Roger Riggs]

Hi Peter,

On 12/04/2015 03:30 PM, Peter Levart wrote:
> Just a nit more, Roger:
>
>  131      * <p>
>  132      * The cleaner terminates when it is unreachable and all of the
>  133      * registered cleaning functions are complete.
>
> (and also in the javadoc of the other create() method)
>
> The cleaner is an object. What terminates is a thread. So what about:
>
> "The thread terminates after the cleaner becomes unreachable and all 
> of the registered cleaning functions have completed."

The cleaner is not just an object but is an active processing element.
The thread is an artifact of the implementation and not exposed in the API
any more than necessary (due to the thread factory).

Colloquially, the combination of  state and thread can be referred to as 
the cleaner;
it starts, it processes cleanup functions for unreachable objects, and 
it stops when there are no more.

It may be useful to talk about the thread terminating, but that is an 
implementation detail
and not readily visible.

>
>
> Would writing something like the following make sense: "A future 
> implementation may use more than one thread. The ThreadFactory should 
> not assume that only one thread will be requested." ?
I'm not sure it adds anything to talk about how many times the thread 
factory will be used.
A ThreadFactory has no specific mins or maxes.

Roger

>
> Regards, Peter
>
> On 12/04/2015 05:55 PM, Roger Riggs wrote:
>> Hi,
>>
>> Thanks for the review and comments.
>>
>> The webrev[1] and javadoc[2] are updated in place.
>>
>> Roger
>>
>> [1] http://cr.openjdk.java.net/~rriggs/webrev-cleaner-8138696/
>> [2] http://cr.openjdk.java.net/~rriggs/cleaner-doc/index.html
>>
>> On 12/3/2015 4:50 PM, mark.reinhold at oracle.com wrote:
>>> Looks good -- thanks for the further simplification.
>>>
>>> Minor editorial comments, to add what Kim and Chris noted:
>>>
>>>    - In many places you write, e.g., "Cleaner" rather than "{@code
>>>      Cleaner}".  For consistency with the rest of the package it'd be
>>>      better in most cases just to write "cleaner" or, if its nature as
>>>      a class is important, write "{@code Cleaner}".  The same goes for
>>>      Cleanable, Thread, ThreadFactory, and all other types.
>>>
>>>    - The specification of Cleaner::create() mentions
>>>      "ThreadContextClassLoader", but that's not actually a type 
>>> anywhere
>>>      in the JDK.  Suggest "{@linkplain
>>>      java.lang.Thread#getContextClassLoader context class loader}.
>>>
>>>    - In the same method, it'd be helpful to provide links into the 
>>> Thread
>>>      class (or wherever) for the concepts of access-control context and
>>>      thread locals.
>>>
>>> - Mark
>>
>