Module io.netty5.buffer
Package io.netty5.buffer.api.internal

Class ResourceSupport<I extends Resource<I>,​T extends ResourceSupport<I,​T>>

  • Type Parameters:
    I - The public interface for the resource.
    T - The concrete implementation of the resource.
    All Implemented Interfaces:
    Resource<I>, AutoCloseable
    Direct Known Subclasses:
    AdaptableBuffer
    @UnstableApi
public abstract class ResourceSupport<I extends Resource<I>,​T extends ResourceSupport<I,​T>>
extends Object
implements Resource<I>
    Internal support class for resources.

    • Constructor Detail

      • ResourceSupport

        protected ResourceSupport​(Drop<T> drop)

    • Method Detail

      • acquire

        protected final I acquire()
        Increment the reference count.

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

        Returns:
        This Resource instance.

      • createResourceClosedException

        protected abstract RuntimeException createResourceClosedException()

      • close

        public final void 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.

        Specified by:
        close in interface AutoCloseable
        Specified by:
        close in interface Resource<I extends Resource<I>>
        Throws:
        IllegalStateException - If this Resource has already been closed.

      • send

        public final Send<I> 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.

        Specified by:
        send in interface Resource<I extends Resource<I>>
        Throws:
        IllegalStateException - if this object has any outstanding acquires; that is, if this object has been acquired more times than it has been closed.

      • attachTrace

        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.
        Type Parameters:
        E - The concrete exception type.
        Parameters:
        throwable - The throwable to attach a life-cycle trace to.
        Returns:
        The given exception, which can then be thrown.

      • isOwned

        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:
        true if this object is in an owned state, otherwise false.

      • countBorrows

        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:
        The number of borrows, if any, of this object.

      • isAccessible

        public boolean isAccessible()
        Description copied from interface: Resource
        Check if this object is accessible.
        Specified by:
        isAccessible in interface Resource<I extends Resource<I>>
        Returns:
        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.

      • touch

        public I touch​(Object hint)
        Description copied from interface: Resource
        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.
        Specified by:
        touch in interface Resource<I extends Resource<I>>
        Parameters:
        hint - An optional hint about this access and its context. May be null.
        Returns:
        This resource instance.

      • prepareSend

        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:
        This resource instance in a deactivated state.

      • makeInaccessible

        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.

      • unsafeGetDrop

        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:
        The Drop object used by this reference counted object.

      • unsafeSetDrop

        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 - The new Drop object to use instead of the current one.