public abstract class

CloseableReference

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

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.CloseableRefType  
interface CloseableReference.LeakHandler  
Constants
int REF_TYPE_DEFAULT
int REF_TYPE_FINALIZER
int REF_TYPE_NOOP
int REF_TYPE_REF_COUNT
Fields
protected boolean mIsClosed
protected final CloseableReference.LeakHandler mLeakHandler
protected final SharedReference<T> mSharedReference
protected final Throwable mStacktrace
Protected Constructors
CloseableReference(SharedReference<T> sharedReference, CloseableReference.LeakHandler leakHandler, Throwable stacktrace)
CloseableReference(T t, ResourceReleaser<T> resourceReleaser, CloseableReference.LeakHandler leakHandler, Throwable stacktrace)
Public Methods
abstract 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.
int getValueHash()
Method used for tracking Closeables pointed by CloseableReference.
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 <T> CloseableReference<T> of(T t, ResourceReleaser<T> resourceReleaser, CloseableReference.LeakHandler leakHandler)
static <T> CloseableReference<T> of(T t, ResourceReleaser<T> resourceReleaser, CloseableReference.LeakHandler leakHandler, Throwable stacktrace)
Constructs a CloseableReference (wrapping a SharedReference) of T with provided ResourceReleaser and a custom handler that's run if a leak is detected in the finalizer.
static <T extends Closeable> CloseableReference<T> of(T t, CloseableReference.LeakHandler leakHandler)
Constructs a CloseableReference with a custom CloseableReference.LeakHandler that's run if a reference is not closed when the finalizer is called.
static void setDisableCloseableReferencesForBitmaps(int bitmapCloseableRefType)
static boolean useGc()
Protected Methods
void finalize()
[Expand]
Inherited Methods
From class java.lang.Object
From interface java.io.Closeable
From interface java.lang.AutoCloseable

Constants

public static final int REF_TYPE_DEFAULT

Constant Value: 0 (0x00000000)

public static final int REF_TYPE_FINALIZER

Constant Value: 1 (0x00000001)

public static final int REF_TYPE_NOOP

Constant Value: 3 (0x00000003)

public static final int REF_TYPE_REF_COUNT

Constant Value: 2 (0x00000002)

Fields

protected boolean mIsClosed

protected final CloseableReference.LeakHandler mLeakHandler

protected final SharedReference<T> mSharedReference

protected final Throwable mStacktrace

Protected Constructors

protected CloseableReference (SharedReference<T> sharedReference, CloseableReference.LeakHandler leakHandler, Throwable stacktrace)

protected CloseableReference (T t, ResourceReleaser<T> resourceReleaser, CloseableReference.LeakHandler leakHandler, Throwable stacktrace)

Public Methods

public abstract 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 int getValueHash ()

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

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 CloseableReference<T> of (T t, ResourceReleaser<T> resourceReleaser, CloseableReference.LeakHandler leakHandler)

public static CloseableReference<T> of (T t, ResourceReleaser<T> resourceReleaser, CloseableReference.LeakHandler leakHandler, Throwable stacktrace)

Constructs a CloseableReference (wrapping a SharedReference) of T with provided ResourceReleaser and a custom handler that's run if a leak is detected in the finalizer. If t is null, this will just return null.

public static CloseableReference<T> of (T t, CloseableReference.LeakHandler leakHandler)

Constructs a CloseableReference with a custom CloseableReference.LeakHandler that's run if a reference is not closed when the finalizer is called.

Returns null if the parameter is null.

public static void setDisableCloseableReferencesForBitmaps (int bitmapCloseableRefType)

public static boolean useGc ()

Protected Methods

protected void finalize ()

Throws
Throwable