Package org.opensearch.common.util

Class ReorganizingLongHash

java.lang.Object
org.opensearch.common.util.ReorganizingLongHash
All Implemented Interfaces:
Closeable, AutoCloseable, org.opensearch.common.lease.Releasable
@InternalApi public class ReorganizingLongHash extends Object implements org.opensearch.common.lease.Releasable
Specialized hash table implementation that maps a (primitive) long to long.

It organizes itself by moving keys around dynamically in order to reduce the longest probe sequence length (PSL), which makes lookups faster as keys are likely to be found in the same CPU cache line. It also optimizes lookups for recently added keys, making it useful for aggregations where keys are correlated across consecutive hits.

This class is not thread-safe.

Opensearch.internal:

  • Constructor Summary

    Constructors
    Constructor
    Description
    ReorganizingLongHash(long initialCapacity, float loadFactor, BigArrays bigArrays)
     
    ReorganizingLongHash(BigArrays bigArrays)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    long
    add(long key)
    Adds the given key to the hash table and returns its ordinal.
    void
    close()
     
    long
    find(long key)
    Returns the ordinal associated with the given key, or -1 if the key doesn't exist.
    long
    get(long ordinal)
    Returns the key associated with the given ordinal.
    long
    size()
    Returns the number of mappings in this hash table.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • ReorganizingLongHash

      public ReorganizingLongHash(BigArrays bigArrays)

    • ReorganizingLongHash

      public ReorganizingLongHash(long initialCapacity, float loadFactor, BigArrays bigArrays)

  • Method Details

    • add

      public long add(long key)
      Adds the given key to the hash table and returns its ordinal. If the key exists already, it returns (-1 - ordinal).

    • get

      public long get(long ordinal)
      Returns the key associated with the given ordinal. The result is undefined for an unused ordinal.

    • find

      public long find(long key)
      Returns the ordinal associated with the given key, or -1 if the key doesn't exist.

      Using the 64-bit hash value, up to 32 least significant bits (LSB) are used to identify the home slot in the hash table, and an additional 16 bits are used to identify the fingerprint. The fingerprint further increases the entropy and reduces the number of false lookups in the keys' table during equality checks, which is expensive due to an uncorrelated memory lookup.

      Total entropy bits = 16 + log2(capacity)

      Linear probing starts from the home slot, until a match or an empty slot is found. Values are first checked using their fingerprint (to reduce false positives), then verified in the keys' table using an equality check.

    • size

      public long size()
      Returns the number of mappings in this hash table.

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Specified by:
      close in interface org.opensearch.common.lease.Releasable