-
- All Superinterfaces:
AutoCloseable
,SafeCloseable
- All Known Implementing Classes:
PooledBufferAllocator
,SensitiveBufferAllocator
public interface BufferAllocator extends SafeCloseable
Interface for allocatingBuffer
s.
-
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description Buffer
allocate(int size)
Allocate aBuffer
of the given size in bytes.void
close()
Close this allocator, freeing all of its internal resources.default CompositeBuffer
compose()
Create an empty composite buffer, that has no components.default CompositeBuffer
compose(Send<Buffer> send)
Compose the send of a buffer and present them as a single buffer.default CompositeBuffer
compose(Iterable<Send<Buffer>> sends)
Compose the given sequence of sends of buffers and present them as a single buffer.Supplier<Buffer>
constBufferSupplier(byte[] bytes)
Create a supplier of "constant" Buffers from this allocator, that all have the given byte contents.default Buffer
copyOf(byte[] bytes)
Allocate aBuffer
with the same size and contents of the given byte array.default Buffer
copyOf(String str, Charset charset)
default Buffer
copyOf(ByteBuffer buffer)
Allocate aBuffer
with the same size and contents, as the contents of the givenByteBuffer
.AllocationType
getAllocationType()
Get theAllocationType
from this allocator.boolean
isPooling()
Determine if this allocator is pooling and reusing its allocated memory.static BufferAllocator
offHeapPooled()
Produces a poolingBufferAllocator
that allocates and recycles off-heap buffers.static BufferAllocator
offHeapUnpooled()
Produces aBufferAllocator
that allocates unpooled, off-heap buffers.static BufferAllocator
onHeapPooled()
Produces a poolingBufferAllocator
that allocates and recycles on-heap buffers.static BufferAllocator
onHeapUnpooled()
Produces aBufferAllocator
that allocates unpooled, on-heap buffers.
-
-
-
Method Detail
-
onHeapUnpooled
static BufferAllocator onHeapUnpooled()
Produces aBufferAllocator
that allocates unpooled, on-heap buffers. On-heap buffers have abyte[]
internally, and their readable and writable native addresses are zero.The concrete
Buffer
implementation is chosen byMemoryManager.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:
- A non-pooling allocator of on-heap buffers
-
offHeapUnpooled
static BufferAllocator offHeapUnpooled()
Produces aBufferAllocator
that allocates unpooled, off-heap buffers. Off-heap buffers a native memory pointer internally, which can be obtained from their readable and writable native address methods.The concrete
Buffer
implementation is chosen byMemoryManager.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:
- A non-pooling allocator of on-heap buffers
-
onHeapPooled
static BufferAllocator onHeapPooled()
Produces a poolingBufferAllocator
that allocates and recycles on-heap buffers. On-heap buffers have abyte[]
internally, and their readable and writable native addresses are zero.The concrete
Buffer
implementation is chosen byMemoryManager.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:
- A pooling allocator of on-heap buffers
-
offHeapPooled
static BufferAllocator offHeapPooled()
Produces a poolingBufferAllocator
that allocates and recycles off-heap buffers. Off-heap buffers a native memory pointer internally, which can be obtained from their readable and writable native address methods.The concrete
Buffer
implementation is chosen byMemoryManager.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:
- A pooling allocator of on-heap buffers
-
isPooling
boolean isPooling()
Determine if this allocator is pooling and reusing its allocated memory.- Returns:
true
if this allocator is pooling and reusing its memory,false
otherwise.
-
getAllocationType
AllocationType getAllocationType()
Get theAllocationType
from this allocator. This would typically be one of theStandardAllocationTypes
.- Returns:
- The type of allocations performed by this allocator.
-
allocate
Buffer allocate(int size)
Allocate aBuffer
of the given size in bytes. This method may throw anOutOfMemoryError
if there is not enough free memory available to allocate aBuffer
of the requested size.The buffer will use big endian byte order.
- Parameters:
size
- The size ofBuffer
to allocate.- Returns:
- The newly allocated
Buffer
. - Throws:
IllegalStateException
- if this allocator has been closed.
-
compose
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
- The sent buffer to compose into a single buffer view.- Returns:
- A buffer composed of, and backed by, the given buffers.
- Throws:
IllegalStateException
- if one of the sends have already been received. The remaining buffers and sends will be closed and discarded, respectively.
-
compose
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
- The sent buffers to compose into a single buffer view.- Returns:
- A buffer composed of, and backed by, the given buffers.
- Throws:
IllegalStateException
- if one of the sends have already been received. The remaining buffers and sends will be closed and discarded, respectively.
-
compose
default CompositeBuffer compose()
Create an empty composite buffer, that has no components. The buffer can be extended with components using eitherCompositeBuffer.ensureWritable(int)
orCompositeBuffer.extendWith(Send)
.- Returns:
- A composite buffer that has no components, and has a capacity of zero.
-
constBufferSupplier
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
- The byte contents of the buffers produced by the returned supplier.- Returns:
- A supplier of read-only buffers with the given contents.
- Throws:
IllegalStateException
- if this allocator has been closed, but any supplier obtained prior to closing the allocator will continue to work.
-
copyOf
default Buffer copyOf(byte[] bytes)
Allocate aBuffer
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 anOutOfMemoryError
if there is not enough free memory available to allocate aBuffer
of the requested size.The allocated buffer will use big endian byte order.
- Parameters:
bytes
- The byte array that determines the size and contents of the new buffer.- Returns:
- The newly allocated
Buffer
. - Throws:
IllegalStateException
- if this allocator has been closed.
-
copyOf
default Buffer copyOf(String str, Charset charset)
Allocate aBuffer
with the same size and contents of the givenString
, when interpreted as a sequence of bytes with the givenCharset
. This may throw anOutOfMemoryError
if there is not enough free memory available to allocate aBuffer
of the requested size.The allocated buffer will use big endian byte order.
- Parameters:
str
- TheString
that determines the size and contents of the new buffer.charset
- TheCharset
that determines how to turn the string into a sequence of bytes.- Returns:
- The newly allocated
Buffer
. - Throws:
IllegalStateException
- if this allocator has been closed.
-
copyOf
default Buffer copyOf(ByteBuffer buffer)
Allocate aBuffer
with the same size and contents, as the contents of the givenByteBuffer
. 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 anOutOfMemoryError
if there is not enough free memory available to allocate aBuffer
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
- The byte buffer, whose contents determine the capacity and contents of the allocated buffer.- Returns:
- The newly allocated
Buffer
. - Throws:
IllegalStateException
- if this allocator has been closed.
-
close
void 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.- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceSafeCloseable
-
-