Package io.netty5.buffer.api

Class BufferHolder<T extends BufferHolder<T>>

  • Type Parameters:
    T - The concrete BufferHolder type.
    All Implemented Interfaces:
    Resource<T>, AutoCloseable
    Direct Known Subclasses:
    BufferRef
    public abstract class BufferHolder<T extends BufferHolder<T>>
extends Object
implements Resource<T>
    The BufferHolder is an abstract class that simplifies the implementation of objects that themselves contain a Buffer instance.

    The BufferHolder can only hold on to a single buffer, so objects and classes that need to hold on to multiple buffers will have to do their implementation from scratch, though they can use the code of the BufferHolder as inspiration. Alternatively, multiple buffers can be composed into a single buffer, which can then be put in a buffer holder.

    If you just want an object that is a reference to a buffer, then the BufferRef can be used for that purpose. If you have an advanced use case where you wish to implement Resource, and tightly control lifetimes, then ResourceSupport can be of help.

    • Constructor Detail

      • BufferHolder

        protected BufferHolder​(Buffer buf)
        Create a new BufferHolder to hold the given buffer.
        Parameters:
        buf - The buffer to be held by this holder.

      • BufferHolder

        protected BufferHolder​(Send<Buffer> send)
        Create a new BufferHolder to hold the buffer received from the given Send.

        The BufferHolder will then be holding exclusive ownership of the buffer.

        Parameters:
        send - The buffer to be held by this holder.

    • Method Detail

      • close

        public void close()
        Description copied from interface: Resource
        Close the resource, making it inaccessible.

        Note, this method is not thread-safe unless otherwise specified.

        Specified by:
        close in interface AutoCloseable
        Specified by:
        close in interface Resource<T extends BufferHolder<T>>

      • send

        public Send<T> send()
        Description copied from interface: Resource
        Send this object instance to another Thread, transferring the ownership to the recipient.

        The object must be in a state where it can be sent, which includes at least being accessible.

        When sent, this instance will immediately become inaccessible, as if by closing it. All attempts at accessing an object that has been sent, even if that object has not yet been received, should cause an exception to be thrown.

        Calling Resource.close() on an object that has been sent will have no effect, so this method is safe to call within a try-with-resources statement.

        Specified by:
        send in interface Resource<T extends BufferHolder<T>>

      • replaceBuffer

        protected final void replaceBuffer​(Send<Buffer> send)
        Replace the underlying referenced buffer with the given buffer.

        This method is protected to permit advanced use cases of BufferHolder sub-class implementations.

        Note: This method closes the current buffer, and takes exclusive ownership of the received buffer.

        The buffer assignment is performed using a plain store.

        Parameters:
        send - The new Buffer instance that is replacing the currently held buffer.

      • replaceBufferVolatile

        protected final void replaceBufferVolatile​(Send<Buffer> send)
        Replace the underlying referenced buffer with the given buffer.

        This method is protected to permit advanced use cases of BufferHolder sub-class implementations.

        Note: this method closes the current buffer, and takes exclusive ownership of the received buffer.

        The buffer assignment is performed using a volatile store.

        Parameters:
        send - The Send with the new Buffer instance that is replacing the currently held buffer.

      • getBuffer

        protected final Buffer getBuffer()
        Access the held Buffer instance.

        The access is performed using a plain load.

        Returns:
        The Buffer instance being held by this buffer holder.

      • getBufferVolatile

        protected final Buffer getBufferVolatile()
        Access the held Buffer instance.

        The access is performed using a volatile load.

        Returns:
        The Buffer instance being held by this buffer holder.

      • isAccessible

        public boolean isAccessible()
        Description copied from interface: Resource
        Check if this object is accessible.
        Specified by:
        isAccessible in interface Resource<T extends BufferHolder<T>>
        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 T 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<T extends BufferHolder<T>>
        Parameters:
        hint - An optional hint about this access and its context. May be null.
        Returns:
        This resource instance.

      • equals

        public boolean equals​(Object other)
        This implementation of the equals operation is restricted to work only with instances of the same class. The reason for that is that Netty library already has a number of classes that extend BufferHolder and override equals method with an additional comparison logic, and we need the symmetric property of the equals operation to be preserved.
        Overrides:
        equals in class Object
        Parameters:
        other - The reference object with which to compare.
        Returns:
        true if this object is the same as the obj argument; false otherwise.

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object