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

Summary

Public Methods
synchronized CloseableReference<T> clone()
Returns a new CloseableReference to the same underlying SharedReference.
synchronized CloseableReference<T> cloneOrNull()
static <T> List<CloseableReference<T>> cloneOrNull(Collection<CloseableReference<T>> refs)
Clones a collection of references and returns a list.
static <T> CloseableReference<T> cloneOrNull(CloseableReference<T> ref)
Returns the cloned reference if valid, null otherwise.
void close()
Closes this CloseableReference.
static void closeSafely(CloseableReference<?> ref)
Closes the reference handling null.
static void closeSafely(Iterable<? extends CloseableReference<?>> references)
Closes the references in the iterable 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 isValid(CloseableReference<?> ref)
Checks if the closable-reference is valid i.e.
synchronized boolean isValid()
Checks if this closable-reference is valid i.e.
static <T> CloseableReference<T> of(T t, ResourceReleaser<T> resourceReleaser)
Constructs a CloseableReference (wrapping a SharedReference) of T with provided ResourceReleaser.
static <T extends Closeable> CloseableReference<T> of(T t)
Constructs a CloseableReference.
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 synchronized CloseableReference<T> cloneOrNull ()

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

Returns the cloned reference if valid, null otherwise.

Parameters
ref the reference to clone

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 (CloseableReference<?> ref)

Closes the reference handling null.

Parameters
ref the reference to close

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

Closes the references in the iterable handling null.

Parameters
references 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 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 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 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)

Constructs a CloseableReference.

Returns null if the parameter is null.

Protected Methods

protected void finalize ()

Throws
Throwable