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:

If the Retainable has been obtained by calling a method, and the caller code consumes it, then the caller code must call release().
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.
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 java.util.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 and Inner Type Summary

Modifier and Type	Class and Description
public static class	Retainable.ReferenceCounter A reference count implementation for a `Retainable` resource.
public static class	Retainable.Wrapper A wrapper of `Retainable` instances.

Method Summary

Modifier and Type	Method and Description
public default boolean	Returns: true if calls to `retain()` are reference counted. canRetain() Returns whether this resource is referenced counted by calls to `retain()` and `release()`.
public default boolean	Returns: `true` when the reference count goes to zero or if there was no reference count, `false` otherwise. release() Releases this resource, potentially decrementing a reference count (if any).
public default void	retain() Retains this resource, potentially incrementing a reference count if there are resources that will be released.

Method Detail

canRetain back to summary

canRetain	back to summary
public 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:boolean true if calls to `retain()` are reference counted.

public 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:boolean: true if calls to retain() are reference counted.

release back to summary

release	back to summary
public default boolean release() Releases this resource, potentially decrementing a reference count (if any). Returns:boolean `true` when the reference count goes to zero or if there was no reference count, `false` otherwise.

public default boolean release()

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

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

retain	back to summary
public default void retain() Retains this resource, potentially incrementing a reference count if there are resources that will be released.

org.eclipse.jetty.io back to summary

public Class Retainable.ReferenceCounter

Class Inheritance

extends Object
implements Retainable

java.lang.Object
org.eclipse.jetty.io.Retainable.ReferenceCounter

All Implemented Interfaces

org.eclipse.jetty.io.Retainable

A reference count implementation for a Retainable resource.

The reference count is initialized to 1 when the resource is created, and therefore it is implicitly retained and needs a call to release().

Additional calls to retain() must be matched by correspondent calls to release().

When the reference count goes to zero, the resource may be pooled. When the resource is acquired from the pool, acquire() should be called to set the reference count to 1.

Field Summary

Modifier and Type	Field and Description
private final AtomicInteger	references

Constructor Summary

Access	Constructor and Description
public	ReferenceCounter()
protected	ReferenceCounter(int initialCount)

Method Summary

Modifier and Type	Method and Description
public void	acquire() Updates the reference count from `0` to `1`.
public boolean	canRetain() Overrides default org.eclipse.jetty.io.Retainable.canRetain. Returns whether this resource is referenced counted by calls to `retain()` and `release()`.
public int	get() Returns: the current reference count
public boolean	Returns: whether this buffer is retained isRetained() Returns whether `retain()` has been called at least one more time than `release()`.
public boolean	release() Overrides default org.eclipse.jetty.io.Retainable.release. Releases this resource, potentially decrementing a reference count (if any).
public void	retain() Overrides default org.eclipse.jetty.io.Retainable.retain. Retains this resource, potentially incrementing a reference count if there are resources that will be released.
public String	toString() Overrides java.lang.Object.toString. Returns a string representation of the object.
public boolean	tryRetain()

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

Field Detail

references	back to summary
private final AtomicInteger references

Constructor Detail

ReferenceCounter	back to summary
public ReferenceCounter()

ReferenceCounter	back to summary
protected ReferenceCounter(int initialCount)

Method Detail

acquire back to summary

acquire	back to summary
public void acquire() Updates the reference count from `0` to `1`. This method should only be used when this resource is acquired from a pool.

public void acquire()

Updates the reference count from 0 to 1.

This method should only be used when this resource is acquired from a pool.

canRetain back to summary

canRetain	back to summary
public boolean canRetain() Overrides default org.eclipse.jetty.io.Retainable.canRetain. Doc from org.eclipse.jetty.io.Retainable.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:boolean true if calls to `retain()` are reference counted. Annotations @Override

public boolean canRetain()

Overrides default org.eclipse.jetty.io.Retainable.canRetain.

Doc from org.eclipse.jetty.io.Retainable.canRetain.

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

Returns:boolean

true if calls to retain() are reference counted.

Annotations

@Override

get	back to summary
public int get() Returns:int the current reference count

isRetained back to summary

isRetained	back to summary
public boolean isRetained() Returns whether `retain()` has been called at least one more time than `release()`. Returns:boolean whether this buffer is retained

public boolean isRetained()

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

Returns:boolean: whether this buffer is retained

release back to summary

release	back to summary
public boolean release() Overrides default org.eclipse.jetty.io.Retainable.release. Doc from org.eclipse.jetty.io.Retainable.release. Releases this resource, potentially decrementing a reference count (if any). Returns:boolean `true` when the reference count goes to zero or if there was no reference count, `false` otherwise. Annotations @Override

