org.apache.arrow.memory

Interface BufferAllocator

All Superinterfaces:

AutoCloseable

All Known Implementing Classes:

BaseAllocator, RootAllocator

public interface BufferAllocator
extends AutoCloseable

Wrapper class to deal with byte buffer allocation. Ensures users only use designated methods.

Method Summary

Modifier and Type	Method and Description
void	assertOpen() Asserts (using java assertions) that the provided allocator is currently open.
ArrowBuf	buffer(long size) Allocate a new or reused buffer of the provided size.
ArrowBuf	buffer(long size, BufferManager manager) Allocate a new or reused buffer of the provided size.
void	close() Close and release all buffers generated from this buffer pool.
long	getAllocatedMemory() Returns the amount of memory currently allocated from this allocator.
io.netty.buffer.ByteBufAllocator	getAsByteBufAllocator() Deprecated. This method may be removed in a future release.
Collection<BufferAllocator>	getChildAllocators() Returns the set of child allocators.
ArrowBuf	getEmpty() Get a reference to the empty buffer associated with this allocator.
long	getHeadroom() Returns the amount of memory that can probably be allocated at this moment without exceeding this or any parents allocation maximum.
long	getInitReservation() Return the initial reservation.
long	getLimit() Return the current maximum limit this allocator imposes.
String	getName() Return the name of this allocator.
BufferAllocator	getParentAllocator() Returns the parent allocator.
long	getPeakMemoryAllocation() Returns the peak amount of memory allocated from this allocator.
boolean	isOverLimit() Return whether or not this allocator (or one if its parents) is over its limits.
BufferAllocator	newChildAllocator(String name, AllocationListener listener, long initReservation, long maxAllocation) Create a new child allocator.
BufferAllocator	newChildAllocator(String name, long initReservation, long maxAllocation) Create a new child allocator.
AllocationReservation	newReservation() Create an allocation reservation.
void	setLimit(long newLimit) Set the maximum amount of memory this allocator is allowed to allocate.
String	toVerboseString() Return a verbose string describing this allocator.

Method Detail

buffer

ArrowBuf buffer(long size)

Allocate a new or reused buffer of the provided size. Note that the buffer may technically be larger than the requested size for rounding purposes. However, the buffer's capacity will be set to the configured size.

Parameters:

size - The size in bytes.

Returns:

a new ArrowBuf, or null if the request can't be satisfied

Throws:

OutOfMemoryException - if buffer cannot be allocated

buffer

ArrowBuf buffer(long size,
                BufferManager manager)

Allocate a new or reused buffer of the provided size. Note that the buffer may technically be larger than the requested size for rounding purposes. However, the buffer's capacity will be set to the configured size.

Parameters:

size - The size in bytes.

manager - A buffer manager to manage reallocation.

Returns:

a new ArrowBuf, or null if the request can't be satisfied

Throws:

OutOfMemoryException - if buffer cannot be allocated

getAsByteBufAllocator

@Deprecated
io.netty.buffer.ByteBufAllocator getAsByteBufAllocator()

Deprecated. This method may be removed in a future release.

Returns the allocator this allocator falls back to when it needs more memory.

Returns:

the underlying allocator used by this allocator

newChildAllocator

BufferAllocator newChildAllocator(String name,
                                  long initReservation,
                                  long maxAllocation)

Create a new child allocator.

Parameters:

name - the name of the allocator.

initReservation - the initial space reservation (obtained from this allocator)

maxAllocation - maximum amount of space the new allocator can allocate

Returns:

the new allocator, or null if it can't be created

newChildAllocator

BufferAllocator newChildAllocator(String name,
                                  AllocationListener listener,
                                  long initReservation,
                                  long maxAllocation)

Create a new child allocator.

Parameters:

name - the name of the allocator.

listener - allocation listener for the newly created child

initReservation - the initial space reservation (obtained from this allocator)

maxAllocation - maximum amount of space the new allocator can allocate

Returns:

the new allocator, or null if it can't be created

close

void close()

Close and release all buffers generated from this buffer pool.

When assertions are on, complains if there are any outstanding buffers; to avoid that, release all buffers before the allocator is closed.

Specified by:

close in interface AutoCloseable

getAllocatedMemory

long getAllocatedMemory()

Returns the amount of memory currently allocated from this allocator.

Returns:

the amount of memory currently allocated

getLimit

long getLimit()

Return the current maximum limit this allocator imposes.

Returns:

Limit in number of bytes.

getInitReservation

long getInitReservation()

Return the initial reservation.

Returns:

reservation in bytes.

setLimit

void setLimit(long newLimit)

Set the maximum amount of memory this allocator is allowed to allocate.

Parameters:

newLimit - The new Limit to apply to allocations

getPeakMemoryAllocation

long getPeakMemoryAllocation()

Returns the peak amount of memory allocated from this allocator.

Returns:

the peak amount of memory allocated

getHeadroom

long getHeadroom()

Returns the amount of memory that can probably be allocated at this moment without exceeding this or any parents allocation maximum.

Returns:

Headroom in bytes

getParentAllocator

BufferAllocator getParentAllocator()

Returns the parent allocator.

Returns:

parent allocator

getChildAllocators

Collection<BufferAllocator> getChildAllocators()

Returns the set of child allocators.

Returns:

set of child allocators

newReservation

AllocationReservation newReservation()

Create an allocation reservation. A reservation is a way of building up a request for a buffer whose size is not known in advance. See

Returns:

the newly created reservation

See Also:

AllocationReservation

getEmpty

ArrowBuf getEmpty()

Get a reference to the empty buffer associated with this allocator. Empty buffers are special because we don't worry about them leaking or managing reference counts on them since they don't actually point to any memory.

Returns:

the empty buffer

getName

String getName()

Return the name of this allocator. This is a human readable name that can help debugging. Typically provides coordinates about where this allocator was created

Returns:

the name of the allocator

isOverLimit

boolean isOverLimit()

Return whether or not this allocator (or one if its parents) is over its limits. In the case that an allocator is over its limit, all consumers of that allocator should aggressively try to address the overlimit situation.

Returns:

whether or not this allocator (or one if its parents) is over its limits

toVerboseString

String toVerboseString()

Return a verbose string describing this allocator. If in DEBUG mode, this will also include relevant stacktraces and historical logs for underlying objects

Returns:

A very verbose description of the allocator hierarchy.

assertOpen

void assertOpen()

Asserts (using java assertions) that the provided allocator is currently open. If assertions are disabled, this is a no-op.