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

Class BufferHolder<T extends io.netty5.util.Resource<T>>

  • Type Parameters:
    T - The concrete BufferHolder type.
    All Implemented Interfaces:
    io.netty5.util.Resource<T>, AutoCloseable
    Direct Known Subclasses:
    BufferRef
    public abstract class BufferHolder<T extends io.netty5.util.Resource<T>>
extends Object
implements io.netty5.util.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​(io.netty5.util.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()
        Specified by:
        close in interface AutoCloseable
        Specified by:
        close in interface io.netty5.util.Resource<T extends io.netty5.util.Resource<T>>

      • send

        public io.netty5.util.Send<T> send()
        Specified by:
        send in interface io.netty5.util.Resource<T extends io.netty5.util.Resource<T>>

      • receive

        protected abstract T receive​(Buffer buf)
        Called when a sent BufferHolder is received by the recipient. The BufferHolder should return a new concrete instance, that wraps the given Buffer object.
        Parameters:
        buf - The Buffer that is received by the recipient, and needs to be wrapped in a new BufferHolder instance.
        Returns:
        A new buffer holder instance, containing the given buffer.

      • replaceBuffer

        protected final void replaceBuffer​(io.netty5.util.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​(io.netty5.util.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()
        Specified by:
        isAccessible in interface io.netty5.util.Resource<T extends io.netty5.util.Resource<T>>

      • touch

        public T touch​(Object hint)
        Specified by:
        touch in interface io.netty5.util.Resource<T extends io.netty5.util.Resource<T>>

      • 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