Class DisposableReference<R>

java.lang.Object

java.lang.ref.Reference<R>

java.lang.ref.WeakReference<R>

org.microbean.bean.DisposableReference<R>

Type Parameters:

R - the type of the reference

All Implemented Interfaces:

AutoCloseable

public final class DisposableReference<R>
extends WeakReference<R>
implements AutoCloseable

An AutoCloseable WeakReference that formally disposes of referents after they have been cleared by the Java Virtual Machine during garbage collection.

Note that garbage collection may never happen.

Author:

Laird Nelson

See Also:

• DisposableReference(Object, Consumer)

Constructor Summary

Constructors

Constructor	Description
DisposableReference(R referent, Consumer<? super R> disposer)	Creates a new DisposableReference.

Method Summary

Modifier and Type	Method	Description
final void	close()	Calls Reference.enqueue().
final boolean	closed()	Calls refersTo(null) and returns the result.
final boolean	dispose()	If there has been no prior successful invocation of this method, calls the accept(Object) method on the Consumer representing the disposer supplied at construction time, thus notionally disposing the referent supplied at construction time, and returns true.
final boolean	disposed()	Returns true if and only if there has been a prior successful invocation of dispose() that returned true.

Methods inherited from class java.lang.ref.Reference

clear, clone, enqueue, get, isEnqueued, reachabilityFence, refersTo

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

DisposableReference

public DisposableReference(R referent,
 Consumer<? super R> disposer)

Creates a new DisposableReference.

Parameters:

referent - the referent; may be null

disposer - a thread-safe Consumer whose accept(Object) method, which must be idempotent, will be invoked from a separate thread to dispose of the referent after it has been cleared by the Java Virtual Machine during garbage collection; may be null in which case no destruction will take place

Method Details

close

public final void close()

Calls Reference.enqueue().

Specified by:

close in interface AutoCloseable

See Also:

• Reference.enqueue()

closed

public final boolean closed()

Calls refersTo(null) and returns the result.

Returns:

the result of an invocation of refersTo(null)

See Also:

• Reference.refersTo(Object)

dispose

public final boolean dispose()

If there has been no prior successful invocation of this method, calls the accept(Object) method on the Consumer representing the disposer supplied at construction time, thus notionally disposing the referent supplied at construction time, and returns true.

Destruction does not imply closing, and closing does not imply destruction (though it normally will eventually lead to it).

If destruction does not result in any RuntimeException or Error being thrown, then calling this method again, from any thread, will have no effect and it will return false.

If the first invocation of this method from any thread succeeds, then it will return true, and all other invocations of this method from any thread will return false, and will have no effect.

This method is often called from a thread dedicated to disposing enqueued DisposableReferences, so the Consumer supplied at construction time must be thread-safe.

Returns:

true if this invocation of this method caused destruction to happen successfully; false in all other cases

Throws:

RuntimeException - if an invocation of the accept(Object) method on the Consumer supplied at construction time fails

See Also:

• DisposableReference(Object, Consumer)

Idempotency:

This method is idempotent.

Thread Safety:

This method is safe for concurrent use by multiple threads.

disposed

public final boolean disposed()

Returns true if and only if there has been a prior successful invocation of dispose() that returned true.

Returns:

true if and only if there has been a prior successful invocation of dispose() that returned true

See Also:

• dispose()