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

Class that Posting and PostingVector use to write byte streams into shared fixed-size byte[] arrays. The idea is to allocate slices of increasing lengths For example, the first slice is 5 bytes, the next slice is 14, etc. We start by writing our bytes into the first 5 bytes. When we hit the end of the slice, we allocate the next slice and then write the address of the new slice into the last 4 bytes of the previous slice (the "forwarding address"). Each slice is filled with 0's initially, and we mark the end with a non-zero byte. This way the methods that are writing into the slice don't need to record its length and instead allocate a new slice once they hit a non-zero byte.

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

### Nested Class Summary

Nested Classes
`static class` `ByteBlockPool.Allocator` Abstract class for allocating and freeing byte blocks.
`static 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
`byte[]` `buffer` Current head buffer
`byte[][]` `buffers` array of buffers currently used in the pool.
`static int` `BYTE_BLOCK_MASK`
`static int` `BYTE_BLOCK_SHIFT`
`static int` `BYTE_BLOCK_SIZE`
`int` `byteOffset` Current head offset
`int` `byteUpto` Where we are in head buffer
`static int` `FIRST_LEVEL_SIZE` The first level size for new slices
`static int[]` `LEVEL_SIZE_ARRAY` An array holding the level sizes for byte slices.
`static int[]` `NEXT_LEVEL_ARRAY` An array holding the offset into the `LEVEL_SIZE_ARRAY` to quickly navigate to the next slice level.

### Constructor Summary

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

### Method Summary

All Methods Instance Methods Concrete Methods
`int` `allocSlice(byte[] slice, int upto)` Creates a new byte slice with the given starting size and returns the slices offset in the pool.
`void` `append(BytesRef bytes)` Appends the bytes in the provided `BytesRef` at the current position.
`int` `newSlice(int size)` Allocates a new slice with the given size.
`void` `nextBuffer()` Advances the pool to its next buffer.
`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()` Resets the pool to its initial state reusing the first buffer and fills all buffers with `0` bytes before they reused or passed to `ByteBlockPool.Allocator.recycleByteBlocks(byte[][], int, int)`.
`void` `reset(boolean zeroFillBuffers, boolean reuseFirst)` Expert: Resets the pool to its initial state reusing the first buffer.
`void` `setBytesRef(BytesRef term, int textStart)`
`void` `setRawBytesRef(BytesRef ref, long offset)` Set the given `BytesRef` so that its content is equal to the `ref.length` bytes starting at `offset`.

### 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 Detail

#### BYTE_BLOCK_SHIFT

    public static final int BYTE_BLOCK_SHIFT

See Also:
  Constant Field Values

#### BYTE_BLOCK_SIZE

    public static final int BYTE_BLOCK_SIZE

See Also:
  Constant Field Values

#### BYTE_BLOCK_MASK

    public static final int BYTE_BLOCK_MASK

See Also:
  Constant Field Values

#### buffers

    public byte[][] buffers

array of buffers currently used in the pool. Buffers are allocated if needed don't modify this outside of this class.

#### byteUpto

    public int byteUpto

Where we are in head buffer

#### buffer

    public byte[] buffer

Current head buffer

#### byteOffset

    public int byteOffset

Current head offset

#### NEXT_LEVEL_ARRAY

    public static final int[] NEXT_LEVEL_ARRAY

An array holding the offset into the `LEVEL_SIZE_ARRAY` to quickly navigate to the next slice level.

#### LEVEL_SIZE_ARRAY

    public static final int[] LEVEL_SIZE_ARRAY

An array holding the level sizes for byte slices.

#### FIRST_LEVEL_SIZE

    public static final int FIRST_LEVEL_SIZE

The first level size for new slices

See Also:
  `newSlice(int)`

### Constructor Detail

#### ByteBlockPool

    public ByteBlockPool(ByteBlockPool.Allocator allocator)

### Method Detail

#### reset

    public void reset()

Resets the pool to its initial state reusing the first buffer and fills all buffers with `0` bytes before they reused or passed to `ByteBlockPool.Allocator.recycleByteBlocks(byte[][], int, int)`. Calling `nextBuffer()` is not needed after reset.

#### reset

    public void reset(boolean zeroFillBuffers,
                      boolean reuseFirst)

Expert: Resets the pool to its initial state reusing the first buffer. Calling `nextBuffer()` is not needed after reset.

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()

Advances the pool to its next buffer. This method should be called once after the constructor to initialize the pool. In contrast to the constructor a `reset()` call will advance the pool to its first buffer immediately.

#### newSlice

    public int newSlice(int size)

Allocates a new slice with the given size.

See Also:
  `FIRST_LEVEL_SIZE`

#### allocSlice

    public int allocSlice(byte[] slice,
                          int upto)

Creates a new byte slice with the given starting size and returns the slices offset in the pool.

#### setBytesRef

    public void setBytesRef(BytesRef term,
                            int textStart)

#### append

    public void append(BytesRef bytes)

Appends the bytes in the provided `BytesRef` at the current position.

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

#### setRawBytesRef

    public void setRawBytesRef(BytesRef ref,
                               long offset)

Set the given `BytesRef` so that its content is equal to the `ref.length` bytes starting at `offset`. Most of the time this method will set pointers to internal data-structures. However, in case a value crosses a boundary, a fresh copy will be returned. On the contrary to `setBytesRef(BytesRef, int)`, this does not expect the length to be encoded with the data.

#### readByte

    public byte readByte(long offset)

Read a single byte at the given `offset`.

#### 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`