Package org.apache.arrow.memory

Interface BufferAllocator

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 Details

    • 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

      @Nullable 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:

    • 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.