Top Description Fields Constructors Methods
io.netty5.buffer.internal

public abstract Class ResourceSupport<I extends io.netty5.util.Resource<I>, T extends io.netty5.buffer.internal.ResourceSupport<I, T>>

extends Object
implements Resource<I extends Resource<I>>
Class Inheritance
All Implemented Interfaces
io.netty5.util.Resource, java.lang.AutoCloseable
Known Direct Subclasses
io.netty5.buffer.DefaultCompositeBuffer, io.netty5.buffer.internal.AdaptableBuffer
Annotations
@UnstableApi
Type Parameters
<I>
The public interface for the resource.
<T>
The concrete implementation of the resource.
Imports
io.netty5.buffer.Drop, .Owned, io.netty5.util.Resource, .Send, io.netty5.util.internal.UnstableApi, java.lang.ref.Reference, java.util.Objects
Internal support class for resources.

Field Summary

Modifier and TypeField and Description
private int
acquires

private Drop<T>
drop

private final LifecycleTracer
tracer

Constructor Summary

AccessConstructor and Description
protected
ResourceSupport(Drop<T> drop)

Method Summary

Modifier and TypeMethod and Description
pack-priv static <
The type of the acquired object, given by target-typing.
T> T

Returns:

The acquired object.
acquire(ResourceSupport<?, ?>
The object we wish to acquire (increment reference count) on.
obj)

Encapsulation bypass for calling acquire() on the given object.

protected final T

Returns:

This Resource instance.
acquire()

Increment the reference count.

protected <
The concrete exception type.
E extends Throwable> E

Returns:

The given exception, which can then be thrown.
attachTrace(E
The throwable to attach a life-cycle trace to.
throwable)

Attach a trace of the life-cycle of this object as suppressed exceptions to the given throwable.

public final void
close()

Implements io.netty5.util.Resource.close.

Decrement the reference count, and dispose of the resource if the last reference is closed.
pack-priv static int

Returns:

The number of borrows, or outstanding acquires, if any, of the given object.
countBorrows(ResourceSupport<?, ?>
The object to count borrows on.
obj)

Encapsulation bypass to call countBorrows() on the given object.

protected int

Returns:

The number of borrows, if any, of this object.
countBorrows()

Count the number of borrows of this object.

protected abstract RuntimeException
createResourceClosedException()

pack-priv static LifecycleTracer

Returns:

The LifecycleTracer that is attached to the given object.
getTracer(ResourceSupport<?, ?>
The object to get the LifecycleTracer from.
obj)

Encapsulation bypass for getting the LifecycleTracer attached to the given object.

private T
impl()

public boolean
isAccessible()

Implements io.netty5.util.Resource.isAccessible.

Check if this object is accessible.
pack-priv static boolean

Returns:

true if the given object is owned, otherwise false.
isOwned(ResourceSupport<?, ?>
The object to query the ownership state on.
obj)

Encapsulation bypass to call isOwned() on the given object.

protected boolean

Returns:

true if this object is in an owned state, otherwise false.
isOwned()

Query if this object is in an "owned" state, which means no other references have been acquired to it.

protected void
makeInaccessible()

Called when this resource needs to be considered inaccessible.

protected IllegalStateException

Returns:

An IllegalStateException to be thrown when this object cannot be sent.
notSendableException()

Create an IllegalStateException with a custom message, tailored to this particular Resource instance, for when the object cannot be sent for some reason.

protected abstract Owned<T>

Returns:

This resource instance in a deactivated state.
prepareSend()

Prepare this instance for ownership transfer.

private I
self()

public final Send<I>
send()

Implements io.netty5.util.Resource.send.

Send this Resource instance to another Thread, transferring the ownership to the recipient.
public I
touch(Object
An optional hint about this access and its context. May be null.
hint)

Overrides default io.netty5.util.Resource.touch.

Record the current access location for debugging purposes.
protected Drop<T>

Returns:

The Drop object used by this reference counted object.
unsafeGetDrop()

Get access to the underlying Drop object.

protected void
unsafeSetDrop(Drop<T>
The new Drop object to use instead of the current one.
replacement)

Replace the current underlying Drop object with the given one.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

acquiresback to summary
private int acquires
dropback to summary
private Drop<T> drop
tracerback to summary
private final LifecycleTracer tracer

Constructor Detail

ResourceSupportback to summary
protected ResourceSupport(Drop<T> drop)

Method Detail

acquireback to summary
pack-priv static <T> T acquire(ResourceSupport<?, ?> obj)

Encapsulation bypass for calling acquire() on the given object.

Note

this acquire method does not check the type of the return value from acquire at compile time. The type is instead checked at runtime, and will cause a ClassCastException to be thrown if done incorrectly.

Parameters
<T>
The type of the acquired object, given by target-typing.
obj:ResourceSupport<?, ?>

The object we wish to acquire (increment reference count) on.

Returns:T

The acquired object.

Annotations
@SuppressWarnings:unchecked
acquireback to summary
protected final T acquire()

Increment the reference count.

Note, this method is not thread-safe because Resources are meant to thread-confined.

Returns:T

This Resource instance.

attachTraceback to summary
protected <E extends Throwable> E attachTrace(E throwable)

Attach a trace of the life-cycle of this object as suppressed exceptions to the given throwable.

Parameters
<E>
The concrete exception type.
throwable:E

The throwable to attach a life-cycle trace to.

Returns:E

The given exception, which can then be thrown.

closeback to summary
public final void close()

Implements io.netty5.util.Resource.close.

Decrement the reference count, and dispose of the resource if the last reference is closed.

Note, this method is not thread-safe because Resources are meant to be thread-confined.

Subclasses who wish to attach behaviour to the close action should override the makeInaccessible() method instead, or make it part of their drop implementation.

Annotations
@Override
Exceptions
IllegalStateException:
If this Resource has already been closed.
countBorrowsback to summary
pack-priv static int countBorrows(ResourceSupport<?, ?> obj)

Encapsulation bypass to call countBorrows() on the given object.

Parameters
obj:ResourceSupport<?, ?>

The object to count borrows on.

Returns:int

The number of borrows, or outstanding acquires, if any, of the given object.

countBorrowsback to summary
protected int countBorrows()

Count the number of borrows of this object. Note that even if the number of borrows is 0, this object might not be owned because there could be other restrictions involved in ownership.

Returns:int

The number of borrows, if any, of this object.

createResourceClosedExceptionback to summary
protected abstract RuntimeException createResourceClosedException()
getTracerback to summary
pack-priv static LifecycleTracer getTracer(ResourceSupport<?, ?> obj)

Encapsulation bypass for getting the LifecycleTracer attached to the given object.

Parameters
obj:ResourceSupport<?, ?>

The object to get the LifecycleTracer from.

Returns:LifecycleTracer

The LifecycleTracer that is attached to the given object.

implback to summary
private T impl()
Annotations
@SuppressWarnings:unchecked
isAccessibleback to summary
public boolean isAccessible()

Implements io.netty5.util.Resource.isAccessible.

Doc from io.netty5.util.Resource.isAccessible.

Check if this object is accessible.

Returns:boolean

true if this object is still valid and can be accessed, otherwise false if, for instance, this object has been dropped/deallocated, or been sent elsewhere.

Annotations
@Override
isOwnedback to summary
pack-priv static boolean isOwned(ResourceSupport<?, ?> obj)

Encapsulation bypass to call isOwned() on the given object.

Parameters
obj:ResourceSupport<?, ?>

The object to query the ownership state on.

Returns:boolean

true if the given object is owned, otherwise false.

isOwnedback to summary
protected boolean isOwned()

Query if this object is in an "owned" state, which means no other references have been acquired to it. This would usually be the case, since there are no public methods for acquiring references to these objects.

Returns:boolean

true if this object is in an owned state, otherwise false.

makeInaccessibleback to summary
protected void makeInaccessible()

Called when this resource needs to be considered inaccessible. This is called at the correct points, by the ResourceSupport class, when the resource is being closed or sent, and can be used to set further traps for accesses that makes accessibility checks cheap. There would normally not be any reason to call this directly from a sub-class.

notSendableExceptionback to summary
protected IllegalStateException notSendableException()

Create an IllegalStateException with a custom message, tailored to this particular Resource instance, for when the object cannot be sent for some reason.

Returns:IllegalStateException

An IllegalStateException to be thrown when this object cannot be sent.

prepareSendback to summary
protected abstract Owned<T> prepareSend()

Prepare this instance for ownership transfer. This method is called from send() in the sending thread. This method should put this resource in a deactivated state where it is no longer accessible from the currently owning thread. In this state, the resource instance should only allow a call to Owned#transferOwnership(Drop) in the recipient thread.

Returns:Owned<T>

This resource instance in a deactivated state.

selfback to summary
private I self()
Annotations
@SuppressWarnings:unchecked
sendback to summary
public final Send<I> send()

Implements io.netty5.util.Resource.send.

Send this Resource instance to another Thread, transferring the ownership to the recipient. This method can be used when the receiving thread is not known up front.

This instance immediately becomes inaccessible, and all attempts at accessing this resource will throw. Calling close() will have no effect, so this method is safe to call within a try-with-resources statement.

Annotations
@Override
Exceptions
IllegalStateException:
if this object has any outstanding acquires; that is, if this object has been acquired more times than it has been closed.
touchback to summary
public I touch(Object hint)

Overrides default io.netty5.util.Resource.touch.

Doc from io.netty5.util.Resource.touch.

Record the current access location for debugging purposes. This information may be included if the resource throws a life-cycle related exception, or if it leaks. If this resource has already been closed, then this method has no effect.

Parameters
hint:Object

An optional hint about this access and its context. May be null.

Returns:I

This resource instance.

Annotations
@Override
unsafeGetDropback to summary
protected Drop<T> unsafeGetDrop()

Get access to the underlying Drop object. This method is unsafe because it opens the possibility of bypassing and overriding resource lifetimes.

Returns:Drop<T>

The Drop object used by this reference counted object.

unsafeSetDropback to summary
protected void unsafeSetDrop(Drop<T> replacement)

Replace the current underlying Drop object with the given one. This method is unsafe because it opens the possibility of bypassing and overriding resource lifetimes.

Parameters
replacement:Drop<T>

The new Drop object to use instead of the current one.