Top Description Fields Constructors Methods
io.netty5.buffer

public abstract Class BufferHolder<T extends Resource<T>>

extends Object
implements Resource<T extends Resource<T>>
Class Inheritance
All Implemented Interfaces
io.netty5.util.Resource, java.lang.AutoCloseable
Known Direct Subclasses
io.netty5.buffer.BufferRef
Type Parameters
<T>
The concrete BufferHolder type.
Imports
io.netty5.buffer.internal.ResourceSupport, .InternalBufferUtils, io.netty5.util.Resource, .Send, java.lang.invoke.VarHandle, java.util.Objects
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.

Field Summary

Modifier and TypeField and Description
private static final VarHandle
BUF

private Buffer
buf

Constructor Summary

AccessConstructor and Description
protected
BufferHolder(Buffer
The buffer to be held by this holder.
buf)

Create a new BufferHolder to hold the given buffer.

protected
BufferHolder(Send<Buffer>
The buffer to be held by this holder.
send)

Create a new BufferHolder to hold the buffer received from the given Send.

Method Summary

Modifier and TypeMethod and Description
public void
close()

Implements io.netty5.util.Resource.close.

Close the resource, making it inaccessible.
public boolean

Returns:

true if this object is the same as the obj argument; false otherwise.
equals(Object
The reference object with which to compare.
other)

Overrides java.lang.Object.equals.

This implementation of the equals operation is restricted to work only with instances of the same class.
protected final Buffer

Returns:

The Buffer instance being held by this buffer holder.
getBuffer()

Access the held Buffer instance.

protected final Buffer

Returns:

The Buffer instance being held by this buffer holder.
getBufferVolatile()

Access the held Buffer instance.

public int
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code value for this object.
public boolean
isAccessible()

Implements io.netty5.util.Resource.isAccessible.

Check if this object is accessible.
protected abstract T

Returns:

A new buffer holder instance, containing the given buffer.
receive(Buffer
The Buffer that is received by the recipient, and needs to be wrapped in a new BufferHolder instance.
buf)

Called when a sent BufferHolder is received by the recipient.

protected final void
replaceBuffer(Send<Buffer>
The new Buffer instance that is replacing the currently held buffer.
send)

Replace the underlying referenced buffer with the given buffer.

protected final void
replaceBufferVolatile(Send<Buffer>
The Send with the new Buffer instance that is replacing the currently held buffer.
send)

Replace the underlying referenced buffer with the given buffer.

public Send<T>
send()

Implements io.netty5.util.Resource.send.

Send this object instance to another Thread, transferring the ownership to the recipient.
public T
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.
Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAlltoStringwaitwaitwait

Field Detail

BUFback to summary
private static final VarHandle BUF
bufback to summary
private Buffer buf

Constructor Detail

BufferHolderback to summary
protected BufferHolder(Buffer buf)

Create a new BufferHolder to hold the given buffer.

Parameters
buf:Buffer

The buffer to be held by this holder.

BufferHolderback to summary
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:Send<Buffer>

The buffer to be held by this holder.

Method Detail

closeback to summary
public void close()

Implements io.netty5.util.Resource.close.

Doc from io.netty5.util.Resource.close.

Close the resource, making it inaccessible.

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

Annotations
@Override
equalsback to summary
public boolean equals(Object other)

Overrides java.lang.Object.equals.

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.

Parameters
other:Object

The reference object with which to compare.

Returns:boolean

true if this object is the same as the obj argument; false otherwise.

Annotations
@Override
getBufferback to summary
protected final Buffer getBuffer()

Access the held Buffer instance.

The access is performed using a plain load.

Returns:Buffer

The Buffer instance being held by this buffer holder.

getBufferVolatileback to summary
protected final Buffer getBufferVolatile()

Access the held Buffer instance.

The access is performed using a volatile load.

Returns:Buffer

The Buffer instance being held by this buffer holder.

hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Doc from java.lang.Object.hashCode.

Returns a hash code value for this object. This method is supported for the benefit of hash tables such as those provided by java.util.HashMap.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.
Returns:int

a hash code value for this object

Annotations
@Override
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
receiveback to summary
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:Buffer

The Buffer that is received by the recipient, and needs to be wrapped in a new BufferHolder instance.

Returns:T

A new buffer holder instance, containing the given buffer.

replaceBufferback to summary
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:Send<Buffer>

The new Buffer instance that is replacing the currently held buffer.

replaceBufferVolatileback to summary
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:Send<Buffer>

The Send with the new Buffer instance that is replacing the currently held buffer.

sendback to summary
public Send<T> send()

Implements io.netty5.util.Resource.send.

Doc from io.netty5.util.Resource.send.

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 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.

Annotations
@SuppressWarnings:unchecked
@Override
touchback to summary
public T 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:T

This resource instance.

Annotations
@SuppressWarnings:unchecked
@Override