Package org.apache.lucene.util

# Class ByteBlockPool

java.lang.Object
org.apache.lucene.util.ByteBlockPool

All Implemented Interfaces:
  `Accountable`

public final class ByteBlockPool extends Object implements Accountable
This class enables the allocation of fixed-size buffers and their management as part of a buffer array. Allocation is done through the use of an `ByteBlockPool.Allocator` which can be customized, e.g. to allow recycling old buffers. There are methods for writing (`append(BytesRef)` and reading from the buffers (e.g. `readBytes(long, byte[], int, int)`, which handle read/write operations across buffer boundaries.

NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static class`
`ByteBlockPool.Allocator`
Abstract class for allocating and freeing byte blocks.
`static final class`
`ByteBlockPool.DirectAllocator`
A simple `ByteBlockPool.Allocator` that never recycles.
`static class`
`ByteBlockPool.DirectTrackingAllocator`
A simple `ByteBlockPool.Allocator` that never recycles, but tracks how much total RAM is in use.

## Field Summary

Fields
Modifier and Type
Field
Description
`byte[]`
`buffer`
Current head buffer.
`static final int`
`BYTE_BLOCK_MASK`
Use this to find the position of a global offset in a particular buffer.
`static final int`
`BYTE_BLOCK_SHIFT`
Use this to find the index of the buffer containing a byte, given an offset to that byte.
`static final int`
`BYTE_BLOCK_SIZE`
The size of each buffer in the pool.
`int`
`byteOffset`
Offset from the start of the first buffer to the start of the current buffer, which is bufferUpto * BYTE_BLOCK_SIZE.
`int`
`byteUpto`
Where we are in the head buffer.

### Fields inherited from interface org.apache.lucene.util.Accountable

`NULL_ACCOUNTABLE`

## Constructor Summary

Constructors
Constructor
Description
`ByteBlockPool(ByteBlockPool.Allocator allocator)`

## Method Summary

Modifier and Type
Method
Description
`void`
`append(byte[] bytes)`
Append the provided byte array at the current position.
`void`
`append(byte[] bytes, int offset, int length)`
Append some portion of the provided byte array at the current position.
`void`
`append(ByteBlockPool srcPool, long srcOffset, int length)`
Append the bytes from a source `ByteBlockPool` at a given offset and length
`void`
`append(BytesRef bytes)`
Appends the bytes in the provided `BytesRef` at the current position.
`byte[]`
`getBuffer(int bufferIndex)`
Retrieve the buffer at the specified index from the buffer pool.
`long`
`getPosition()`
the current position (in absolute value) of this byte pool
`void`
`nextBuffer()`
Allocates a new buffer and advances the pool to it.
`long`
`ramBytesUsed()`
Return the memory usage of this object in bytes.
`byte`
`readByte(long offset)`
Read a single byte at the given offset
`void`
`readBytes(long offset, byte[] bytes, int bytesOffset, int bytesLength)`
Reads bytes out of the pool starting at the given offset with the given length into the given byte array at offset `off`.
`void`
`reset(boolean zeroFillBuffers, boolean reuseFirst)`
Expert: Resets the pool to its initial state, while optionally reusing the first buffer.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Methods inherited from interface org.apache.lucene.util.Accountable

`getChildResources`

## Field Details

### BYTE_BLOCK_SHIFT

public static final int BYTE_BLOCK_SHIFT
Use this to find the index of the buffer containing a byte, given an offset to that byte.

bufferUpto = globalOffset >> BYTE_BLOCK_SHIFT

bufferUpto = globalOffset / BYTE_BLOCK_SIZE

See Also:
  - Constant Field Values

### BYTE_BLOCK_SIZE

public static final int BYTE_BLOCK_SIZE
The size of each buffer in the pool.

See Also:
  - Constant Field Values

### BYTE_BLOCK_MASK

public static final int BYTE_BLOCK_MASK
Use this to find the position of a global offset in a particular buffer.

positionInCurrentBuffer = globalOffset & BYTE_BLOCK_MASK

positionInCurrentBuffer = globalOffset % BYTE_BLOCK_SIZE

See Also:
  - Constant Field Values

### byteUpto

public int byteUpto
Where we are in the head buffer.

### buffer

public byte[] buffer
Current head buffer.

### byteOffset

public int byteOffset
Offset from the start of the first buffer to the start of the current buffer, which is bufferUpto * BYTE_BLOCK_SIZE. The buffer pool maintains this offset because it is the first to overflow if there are too many allocated blocks.

## Constructor Details

### ByteBlockPool

public ByteBlockPool(ByteBlockPool.Allocator allocator)

## Method Details

### reset

public void reset(boolean zeroFillBuffers, boolean reuseFirst)
Expert: Resets the pool to its initial state, while optionally reusing the first buffer. Buffers that are not reused are reclaimed by `ByteBlockPool.Allocator.recycleByteBlocks(byte[][], int, int)`. Buffers can be filled with zeros before recycling them. This is useful if a slice pool works on top of this byte pool and relies on the buffers being filled with zeros to find the non-zero end of slices.

Parameters:
  `zeroFillBuffers` - if `true` the buffers are filled with `0`. This should be set to `true` if this pool is used with slices.
  `reuseFirst` - if `true` the first buffer will be reused and calling `nextBuffer()` is not needed after reset iff the block pool was used before ie. `nextBuffer()` was called before.

### nextBuffer

public void nextBuffer()
Allocates a new buffer and advances the pool to it. This method should be called once after the constructor to initialize the pool. In contrast to the constructor, a `reset(boolean, boolean)` call will advance the pool to its first buffer immediately.

### append

public void append(BytesRef bytes)
Appends the bytes in the provided `BytesRef` at the current position.

### append

public void append(ByteBlockPool srcPool, long srcOffset, int length)
Append the bytes from a source `ByteBlockPool` at a given offset and length

Parameters:
  `srcPool` - the source pool to copy from
  `srcOffset` - the source pool offset
  `length` - the number of bytes to copy

### append

public void append(byte[] bytes)
Append the provided byte array at the current position.

Parameters:
  `bytes` - the byte array to write

### append

public void append(byte[] bytes, int offset, int length)
Append some portion of the provided byte array at the current position.

Parameters:
  `bytes` - the byte array to write
  `offset` - the offset of the byte array
  `length` - the number of bytes to write

### readBytes

public void readBytes(long offset, byte[] bytes, int bytesOffset, int bytesLength)
Reads bytes out of the pool starting at the given offset with the given length into the given byte array at offset `off`.

Note: this method allows to copy across block boundaries.

### readByte

public byte readByte(long offset)
Read a single byte at the given offset

Parameters:
  `offset` - the offset to read
Returns:
  the byte

### ramBytesUsed

public long ramBytesUsed()
Description copied from interface: `Accountable`
Return the memory usage of this object in bytes. Negative values are illegal.

Specified by:
  `ramBytesUsed` in interface `Accountable`

### getPosition

public long getPosition()
the current position (in absolute value) of this byte pool

### getBuffer

public byte[] getBuffer(int bufferIndex)
Retrieve the buffer at the specified index from the buffer pool.