Netty5/Buffer 5.0.0.Alpha5 · io.netty5.buffer.BufferAllocator

Method Summary

Modifier and Type	Method and Description
public Buffer	Returns: The newly allocated `Buffer`. allocate(int The size of `Buffer` to allocate. size) Allocate a `Buffer` of the given size in bytes.
public void	close() Redeclares io.netty5.util.SafeCloseable.close. Close this allocator, freeing all of its internal resources.
public default CompositeBuffer	Returns: A buffer composed of, and backed by, the given buffers. compose(Send<Buffer> The sent buffer to compose into a single buffer view. send) Compose the send of a buffer and present them as a single buffer.
public default CompositeBuffer	Returns: A buffer composed of, and backed by, the given buffers. compose(Iterable<Send<Buffer>> The sent buffers to compose into a single buffer view. sends) Compose the given sequence of sends of buffers and present them as a single buffer.
public default CompositeBuffer	Returns: A composite buffer that has no components, and has a capacity of zero. compose() Create an empty composite buffer, that has no components.
public Supplier<Buffer>	Returns: A supplier of read-only buffers with the given contents. constBufferSupplier(byte[] The byte contents of the buffers produced by the returned supplier. bytes) Create a supplier of "constant" Buffers from this allocator, that all have the given byte contents.
public default Buffer	Returns: The newly allocated `Buffer`. copyOf(byte[] The byte array that determines the size and contents of the new buffer. bytes) Allocate a `Buffer` with the same size and contents of the given byte array.
public default Buffer	Returns: The newly allocated `Buffer`. copyOf(String The `String` that determines the size and contents of the new buffer. str, Charset The `Charset` that determines how to turn the string into a sequence of bytes. charset) Allocate a `Buffer` with the same size and contents of the given `String`, when interpreted as a sequence of bytes with the given `Charset`.
public default Buffer	Returns: The newly allocated `Buffer`. copyOf(ByteBuffer The byte buffer, whose contents determine the capacity and contents of the allocated buffer. buffer) Allocate a `Buffer` with the same size and contents, as the contents of the given `ByteBuffer`.
public AllocationType	Returns: The type of allocations performed by this allocator. getAllocationType() Get the `AllocationType` from this allocator.
public boolean	Returns: `true` if this allocator is pooling and reusing its memory, `false` otherwise. isPooling() Determine if this allocator is pooling and reusing its allocated memory.
public static BufferAllocator	Returns: A pooling allocator of on-heap buffers offHeapPooled() Produces a pooling `BufferAllocator` that allocates and recycles off-heap buffers.
public static BufferAllocator	Returns: A non-pooling allocator of on-heap buffers offHeapUnpooled() Produces a `BufferAllocator` that allocates unpooled, off-heap buffers.
public static BufferAllocator	Returns: A pooling allocator of on-heap buffers onHeapPooled() Produces a pooling `BufferAllocator` that allocates and recycles on-heap buffers.
public static BufferAllocator	Returns: A non-pooling allocator of on-heap buffers onHeapUnpooled() Produces a `BufferAllocator` that allocates unpooled, on-heap buffers.

Method Detail

allocate back to summary

allocate	back to summary
public Buffer allocate(int size) Allocate a `Buffer` of the given size in bytes. This method may throw an `OutOfMemoryError` if there is not enough free memory available to allocate a `Buffer` of the requested size. The buffer will use big endian byte order. Note unlike the JDK `ByteBuffer`s, Netty `Buffers` are not guaranteed to be zeroed when allocated. In other words, the memory of a newly allocated buffer may contain garbage data from prior allocations, and the memory is likewise not guaranteed to be erased when the buffer is closed. If the data is sensitive and needs to be overwritten when the buffer is closed, then the buffer should be allocated with the `SensitiveBufferAllocator`. Parameters size:int The size of `Buffer` to allocate. Returns:Buffer The newly allocated `Buffer`. Exceptions IllegalStateException: if this allocator has been closed.

public Buffer allocate(int size)

Allocate a Buffer of the given size in bytes. This method may throw an OutOfMemoryError if there is not enough free memory available to allocate a Buffer of the requested size.

