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
    Modifier and Type | Class and 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 and Description
    --- | ---
    `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.

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

      `NULL_ACCOUNTABLE`

  - ### Constructor Summary

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

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `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`

Copyright © 2000-2021 Apache Software Foundation. All Rights Reserved.