Package io.deephaven.base.reference

Class PooledObjectReference<REFERENT_TYPE>

java.lang.Object
io.deephaven.base.reference.PooledObjectReference<REFERENT_TYPE>
All Implemented Interfaces:
SimpleReference<REFERENT_TYPE>
public abstract class PooledObjectReference<REFERENT_TYPE> extends Object implements SimpleReference<REFERENT_TYPE>
SimpleReference implementation with built-in reference-counting and pooling support.

  • Constructor Details

    • PooledObjectReference

      protected PooledObjectReference(@NotNull REFERENT_TYPE referent)
      Construct a new PooledObjectReference to the supplied referent.
      Parameters:
      referent - The referent of this reference

  • Method Details

    • get

      public final REFERENT_TYPE get()
      Get the referent. It is an error to call this method if the caller does not have any outstanding permits. Callers are encouraged to use this in the try block of a try-finally pattern: 
       if (!ref.acquire()) {
     return;
 }
 try {
     doSomethingWith(ref.get());
 } finally {
     ref.release();
 }
      Specified by:
      get in interface SimpleReference<REFERENT_TYPE>
      Returns:
      The referent if this reference has not been cleared, null otherwise (which implies an error by the caller)

    • acquire

      public final boolean acquire()
      Acquire an active use permit. Callers should pair this with a corresponding release(), ideally with a try-finally pattern: 
       if (!ref.acquire()) {
     return;
 }
 try {
     doSomethingWith(ref.get());
 } finally {
     ref.release();
 }
      Returns:
      Whether a permit was acquired

    • acquireIfAvailable

      public final boolean acquireIfAvailable()
      Acquire an active use permit if this has not been cleared. This is useful in situations where callers want to fail-fast and don't need to guarantee reentrancy. Callers should pair this with a corresponding release(), ideally with a try-finally pattern: 
       if (!ref.acquireIfAvailable()) {
     return;
 }
 try {
     doSomethingWith(ref.get());
 } finally {
     ref.release();
 }
      Returns:
      Whether a permit was acquired

    • acquireAndGet

      @Nullable public final REFERENT_TYPE acquireAndGet()
      Acquire an active use permit and return the referent, if possible. Callers should pair this with a corresponding release(), ideally with a try-finally pattern: 
       final Object obj;
 if ((obj = ref.acquireAndGet()) == null) {
     return;
 }
 try {
     doSomethingWith(obj);
 } finally {
     ref.release();
 }
      Returns:
      The referent, or null if no permit could be acquired

    • release

      public final void release()
      Release a single active use permit. It is a serious error to release more permits than acquired. Callers are encouraged to use this in the finally block of a try-finally pattern: 
       if (!ref.acquire()) {
     return;
 }
 try {
     doSomethingWith(ref.get());
 } finally {
     ref.release();
 }

    • clear

      public final void clear()
      Clear this reference (and return its referent to the pool) when it no longer has any outstanding permits, which may mean immediately if the number of outstanding permits is already zero. All invocations after the first will have no effect.
      Specified by:
      clear in interface SimpleReference<REFERENT_TYPE>

    • returnReferentToPool

      protected abstract void returnReferentToPool(@NotNull REFERENT_TYPE referent)
      Return the referent to the pool.
      Parameters:
      referent - The referent to return