The buffer will use big endian byte order.

Note

unlike the JDK ByteBuffers, Netty Buffers are not guaranteed to be zeroed when allocated. In other words, the memory of a newly allocated buffer may contain garbage data from prior allocations, and the memory is likewise not guaranteed to be erased when the buffer is closed. If the data is sensitive and needs to be overwritten when the buffer is closed, then the buffer should be allocated with the SensitiveBufferAllocator.

Parameters

size:int: The size of Buffer to allocate.

Returns:Buffer

The newly allocated Buffer.

Exceptions

IllegalStateException:: if this allocator has been closed.

close back to summary

close	back to summary
public void close() Redeclares io.netty5.util.SafeCloseable.close. Close this allocator, freeing all of its internal resources. Existing (currently in-use) allocated buffers will not be impacted by calling this method. If this is a pooling or caching allocator, then existing buffers will be immediately freed when they are closed, instead of being pooled or cached. The allocator can no longer be used to allocate more buffers after calling this method. Attempting to allocate from a closed allocator will cause `IllegalStateException`s to be thrown. Annotations @Override

public void close()

Redeclares io.netty5.util.SafeCloseable.close.

Close this allocator, freeing all of its internal resources.

Existing (currently in-use) allocated buffers will not be impacted by calling this method. If this is a pooling or caching allocator, then existing buffers will be immediately freed when they are closed, instead of being pooled or cached.

The allocator can no longer be used to allocate more buffers after calling this method. Attempting to allocate from a closed allocator will cause IllegalStateExceptions to be thrown.

Annotations

@Override

compose	back to summary
public default CompositeBuffer compose(Send<Buffer> send) Compose the send of a buffer and present them as a single buffer. When a composite buffer is closed, all of its constituent component buffers are closed as well. See the class documentation for more information on how buffers compose, and what is required of the given buffers for composition to be allowed. Parameters send:Send<Buffer> The sent buffer to compose into a single buffer view. Returns:CompositeBuffer A buffer composed of, and backed by, the given buffers. Exceptions IllegalStateException: if one of the sends have already been received. The remaining buffers and sends will be closed and discarded, respectively.

compose

back to summary

public default CompositeBuffer compose(Send<Buffer> send)

Compose the send of a buffer and present them as a single buffer.

When a composite buffer is closed, all of its constituent component buffers are closed as well.

See the class documentation for more information on how buffers compose, and what is required of the given buffers for composition to be allowed.

Parameters

send:Send<Buffer>: The sent buffer to compose into a single buffer view.

Returns:CompositeBuffer

A buffer composed of, and backed by, the given buffers.

Exceptions

IllegalStateException:: if one of the sends have already been received. The remaining buffers and sends will be closed and discarded, respectively.

compose	back to summary
public default CompositeBuffer compose(Iterable<Send<Buffer>> sends) Compose the given sequence of sends of buffers and present them as a single buffer. When a composite buffer is closed, all of its constituent component buffers are closed as well. See the class documentation for more information on how buffers compose, and what is required of the given buffers for composition to be allowed. Parameters sends:Iterable<Send<Buffer>> The sent buffers to compose into a single buffer view. Returns:CompositeBuffer A buffer composed of, and backed by, the given buffers. Exceptions IllegalStateException: if one of the sends have already been received. The remaining buffers and sends will be closed and discarded, respectively.

compose

back to summary

public default CompositeBuffer compose(Iterable<Send<Buffer>> sends)

Compose the given sequence of sends of buffers and present them as a single buffer.

When a composite buffer is closed, all of its constituent component buffers are closed as well.

See the class documentation for more information on how buffers compose, and what is required of the given buffers for composition to be allowed.

Parameters

sends:Iterable<Send<Buffer>>: The sent buffers to compose into a single buffer view.

Returns:CompositeBuffer

A buffer composed of, and backed by, the given buffers.

Exceptions

IllegalStateException:: if one of the sends have already been received. The remaining buffers and sends will be closed and discarded, respectively.

compose back to summary

