Interface Retainable

All Known Subinterfaces:
Content.Chunk, RetainableByteBuffer, RetainableByteBuffer.Mutable
All Known Implementing Classes:
AbstractRetainableByteBuffer, ArrayByteBufferPool.Tracking.TrackedBuffer, Content.Chunk.Empty, Retainable.ReferenceCounter, Retainable.Wrapper, RetainableByteBuffer.Abstract, RetainableByteBuffer.DynamicCapacity, RetainableByteBuffer.EmptyRetainableByteBuffer, RetainableByteBuffer.FixedCapacity, RetainableByteBuffer.NonRetainableByteBuffer, RetainableByteBuffer.Pooled, RetainableByteBuffer.Wrapper, Stream.Data, Trailers

public interface Retainable

A reference counted resource, for example one that is borrowed from a pool, that may be retained an additional number of times, and released a correspondent number of times, over its lifecycle.

The resource is typically implicitly retained when it is first created. It may be retained more times (thus incrementing its reference count) and released (thus decrementing its reference count), until the reference count goes to zero.

Idiomatic usage

The general rules to use Retainable objects are the following:

  1. If the Retainable has been obtained by calling a method, and the caller code consumes it, then the caller code must call release().
  2. If the Retainable has been obtained by caller2 by calling a method, and caller2 returns it without consuming it to caller1, then caller2 must not call release(), since caller1 will.
  3. If the Retainable has been obtained as a method argument, the receiver code must either:
    1. Consume the Retainable synchronously within the method, in which case release() must not be called.
    2. Pass the Retainable to some other method, in which case release() must not be called.
    3. Store away the Retainable for later or asynchronous processing, for example storing it in containers such as Collections, or capturing it in a lambda that is passed to another thread, etc., in which case retain() must be called and a mechanism to call release() later or asynchronously for this additional retain() must be arranged.
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static class 
    A reference count implementation for a Retainable resource.
    static class 
    A wrapper of Retainable instances.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Retainable
     
  • Method Summary

    Modifier and Type
    Method
    Description
    default boolean
    Returns whether this resource is referenced counted by calls to retain() and release().
    default int
    Get the retained count.
    default boolean
    Returns whether retain() has been called at least one more time than release().
    default boolean
    Releases this resource, potentially decrementing a reference count (if any).
    static <R extends Retainable>
    R
    release(R retainable)
    Convenience method that replaces code like:
    default void
    Retains this resource, potentially incrementing a reference count if there are resources that will be released.
  • Field Details

    • NON_RETAINABLE

      static final Retainable NON_RETAINABLE
  • Method Details

    • canRetain

      default boolean canRetain()

      Returns whether this resource is referenced counted by calls to retain() and release().

      Implementations may decide that special resources are not not referenced counted (for example, static constants) so calling retain() is a no-operation, and calling release() on those special resources is a no-operation that always returns true.

      Returns:
      true if calls to retain() are reference counted.
    • isRetained

      default boolean isRetained()

      Returns whether retain() has been called at least one more time than release().

      Returns:
      whether this buffer is retained
    • retain

      default void retain()

      Retains this resource, potentially incrementing a reference count if there are resources that will be released.

    • release

      default boolean release()

      Releases this resource, potentially decrementing a reference count (if any).

      Returns:
      true when the reference count goes to zero or if there was no reference count, false otherwise.
    • getRetained

      default int getRetained()

      Get the retained count. This value is volatile and should only be used for informational/debugging purposes.

      Returns:
      the retained count
    • release

      static <R extends Retainable> R release(R retainable)
      Convenience method that replaces code like:
      
         if (buffer != null)
         {
             buffer.release();
             buffer = null;
         }
       
       
      with:
      
         buffer = Retainable.release(buffer);
       
       
      Type Parameters:
      R - The type of the retainable
      Parameters:
      retainable - The retainable to release, if not null.
      Returns:
      always returns null