public abstract class

CloseableReference

extends Object
implements Closeable Cloneable
java.lang.Object
   ↳ com.facebook.common.references.CloseableReference<T>

Class Overview

A smart pointer-like class for Java.

This class allows reference-counting semantics in a Java-friendlier way. A single object can have any number of CloseableReferences pointing to it. When all of these have been closed, the object either has its close() method called, if it implements Closeable, or its designated release(T), if it does not.

Callers can construct a CloseableReference wrapping a Closeable with:

 Closeable foo;
 CloseableReference c = CloseableReference.of(foo);
 

Objects that do not implement Closeable can still use this class, but must supply a ResourceReleaser:

 Object foo;
 ResourceReleaser<Object> fooReleaser;
 CloseableReference c = CloseableReference.of(foo, fooReleaser);
 
 

When making a logical copy, callers should call clone():

 CloseableReference copy = c.clone();
 

When each copy of CloseableReference is no longer needed, close should be called:

 copy.close();
 c.close();
 

As with any Closeable, try-finally semantics may be needed to ensure that close is called.

Do not rely upon the finalizer; the purpose of this class is for expensive resources to be released without waiting for the garbage collector. The finalizer will log an error if the close method has not been called.

Summary

Nested Classes
interface CloseableReference.UnclosedReferenceListener  
Fields
protected boolean mIsClosed
protected Throwable mRelevantTrace
protected final SharedReference<T> mSharedReference
Public Methods
synchronized CloseableReference<T> clone()
Returns a new CloseableReference to the same underlying SharedReference.
static <T> CloseableReference<T> cloneOrNull(CloseableReference<T> ref)
Returns the cloned reference if valid, null otherwise.
static <T> List<CloseableReference<T>> cloneOrNull(Collection<CloseableReference<T>> refs)
Clones a collection of references and returns a list.
synchronized CloseableReference<T> cloneOrNull()
void close()
Closes this CloseableReference.
static void closeSafely(Iterable<? extends CloseableReference<?>> references)
Closes the references in the iterable handling null.
static void closeSafely(CloseableReference<?> ref)
Closes the reference handling null.
synchronized T get()
Returns the underlying Closeable if this reference is not closed yet.
synchronized SharedReference<T> getUnderlyingReferenceTestOnly()
A test-only method to get the underlying references.
synchronized int getValueHash()
Method used for tracking Closeables pointed by CloseableReference.
static boolean isUnclosedTrackingEnabled()
Returns whether CloseableReference instances are currently gathering obtain/clone traces for the purpose of unclosed reference tracking.
synchronized boolean isValid()
Checks if this closable-reference is valid i.e.
static boolean isValid(CloseableReference<?> ref)
Checks if the closable-reference is valid i.e.
static <T extends Closeable> CloseableReference<T> of(T t)
Constructs a CloseableReference.
static <T> CloseableReference<T> of(T t, ResourceReleaser<T> resourceReleaser)
Constructs a CloseableReference (wrapping a SharedReference) of T with provided ResourceReleaser.
static void setUnclosedReferenceListener(CloseableReference.UnclosedReferenceListener unclosedReferenceListener)
Set a listener to be notified when a CloseableReference is finalized by GC without it being explicitly closed beforehand.
void setUnclosedRelevantTrance(Throwable relevantTrance)
If the obtained/cloned trace is not valuable in some instances, you can set a more relevant trace here, for the purpose of unclosed reference tracking.
static void setUseFinalizers(boolean useFinalizers)
[Expand]
Inherited Methods
From class java.lang.Object
From interface java.io.Closeable
From interface java.lang.AutoCloseable

Fields

protected boolean mIsClosed

protected Throwable mRelevantTrace

protected final SharedReference<T> mSharedReference

Public Methods

public synchronized CloseableReference<T> clone ()

Returns a new CloseableReference to the same underlying SharedReference. The SharedReference ref-count is incremented.

public static CloseableReference<T> cloneOrNull (CloseableReference<T> ref)

Returns the cloned reference if valid, null otherwise.

Parameters
ref the reference to clone

public static List<CloseableReference<T>> cloneOrNull (Collection<CloseableReference<T>> refs)

Clones a collection of references and returns a list. Returns null if the list is null. If the list is non-null, clones each reference. If a reference cannot be cloned due to already being closed, the list will contain a null value in its place.

Parameters
refs the references to clone
Returns
  • the list of cloned references or null

public synchronized CloseableReference<T> cloneOrNull ()

public void close ()

Closes this CloseableReference.

Decrements the reference count of the underlying object. If it is zero, the object will be released.

This method is idempotent. Calling it multiple times on the same instance has no effect.

public static void closeSafely (Iterable<? extends CloseableReference<?>> references)

Closes the references in the iterable handling null.

Parameters
references the reference to close

public static void closeSafely (CloseableReference<?> ref)

Closes the reference handling null.

Parameters
ref the reference to close

public synchronized T get ()

Returns the underlying Closeable if this reference is not closed yet. Otherwise IllegalStateException is thrown.

public synchronized SharedReference<T> getUnderlyingReferenceTestOnly ()

A test-only method to get the underlying references.

DO NOT USE in application code.

public synchronized int getValueHash ()

Method used for tracking Closeables pointed by CloseableReference. Use only for debugging and logging.

public static boolean isUnclosedTrackingEnabled ()

Returns whether CloseableReference instances are currently gathering obtain/clone traces for the purpose of unclosed reference tracking.

public synchronized boolean isValid ()

Checks if this closable-reference is valid i.e. is not closed.

Returns
  • true if the closeable reference is valid

public static boolean isValid (CloseableReference<?> ref)

Checks if the closable-reference is valid i.e. is not null, and is not closed.

Returns
  • true if the closeable reference is valid

public static CloseableReference<T> of (T t)

Constructs a CloseableReference.

Returns null if the parameter is null.

public static CloseableReference<T> of (T t, ResourceReleaser<T> resourceReleaser)

Constructs a CloseableReference (wrapping a SharedReference) of T with provided ResourceReleaser. If t is null, this will just return null.

public static void setUnclosedReferenceListener (CloseableReference.UnclosedReferenceListener unclosedReferenceListener)

Set a listener to be notified when a CloseableReference is finalized by GC without it being explicitly closed beforehand.

public void setUnclosedRelevantTrance (Throwable relevantTrance)

If the obtained/cloned trace is not valuable in some instances, you can set a more relevant trace here, for the purpose of unclosed reference tracking.

public static void setUseFinalizers (boolean useFinalizers)