compose	back to summary
public default CompositeBuffer compose() Create an empty composite buffer, that has no components. The buffer can be extended with components using either `CompositeBuffer#ensureWritable(int)` or `CompositeBuffer#extendWith(Send)`. Returns:CompositeBuffer A composite buffer that has no components, and has a capacity of zero.

public default CompositeBuffer compose()

Create an empty composite buffer, that has no components. The buffer can be extended with components using either CompositeBuffer#ensureWritable(int) or CompositeBuffer#extendWith(Send).

Returns:CompositeBuffer: A composite buffer that has no components, and has a capacity of zero.

constBufferSupplier back to summary

constBufferSupplier	back to summary
public Supplier<Buffer> constBufferSupplier(byte[] bytes) Create a supplier of "constant" Buffers from this allocator, that all have the given byte contents. The buffer has the same capacity as the byte array length, and its write offset is placed at the end, and its read offset is at the beginning, such that the entire buffer contents are readable. The buffers produced by the supplier will each have their own independent life-cycle, and closing them will make them inaccessible, just like normally allocated buffers. The buffers produced are "constants", in the sense that they are read-only. It can generally be expected, but is not guaranteed, that the returned supplier is more resource efficient than allocating and copying memory with other available APIs. In such optimised implementations, the underlying memory baking the buffers will be shared among all the buffers produced by the supplier. The primary use case for this API, is when you need to repeatedly produce buffers with the same contents, and you perhaps wish to keep a `static final` field with these contents. The supplier-based API enforces that each usage get their own distinct buffer instance. Each of these instances cannot interfere with each other, so bugs like closing, or modifying the contents, of a shared buffer cannot occur. Parameters bytes:byte[] The byte contents of the buffers produced by the returned supplier. Returns:Supplier<Buffer> A supplier of read-only buffers with the given contents. Exceptions IllegalStateException: if this allocator has been closed, but any supplier obtained prior to closing the allocator will continue to work.

public Supplier<Buffer> constBufferSupplier(byte[] bytes)

Create a supplier of "constant" Buffers from this allocator, that all have the given byte contents. The buffer has the same capacity as the byte array length, and its write offset is placed at the end, and its read offset is at the beginning, such that the entire buffer contents are readable.

The buffers produced by the supplier will each have their own independent life-cycle, and closing them will make them inaccessible, just like normally allocated buffers.

The buffers produced are "constants", in the sense that they are read-only.

It can generally be expected, but is not guaranteed, that the returned supplier is more resource efficient than allocating and copying memory with other available APIs. In such optimised implementations, the underlying memory baking the buffers will be shared among all the buffers produced by the supplier.

The primary use case for this API, is when you need to repeatedly produce buffers with the same contents, and you perhaps wish to keep a static final field with these contents. The supplier-based API enforces that each usage get their own distinct buffer instance. Each of these instances cannot interfere with each other, so bugs like closing, or modifying the contents, of a shared buffer cannot occur.

Parameters

bytes:byte[]: The byte contents of the buffers produced by the returned supplier.

Returns:Supplier<Buffer>

A supplier of read-only buffers with the given contents.

Exceptions

IllegalStateException:: if this allocator has been closed, but any supplier obtained prior to closing the allocator will continue to work.

copyOf back to summary

copyOf	back to summary
public default Buffer copyOf(byte[] bytes) Allocate a `Buffer` with the same size and contents of the given byte array. The allocated buffer is NOT backed by the given byte array, and changes to the contents of either will not be reflected in the other. This may throw an `OutOfMemoryError` if there is not enough free memory available to allocate a `Buffer` of the requested size. The allocated buffer will use big endian byte order. Parameters bytes:byte[] The byte array that determines the size and contents of the new buffer. Returns:Buffer The newly allocated `Buffer`. Exceptions IllegalStateException: if this allocator has been closed.

public default Buffer copyOf(byte[] bytes)

Allocate a Buffer with the same size and contents of the given byte array. The allocated buffer is NOT backed by the given byte array, and changes to the contents of either will not be reflected in the other. This may throw an OutOfMemoryError if there is not enough free memory available to allocate a Buffer of the requested size.

The allocated buffer will use big endian byte order.

Parameters

