Interface BufferAllocator

All Superinterfaces:

AutoCloseable, Closeable

public sealed interface BufferAllocator
extends Closeable

An allocator of byte and char buffers.

By default, MxPack allocates buffers with an unpooled allocator with default options. To use a different allocator, set MessageReader.OptionBuilder.allocator(org.odenix.mxpack.core.BufferAllocator) when creating a MessageReader, or MessageWriter.OptionBuilder.allocator(org.odenix.mxpack.core.BufferAllocator) when creating a MessageWriter.

If frequent buffer allocations are not a concern, use an unpooled allocator. To reduce buffer allocations, use a single pooled allocator for all message sources and sinks. Allocators can be safely shared by multiple threads. Only pooled allocators can allocate direct byte buffers.

To create an allocator, call ofUnpooled() or ofPooled(). Because unpooled and pooled allocators implement the same BufferAllocator interface, switching between them is easy. To obtain a buffer, call getByteBuffer(int) or getCharBuffer(int). When a buffer is no longer used, call LeasedByteBuffer.close() or LeasedCharBuffer.close(). Failing to close an unused buffer reduces the efficiency of buffer pooling.

When an allocator is no longer used, call close() to free its buffer pool.

For usage examples, see Buffer allocation.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	BufferAllocator.PooledOptionBuilder	Options for creating pooled buffer allocators.
static interface	BufferAllocator.UnpooledOptionBuilder	Options for creating unpooled buffer allocators.

Method Summary

Modifier and Type	Method	Description
void	close()	Closes this buffer allocator, freeing any pooled buffers.
LeasedByteBuffer	getByteBuffer(int capacity)	Returns a leased ByteBuffer with at least the given capacity.
LeasedCharBuffer	getCharBuffer(int capacity)	Returns a leased CharBuffer with at least the given capacity.
int	maxByteBufferCapacity()	Returns the maximum buffer capacity, in bytes, that may be requested by getByteBuffer(int).
int	maxCharBufferCapacity()	Returns the maximum buffer capacity, in chars, that may be requested by getCharBuffer(int).
static BufferAllocator	ofPooled()	Returns a new buffer allocator that maintains a buffer pool to reduce buffer allocations.
static BufferAllocator	ofPooled(Consumer<BufferAllocator.PooledOptionBuilder> optionHandler)	Returns a new buffer allocator with the given options that maintains a buffer pool to reduce buffer allocations.
static BufferAllocator	ofUnpooled()	Returns a new buffer allocator that allocates a new buffer each time getByteBuffer(int) or getCharBuffer(int) is called.
static BufferAllocator	ofUnpooled(Consumer<BufferAllocator.UnpooledOptionBuilder> optionHandler)	Returns a new buffer allocator with the given options that allocates a new buffer each time getByteBuffer(int) or getCharBuffer(int) is called.

Method Details

ofUnpooled

static BufferAllocator ofUnpooled()

Returns a new buffer allocator that allocates a new buffer each time getByteBuffer(int) or getCharBuffer(int) is called.

Returns:

a new buffer allocator that allocates a new buffer each time getByteBuffer(int) or getCharBuffer(int) is called

ofUnpooled

static BufferAllocator ofUnpooled(Consumer<BufferAllocator.UnpooledOptionBuilder> optionHandler)

Returns a new buffer allocator with the given options that allocates a new buffer each time getByteBuffer(int) or getCharBuffer(int) is called.

Parameters:

optionHandler - a handler that receives an BufferAllocator.UnpooledOptionBuilder

Returns:

a new buffer allocator with the given options that allocates a new buffer each time getByteBuffer(int) or getCharBuffer(int) is called

ofPooled

static BufferAllocator ofPooled()

Returns a new buffer allocator that maintains a buffer pool to reduce buffer allocations.

This allocator supports the use of direct buffers.

The current pooled allocator implementation behaves as follows:

• The buffer pool is grown as needed until the maximum pool capacity for byte and char buffers is reached.
• If the buffer pool runs out of buffers after the maximum pool capacity has been reached, additional unpooled buffers are allocated.
• The buffer pool is never shrunk. It is freed when the allocator is closed.

Returns:

a new buffer allocator that maintains a buffer pool to reduce buffer allocations

ofPooled

static BufferAllocator ofPooled(Consumer<BufferAllocator.PooledOptionBuilder> optionHandler)

Returns a new buffer allocator with the given options that maintains a buffer pool to reduce buffer allocations.

This allocator supports the use of direct buffers.

The current pooled allocator implementation behaves as follows:

• The buffer pool is grown as needed until the maximum pool capacity for byte and char buffers is reached.
• If the buffer pool runs out of buffers after the maximum pool capacity has been reached, additional unpooled buffers are allocated.
• The buffer pool is never shrunk. It is freed when the allocator is closed.

Parameters:

optionHandler - a handler that receives a BufferAllocator.PooledOptionBuilder

Returns:

a new buffer allocator with the given options that maintains a buffer pool to reduce buffer allocations

maxByteBufferCapacity

int maxByteBufferCapacity()

Returns the maximum buffer capacity, in bytes, that may be requested by getByteBuffer(int).

The returned value can be set with BufferAllocator.UnpooledOptionBuilder.maxByteBufferCapacity(int) and BufferAllocator.PooledOptionBuilder.maxByteBufferCapacity(int).

Default: Integer.MAX_VALUE

Returns:

the maximum buffer capacity, in bytes, that may be requested by getByteBuffer(int)

maxCharBufferCapacity

int maxCharBufferCapacity()

Returns the maximum buffer capacity, in chars, that may be requested by getCharBuffer(int).

The returned value can be set with BufferAllocator.UnpooledOptionBuilder.maxCharBufferCapacity(int) and BufferAllocator.PooledOptionBuilder.maxCharBufferCapacity(int).

Default: Integer.MAX_VALUE

Returns:

the maximum buffer capacity, in chars, that may be requested by getCharBuffer(int)

getByteBuffer

LeasedByteBuffer getByteBuffer(int capacity)

Returns a leased ByteBuffer with at least the given capacity.

The returned buffer is cleared. When the buffer is no longer used, it should be closed. Failing to close an unused buffer reduces the efficiency of buffer pooling.

Parameters:

capacity - the minimum capacity, in bytes, of the leased buffer

Returns:

a leased ByteBuffer with at least the given capacity

Throws:

MxPackException.SizeLimitExceeded - if the given capacity is greater than the maximum capacity

IllegalStateException - if this allocator has already been closed

getCharBuffer

LeasedCharBuffer getCharBuffer(int capacity)

Returns a leased CharBuffer with at least the given capacity.

The returned buffer is cleared. When the buffer is no longer used, it should be closed. Failing to close an unused buffer reduces the efficiency of buffer pooling.

Parameters:

capacity - the minimum capacity, in chars, of the leased buffer

Returns:

a leased CharBuffer with at least the given capacity

Throws:

MxPackException.SizeLimitExceeded - if the given capacity is greater than the maximum capacity

IllegalStateException - if this allocator has already been closed

close

void close()

Closes this buffer allocator, freeing any pooled buffers.

Subsequent calls to this method have no effect. Subsequent calls to getByteBuffer(int) or getCharBuffer(int) throw IllegalStateException.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable