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 and Description
static ReferenceManager	NO_OP
static String	NO_OP_ERROR_MESSAGE

Method Summary

Modifier and Type	Method and 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.
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.
void	retain(int increment) Increment this reference manager's reference count by a given amount for the associated underlying memory.
OwnershipTransferResult	transferOwnership(ArrowBuf sourceBuffer, BufferAllocator targetAllocator) Duplicate the memory accounting ownership of the backing allocation of the given ArrowBuf in another allocator.

Field Detail

NO_OP_ERROR_MESSAGE

static final String NO_OP_ERROR_MESSAGE

See Also:

Constant Field Values

NO_OP

static final ReferenceManager NO_OP

Method Detail

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.