BufferAllocator (Apache Arrow Java Root POM 12.0.0 API)

All Superinterfaces:

AutoCloseable

All Known Implementing Classes:

RootAllocator
```
public interface BufferAllocator
extends AutoCloseable
```
Wrapper class to deal with byte buffer allocation. Ensures users only use designated methods.

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
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.
`boolean`	`forceAllocate(long size)` Forcibly allocate bytes.
`long`	`getAllocatedMemory()` Returns the amount of memory currently allocated from this allocator.
`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.
`AllocationListener`	`getListener()` Returns the allocation listener used by this allocator.
`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.
`BufferAllocator`	`getRoot()` Get the root allocator of this allocator.
`default RoundingPolicy`	`getRoundingPolicy()` Gets the rounding policy of the 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`	`releaseBytes(long size)` Release bytes from this allocator.
`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.
`default ArrowBuf`	`wrapForeignAllocation(ForeignAllocation allocation)` EXPERIMENTAL: Wrap an allocation created outside this BufferAllocator.

- 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
  - getRoot
```
BufferAllocator getRoot()
```
    Get the root allocator of this allocator. If this allocator is already a root, return this directly.
    
    Returns:
    
    The root 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
  - forceAllocate
```
boolean forceAllocate(long size)
```
    Forcibly allocate bytes. Returns whether the allocation fit within limits.
    
    Parameters:
    
    size - to increase
    
    Returns:
    
    Whether the allocation fit within limits.
  - releaseBytes
```
void releaseBytes(long size)
```
    Release bytes from this allocator.
    
    Parameters:
    
    size - to release
  - getListener
```
AllocationListener getListener()
```
    Returns the allocation listener used by this allocator.
    
    Returns:
    
    the AllocationListener instance. Or AllocationListener.NOOP by default if no listener is configured when this allocator was created.
  - 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.
  - getRoundingPolicy
```
default RoundingPolicy getRoundingPolicy()
```
    Gets the rounding policy of the allocator.
  - wrapForeignAllocation
```
default ArrowBuf wrapForeignAllocation(ForeignAllocation allocation)
```
    EXPERIMENTAL: Wrap an allocation created outside this BufferAllocator.
    This is useful to integrate allocations from native code into the same memory management framework as Java-allocated buffers, presenting users a consistent API. The created buffer will be tracked by this allocator and can be transferred like Java-allocated buffers.
    The underlying allocation will be closed when all references to the buffer are released. If this method throws, the underlying allocation will also be closed.
    
    Parameters:
    
    allocation - The underlying allocation.

Interface BufferAllocator

Method Summary

Method Detail

buffer

buffer

getRoot

newChildAllocator

newChildAllocator

close

getAllocatedMemory

getLimit

getInitReservation

setLimit

getPeakMemoryAllocation

getHeadroom

forceAllocate

releaseBytes

getListener

getParentAllocator

getChildAllocators

newReservation

getEmpty

getName

isOverLimit

toVerboseString

assertOpen

getRoundingPolicy

wrapForeignAllocation