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

Public Constructors
CloseableReference()
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.
abstract CloseableReference<T> cloneOrNull()
abstract 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.
abstract T get()
Returns the underlying Closeable if this reference is not closed yet.
abstract SharedReference<T> getUnderlyingReferenceTestOnly()
A test-only method to get the underlying references.
abstract int getValueHash()
Method used for tracking Closeables pointed by CloseableReference.
abstract 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 setUseFinalizers(boolean useFinalizers)
[Expand]
Inherited Methods
From class java.lang.Object
From interface java.io.Closeable
From interface java.lang.AutoCloseable

Public Constructors

public CloseableReference ()

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 abstract CloseableReference<T> cloneOrNull ()

public abstract 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 abstract T get ()

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

public abstract SharedReference<T> getUnderlyingReferenceTestOnly ()

A test-only method to get the underlying references.

DO NOT USE in application code.

public abstract int getValueHash ()

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

public abstract 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 setUseFinalizers (boolean useFinalizers)