bytes:byte[]: The byte array that determines the size and contents of the new buffer.

Returns:Buffer

The newly allocated Buffer.

Exceptions

IllegalStateException:: if this allocator has been closed.

copyOf back to summary

copyOf	back to summary
public default Buffer copyOf(String str, Charset charset) Allocate a `Buffer` with the same size and contents of the given `String`, when interpreted as a sequence of bytes with the given `Charset`. This may throw an `OutOfMemoryError` if there is not enough free memory available to allocate a `Buffer` of the requested size. The allocated buffer will use big endian byte order. Parameters str:String The `String` that determines the size and contents of the new buffer. charset:Charset The `Charset` that determines how to turn the string into a sequence of bytes. Returns:Buffer The newly allocated `Buffer`. Exceptions IllegalStateException: if this allocator has been closed.

public default Buffer copyOf(String str, Charset charset)

Allocate a Buffer with the same size and contents of the given String, when interpreted as a sequence of bytes with the given Charset. This may throw an OutOfMemoryError if there is not enough free memory available to allocate a Buffer of the requested size.

The allocated buffer will use big endian byte order.

Parameters

str:String: The String that determines the size and contents of the new buffer.
charset:Charset: The Charset that determines how to turn the string into a sequence of bytes.

Returns:Buffer

The newly allocated Buffer.

Exceptions

IllegalStateException:: if this allocator has been closed.

copyOf back to summary

copyOf	back to summary
public default Buffer copyOf(ByteBuffer buffer) Allocate a `Buffer` with the same size and contents, as the contents of the given `ByteBuffer`. The allocated buffer is NOT backed by the give byte buffer, and changes to the contents of either will not be reflected in the other. The position and limit of the given byte buffer defines the region of contents that will be copied. The position and limit are not modified by this method. This may throw an `OutOfMemoryError` if there is not enough free memory available to allocate a `Buffer` of the requested size. The allocated buffer will use big endian byte order, regardless of the byte order of the given buffer. The contents of the byte buffer will be copied without regard to the byte order, as if the bytes are copied one at a time. Parameters buffer:ByteBuffer The byte buffer, whose contents determine the capacity and contents of the allocated buffer. Returns:Buffer The newly allocated `Buffer`. Exceptions IllegalStateException: if this allocator has been closed.

public default Buffer copyOf(ByteBuffer buffer)

Allocate a Buffer with the same size and contents, as the contents of the given ByteBuffer. The allocated buffer is NOT backed by the give byte buffer, and changes to the contents of either will not be reflected in the other. The position and limit of the given byte buffer defines the region of contents that will be copied. The position and limit are not modified by this method. This may throw an OutOfMemoryError if there is not enough free memory available to allocate a Buffer of the requested size.

The allocated buffer will use big endian byte order, regardless of the byte order of the given buffer. The contents of the byte buffer will be copied without regard to the byte order, as if the bytes are copied one at a time.

Parameters

buffer:ByteBuffer: The byte buffer, whose contents determine the capacity and contents of the allocated buffer.

Returns:Buffer

The newly allocated Buffer.

Exceptions

IllegalStateException:: if this allocator has been closed.

getAllocationType back to summary

getAllocationType	back to summary
public AllocationType getAllocationType() Get the `AllocationType` from this allocator. This would typically be one of the `StandardAllocationTypes`. Returns:AllocationType The type of allocations performed by this allocator.

public AllocationType getAllocationType()

Get the AllocationType from this allocator. This would typically be one of the StandardAllocationTypes.

Returns:AllocationType: The type of allocations performed by this allocator.

isPooling back to summary

isPooling	back to summary
public boolean isPooling() Determine if this allocator is pooling and reusing its allocated memory. Returns:boolean `true` if this allocator is pooling and reusing its memory, `false` otherwise.

public boolean isPooling()

Determine if this allocator is pooling and reusing its allocated memory.

Returns:boolean: true if this allocator is pooling and reusing its memory, false otherwise.

offHeapPooled back to summary

