public final 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 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.
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.
Protected Methods
void finalize()
[Expand]
Inherited Methods
From class java.lang.Object
From interface java.io.Closeable
From interface java.lang.AutoCloseable

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 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.

Protected Methods

protected void finalize ()

Throws
Throwable