public boolean release()

Overrides default org.eclipse.jetty.io.Retainable.release.

Doc from org.eclipse.jetty.io.Retainable.release.

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

Returns:boolean

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

Annotations

@Override

retain	back to summary
public void retain() Overrides default org.eclipse.jetty.io.Retainable.retain. Doc from org.eclipse.jetty.io.Retainable.retain. Retains this resource, potentially incrementing a reference count if there are resources that will be released. Annotations @Override

retain

back to summary

public void retain()

Overrides default org.eclipse.jetty.io.Retainable.retain.

Doc from org.eclipse.jetty.io.Retainable.retain.

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

Annotations

@Override

toString back to summary

toString	back to summary
public String toString() Overrides java.lang.Object.toString. Doc from java.lang.Object.toString. Returns a string representation of the object. Satisfying this method's contract implies a non-`null` result must be returned. Returns:String a string representation of the object Annotations @Override

public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Returns:String

a string representation of the object

Annotations

@Override

tryRetain	back to summary
public boolean tryRetain()

org.eclipse.jetty.io back to summary

public Class Retainable.Wrapper

Class Inheritance

extends Object
implements Retainable

java.lang.Object
org.eclipse.jetty.io.Retainable.Wrapper

All Implemented Interfaces

org.eclipse.jetty.io.Retainable

Known Direct Subclasses

org.eclipse.jetty.io.RetainableByteBuffer.Wrapper

A wrapper of Retainable instances.

Field Summary

Modifier and Type	Field and Description
private final Retainable	wrapped

Constructor Summary

Access	Constructor and Description
public	Wrapper(Retainable wrapped)

Method Summary

Modifier and Type	Method and Description
public boolean	canRetain() Overrides default org.eclipse.jetty.io.Retainable.canRetain. Returns whether this resource is referenced counted by calls to `retain()` and `release()`.
public Retainable	getWrapped()
public boolean	release() Overrides default org.eclipse.jetty.io.Retainable.release. Releases this resource, potentially decrementing a reference count (if any).
public void	retain() Overrides default org.eclipse.jetty.io.Retainable.retain. Retains this resource, potentially incrementing a reference count if there are resources that will be released.
public String	toString() Overrides java.lang.Object.toString. Returns a string representation of the object.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

Field Detail

wrapped	back to summary
private final Retainable wrapped

wrapped

back to summary

private final Retainable wrapped

Constructor Detail

Wrapper	back to summary
public Wrapper(Retainable wrapped)

Wrapper

back to summary

public Wrapper(Retainable wrapped)

Method Detail

canRetain back to summary

canRetain	back to summary
public boolean canRetain() Overrides default org.eclipse.jetty.io.Retainable.canRetain. Doc from org.eclipse.jetty.io.Retainable.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:boolean true if calls to `retain()` are reference counted. Annotations @Override

public boolean canRetain()

Overrides default org.eclipse.jetty.io.Retainable.canRetain.

Doc from org.eclipse.jetty.io.Retainable.canRetain.

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

Returns:boolean

true if calls to retain() are reference counted.

Annotations

@Override

getWrapped	back to summary
public Retainable getWrapped()

getWrapped

back to summary

public Retainable getWrapped()

release back to summary

release	back to summary
public boolean release() Overrides default org.eclipse.jetty.io.Retainable.release. Doc from org.eclipse.jetty.io.Retainable.release. Releases this resource, potentially decrementing a reference count (if any). Returns:boolean `true` when the reference count goes to zero or if there was no reference count, `false` otherwise. Annotations @Override

public boolean release()

Overrides default org.eclipse.jetty.io.Retainable.release.

Doc from org.eclipse.jetty.io.Retainable.release.

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

Returns:boolean

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

Annotations

@Override

retain	back to summary
public void retain() Overrides default org.eclipse.jetty.io.Retainable.retain. Doc from org.eclipse.jetty.io.Retainable.retain. Retains this resource, potentially incrementing a reference count if there are resources that will be released. Annotations @Override

retain

back to summary

public void retain()

Overrides default org.eclipse.jetty.io.Retainable.retain.

Doc from org.eclipse.jetty.io.Retainable.retain.

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

Annotations

@Override

toString back to summary

toString	back to summary
public String toString() Overrides java.lang.Object.toString. Doc from java.lang.Object.toString. Returns a string representation of the object. Satisfying this method's contract implies a non-`null` result must be returned. Returns:String a string representation of the object Annotations @Override

public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Returns:String

a string representation of the object

Annotations

@Override

public Interface Retainable

Idiomatic usage

Nested and Inner Type Summary

Method Summary

Method Detail

public Class Retainable.ReferenceCounter

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public Class Retainable.Wrapper

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail