Package org.apache.arrow.memory

Interface ReferenceManager

All Known Implementing Classes:
BufferLedger
public interface ReferenceManager
ReferenceManager is the reference count for one or more allocations.

In order to integrate with the core BufferAllocator implementation, the allocation itself should be represented by an AllocationManager, though this is not required by the API.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final ReferenceManager
    NO_OP
     
    static final String
    NO_OP_ERROR_MESSAGE
     

  • Method Summary

    Modifier and Type
    Method
    Description
    ArrowBuf
    deriveBuffer(ArrowBuf sourceBuffer, long index, long length)
    Derive a new ArrowBuf from a given source ArrowBuf.
    long
    getAccountedSize()
    Get the total accounted size (in bytes).
    BufferAllocator
    getAllocator()
    Get the buffer allocator associated with this reference manager.
    int
    getRefCount()
    Return the reference count.
    long
    getSize()
    Total size (in bytes) of memory underlying this reference manager.
    boolean
    release()
    Decrement this reference manager's reference count by 1 for the associated underlying memory.
    boolean
    release(int decrement)
    Decrement this reference manager's reference count for the associated underlying memory.
    void
    retain()
    Increment this reference manager's reference count by 1 for the associated underlying memory.
    void
    retain(int increment)
    Increment this reference manager's reference count by a given amount for the associated underlying memory.
    ArrowBuf
    retain(ArrowBuf srcBuffer, BufferAllocator targetAllocator)
    Create a new ArrowBuf that is associated with an alternative allocator for the purposes of memory ownership and accounting.
    OwnershipTransferResult
    transferOwnership(ArrowBuf sourceBuffer, BufferAllocator targetAllocator)
    Duplicate the memory accounting ownership of the backing allocation of the given ArrowBuf in another allocator.

  • Field Details

  • Method Details

    • getRefCount

      int getRefCount()
      Return the reference count.
      Returns:
      reference count

    • release

      boolean release()
      Decrement this reference manager's reference count by 1 for the associated underlying memory. If the reference count drops to 0, it implies that ArrowBufs managed by this reference manager no longer need access to the underlying memory
      Returns:
      true if ref count has dropped to 0, false otherwise

    • release

      boolean release(int decrement)
      Decrement this reference manager's reference count for the associated underlying memory. If the reference count drops to 0, it implies that ArrowBufs managed by this reference manager no longer need access to the underlying memory
      Parameters:
      decrement - the count to decrease the reference count by
      Returns:
      the new reference count

    • retain

      void retain()
      Increment this reference manager's reference count by 1 for the associated underlying memory.

    • retain

      void retain(int increment)
      Increment this reference manager's reference count by a given amount for the associated underlying memory.
      Parameters:
      increment - the count to increase the reference count by

    • retain

      ArrowBuf retain(ArrowBuf srcBuffer, BufferAllocator targetAllocator)
      Create a new ArrowBuf that is associated with an alternative allocator for the purposes of memory ownership and accounting. This has no impact on the reference counting for the current ArrowBuf except in the situation where the passed in Allocator is the same as the current buffer. This operation has no impact on the reference count of this ArrowBuf. The newly created ArrowBuf with either have a reference count of 1 (in the case that this is the first time this memory is being associated with the target allocator or in other words allocation manager currently doesn't hold a mapping for the target allocator) or the current value of the reference count for the target allocator-reference manager combination + 1 in the case that the provided allocator already had an association to this underlying memory.

      The underlying allocation (AllocationManager) will not be copied.

      Parameters:
      srcBuffer - source ArrowBuf
      targetAllocator - The target allocator to create an association with.
      Returns:
      A new ArrowBuf which shares the same underlying memory as this ArrowBuf.

    • deriveBuffer

      ArrowBuf deriveBuffer(ArrowBuf sourceBuffer, long index, long length)
      Derive a new ArrowBuf from a given source ArrowBuf. The new derived ArrowBuf will share the same reference count as rest of the ArrowBufs associated with this reference manager.
      Parameters:
      sourceBuffer - source ArrowBuf
      index - index (relative to source ArrowBuf) new ArrowBuf should be derived from
      length - length (bytes) of data in underlying memory that derived buffer will have access to in underlying memory
      Returns:
      derived buffer

    • transferOwnership

      OwnershipTransferResult transferOwnership(ArrowBuf sourceBuffer, BufferAllocator targetAllocator)
      Duplicate the memory accounting ownership of the backing allocation of the given ArrowBuf in another allocator. This will generate a new ArrowBuf that carries an association with the same underlying memory (AllocationManagers) as the given ArrowBuf.
      Parameters:
      sourceBuffer - source ArrowBuf
      targetAllocator - The target allocator to create an association with
      Returns:
      OwnershipTransferResult with info on transfer result and new buffer

    • getAllocator

      BufferAllocator getAllocator()
      Get the buffer allocator associated with this reference manager.
      Returns:
      buffer allocator.

    • getSize

      long getSize()
      Total size (in bytes) of memory underlying this reference manager.
      Returns:
      Size (in bytes) of the memory chunk.

    • getAccountedSize

      long getAccountedSize()
      Get the total accounted size (in bytes).
      Returns:
      accounted size.