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 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 int` | `BYTE_BLOCK_MASK` | Use this to find the position of a global offset in a particular buffer.
    `static int` | `BYTE_BLOCK_SHIFT` | Use this to find the index of the buffer containing a byte, given an offset to that byte.
    `static 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

    All Methods Instance Methods Concrete Methods
    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 Detail

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

    - #### ByteBlockPool

          public ByteBlockPool​(ByteBlockPool.Allocator allocator)

  - ### Method Detail

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