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	Retainable.ReferenceCounter	A reference count implementation for a Retainable resource.
static class	Retainable.Wrapper	A wrapper of Retainable instances.

Field Summary

Fields

Modifier and Type	Field	Description
static final Retainable	NON_RETAINABLE

Method Summary

Modifier and Type	Method	Description
default boolean	canRetain()	Returns whether this resource is referenced counted by calls to retain() and release().
default int	getRetained()	Get the retained count.
default boolean	isRetained()	Returns whether retain() has been called at least one more time than release().
default boolean	release()	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	retain()	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