offHeapPooled	back to summary
public static BufferAllocator offHeapPooled() Produces a pooling `BufferAllocator` that allocates and recycles off-heap buffers. Off-heap buffers a native memory pointer internally, which can be obtained from their buffer component native address methods. The concrete `Buffer` implementation is chosen by `MemoryManager#instance()`. Note This method always creates a new allocator instance. To get a shared and cached allocator instance, use the `DefaultBufferAllocators#offHeapAllocator()` method instead. Returns:BufferAllocator A pooling allocator of on-heap buffers

public static BufferAllocator offHeapPooled()

Produces a pooling BufferAllocator that allocates and recycles off-heap buffers. Off-heap buffers a native memory pointer internally, which can be obtained from their buffer component native address methods.

The concrete Buffer implementation is chosen by MemoryManager#instance().

Note

This method always creates a new allocator instance. To get a shared and cached allocator instance, use the DefaultBufferAllocators#offHeapAllocator() method instead.

Returns:BufferAllocator: A pooling allocator of on-heap buffers

offHeapUnpooled back to summary

offHeapUnpooled	back to summary
public static BufferAllocator offHeapUnpooled() Produces a `BufferAllocator` that allocates unpooled, off-heap buffers. Off-heap buffers a native memory pointer internally, which can be obtained from their buffer component native address methods. The concrete `Buffer` implementation is chosen by `MemoryManager#instance()`. Note This method always creates a new allocator instance. To get a shared and cached allocator instance, use the `DefaultBufferAllocators#offHeapAllocator()` method instead. Returns:BufferAllocator A non-pooling allocator of on-heap buffers

public static BufferAllocator offHeapUnpooled()

Produces a BufferAllocator that allocates unpooled, off-heap buffers. Off-heap buffers a native memory pointer internally, which can be obtained from their buffer component native address methods.

The concrete Buffer implementation is chosen by MemoryManager#instance().

Note

This method always creates a new allocator instance. To get a shared and cached allocator instance, use the DefaultBufferAllocators#offHeapAllocator() method instead.

Returns:BufferAllocator: A non-pooling allocator of on-heap buffers

onHeapPooled back to summary

onHeapPooled	back to summary
public static BufferAllocator onHeapPooled() Produces a pooling `BufferAllocator` that allocates and recycles on-heap buffers. On-heap buffers have a `byte[]` internally, and their buffer component native addresses are zero. The concrete `Buffer` implementation is chosen by `MemoryManager#instance()`. Note This method always creates a new allocator instance. To get a shared and cached allocator instance, use the `DefaultBufferAllocators#onHeapAllocator()` method instead. Returns:BufferAllocator A pooling allocator of on-heap buffers

public static BufferAllocator onHeapPooled()

Produces a pooling BufferAllocator that allocates and recycles on-heap buffers. On-heap buffers have a byte[] internally, and their buffer component native addresses are zero.

The concrete Buffer implementation is chosen by MemoryManager#instance().

Note

This method always creates a new allocator instance. To get a shared and cached allocator instance, use the DefaultBufferAllocators#onHeapAllocator() method instead.

Returns:BufferAllocator: A pooling allocator of on-heap buffers

onHeapUnpooled back to summary

onHeapUnpooled	back to summary
public static BufferAllocator onHeapUnpooled() Produces a `BufferAllocator` that allocates unpooled, on-heap buffers. On-heap buffers have a `byte[]` internally, and their buffer component native addresses are zero. The concrete `Buffer` implementation is chosen by `MemoryManager#instance()`. Note This method always creates a new allocator instance. To get a shared and cached allocator instance, use the `DefaultBufferAllocators#onHeapAllocator()` method instead. Returns:BufferAllocator A non-pooling allocator of on-heap buffers

public static BufferAllocator onHeapUnpooled()

Produces a BufferAllocator that allocates unpooled, on-heap buffers. On-heap buffers have a byte[] internally, and their buffer component native addresses are zero.

The concrete Buffer implementation is chosen by MemoryManager#instance().

Note

This method always creates a new allocator instance. To get a shared and cached allocator instance, use the DefaultBufferAllocators#onHeapAllocator() method instead.

Returns:BufferAllocator: A non-pooling allocator of on-heap buffers

public Interface BufferAllocator

Method Summary

Method Detail