Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -851,9 +851,7 @@ private static <E> boolean placeAt(E[] table, E entry, long hash) {
* Package-private so tests can predict slots.
*/
static int home(long hash, int mask) {
long z = hash * 0x9E3779B97F4A7C15L; // 2^64 / golden ratio; odd ⇒ a bijection (loses no bits)
z ^= z >>> 32; // fold the well-mixed high half down into the low bits the mask keeps
return (int) z & mask;
return LongHashingUtils.hashSpread(hash) & mask;
}

/**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -171,6 +171,25 @@ public static final int hash(Object[] objs) {
return result;
}

/**
* Spreads a hash code across all 32 bits, for a table that takes its slot from the low bits. A
* golden-ratio (Fibonacci) multiply mixes the low input bits into the high bits of the product,
* and the fold brings those back down. So keys whose hash codes differ only slightly, such as
* sequential names like {@code key-00001} and {@code key-00002}, land far apart instead of in
* adjacent slots that grow into long probe runs. The multiplier is odd, so the multiply loses no
* bits.
*
* <p>One 32-bit multiply, a shift and an xor: cheap enough for lookups of keys that are already
* well spread. For a 64-bit composite hash, use {@link LongHashingUtils#hashSpread(long)}.
*
* @param hash a hash code.
* @return the spread hash: mask it for a slot, or store it.
*/
public static int hashSpread(int hash) {
final int z = hash * 0x9E3779B9; // 2^32 / golden ratio
return z ^ (z >>> 15);
}

/**
* A {@code hashCode} consistent with {@link String#equalsIgnoreCase}: any two strings that are
* equal ignoring case produce the same value. Same polynomial as {@link String#hashCode} but over
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,21 @@
public final class LongHashingUtils {
private LongHashingUtils() {}

/**
* Spreads a 64-bit hash into 32 bits, for a table that takes its slot from the low bits. A
* golden-ratio (Fibonacci) multiply mixes every input bit into the high half of the product, and
* the fold brings that half down, so hashes that differ only slightly land far apart. The
* multiplier is odd, so the multiply loses no bits. For a 32-bit hash code, {@link
* HashingUtils#hashSpread(int)} is cheaper.
*
* @param hash a 64-bit hash, such as one combined with {@link #addToHash}.
* @return the spread hash: mask it for a slot, or store it.
*/
public static int hashSpread(long hash) {
final long z = hash * 0x9E3779B97F4A7C15L; // 2^64 / golden ratio
return (int) (z ^ (z >>> 32));
}

public static final long hash(Object obj) {
return obj == null ? Long.MIN_VALUE : obj.hashCode();
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -169,10 +169,13 @@ public static final class Data {
public static final class EmbeddingSupport {
private EmbeddingSupport() {}

/** Spread of String.hashCode; 0 reserved as the empty sentinel. */
/**
* {@link HashingUtils#hashSpread} of String.hashCode, so sequential names don't cluster under
* linear probing; 0 reserved as the empty sentinel.
*/
public static int hash(String name) {
int h = name.hashCode(); // cached on String -> field load
return h == 0 ? 0xDD06 : h ^ (h >>> 16);
final int h = HashingUtils.hashSpread(name.hashCode()); // hashCode is cached on String

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Measure the claimed lookup optimization

The commit presents this shipped toolbox change as an “FFE optimization” and says misses “gain the most”, but explicitly states that timing has not been measured. The exact probe counts demonstrate improved distribution, not an end-to-end lookup-speed improvement; the additional hash mixing also changes the tradeoff for already well-distributed keys. Include JMH before/after time and allocation results from the same machine, JDK, JVM flags, and benchmark settings (-Pjmh.profilers=gc), or drop the performance claim until those results exist.

AGENTS.md reference: AGENTS.md:L82-L84

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Measured since this review, and the description now has the JMH results (5 forks per variant, 4 threads, same machine and JDK, -prof gc, 0 B/op throughout). The data also changed the code: the PR now spreads hash codes with a 32-bit multiply (HashingUtils.hashSpread(int)), because the 64-bit one reviewed here cost +4–5% on random-key hits. With the 32-bit spread, sequential misses are −30% to −49% and random hits stay within noise of h ^ (h >>> 16). The 64-bit spread moved to LongHashingUtils.hashSpread(long) for FlatHashtable, whose slots don't change.

return h == 0 ? 0xDD06 : h;
}

/**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNotEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

import java.util.Arrays;
import org.junit.jupiter.api.Test;
Expand Down Expand Up @@ -270,4 +271,30 @@ static final String[] deepClone(String[] strings) {
}
return clones;
}

@Test
void hashSpreadIsTheFibonacciMultiplyFolded() {
for (final int hash : new int[] {0, 1, -1, 42, Integer.MIN_VALUE, Integer.MAX_VALUE}) {
final int z = hash * 0x9E3779B9;
assertEquals(z ^ (z >>> 15), HashingUtils.hashSpread(hash));
}
assertEquals(0, HashingUtils.hashSpread(0));
assertNotEquals(HashingUtils.hashSpread(1), HashingUtils.hashSpread(2));
}

@Test
void hashSpreadSendsAdjacentHashesToDistantSlots() {
final int mask = (1 << 12) - 1;
final boolean[] used = new boolean[mask + 1];
int distinct = 0;
for (int h = 0; h < 1_000; h++) {
final int slot = HashingUtils.hashSpread(h) & mask;
if (!used[slot]) {
used[slot] = true;
distinct++;
}
}
// Consecutive hashes would fill 1,000 adjacent slots; spread, few of them share a slot.
assertTrue(distinct > 800, "distinct slots " + distinct);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we assert the longest occupied run here, or rely on the probe-length regression test in StringIndexTest? With the old XOR spread, hashes 0 through 999 land in 1,000 distinct but consecutive slots, so this assertion also passes for the clustering the test name describes.

--- found by Codex

}
}
Original file line number Diff line number Diff line change
Expand Up @@ -189,4 +189,12 @@ void multiArgHashTreatsNullAsZero() {
int xHash = Objects.hashCode("x");
assertEquals(31L * 0 + xHash, hash(null, "x"));
}

@Test
void hashSpreadIsTheFibonacciMultiplyFoldedTo32Bits() {
for (final long hash : new long[] {0L, 1L, -1L, 42L, Long.MIN_VALUE, Long.MAX_VALUE}) {
final long z = hash * 0x9E3779B97F4A7C15L;
assertEquals((int) (z ^ (z >>> 32)), LongHashingUtils.hashSpread(hash));
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,7 @@ void hash_spread_and_zeroSentinel() {
// "".hashCode() == 0 -> remapped to the non-zero sentinel so 0 can mean "empty slot"
assertEquals(0xDD06, EmbeddingSupport.hash(""));

int raw = "foo".hashCode();
assertEquals(raw ^ (raw >>> 16), EmbeddingSupport.hash("foo"));
assertEquals(HashingUtils.hashSpread("foo".hashCode()), EmbeddingSupport.hash("foo"));
assertNotEquals(0, EmbeddingSupport.hash("foo"));
}

Expand Down Expand Up @@ -227,4 +226,26 @@ void support_numSlots_matchesTableSize() {
Data d = EmbeddingSupport.create("a", "b", "c");
assertEquals(d.hashes.length, EmbeddingSupport.numSlots(d.hashes));
}

@Test
void sequentialNamesDoNotClusterUnderLinearProbing() {
// Names that differ only in a trailing counter have nearly equal String.hashCodes. Without a
// multiplicative spread they fill runs of adjacent slots: with h ^ (h >>> 16), these 10,030
// names average 6.3 probes, with a worst case of 156.
final int n = 10_030;
final int[] hashes = new int[EmbeddingSupport.capacityFor(n)];
final String[] names = new String[hashes.length];
final int mask = hashes.length - 1;
long probes = 0;
int worst = 0;
for (int i = 0; i < n; i++) {
final String name = String.format("scale-bulk-%05d", i);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we use String.format(Locale.ROOT, ...) here and in StringIndexKeyShapeBenchmark.name? This overload uses the JVM's default locale. For example, ar-EG formats the counter with Arabic-Indic digits, which changes the string hashes and probe counts. Pinning the locale keeps the regression test, benchmark, and probe counts in the PR description on the same ASCII dataset.

--- found by Codex

final int h = EmbeddingSupport.hash(name);
final int distance = ((EmbeddingSupport.put(hashes, names, name, h) - h) & mask) + 1;
probes += distance;
worst = Math.max(worst, distance);
}
assertTrue(probes < 2L * n, "average probes " + (double) probes / n);
assertTrue(worst < 32, "worst probe " + worst);
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
package datadog.trace.util;

import java.util.Random;
import java.util.concurrent.atomic.AtomicInteger;
import org.openjdk.jmh.annotations.Benchmark;
import org.openjdk.jmh.annotations.Fork;
import org.openjdk.jmh.annotations.Measurement;
import org.openjdk.jmh.annotations.Param;
import org.openjdk.jmh.annotations.Scope;
import org.openjdk.jmh.annotations.Setup;
import org.openjdk.jmh.annotations.State;
import org.openjdk.jmh.annotations.Threads;
import org.openjdk.jmh.annotations.Warmup;

/**
* {@link StringIndex} lookups by key shape: sequential names that differ only in a trailing counter
* ({@code scale-bulk-00001}, {@code scale-bulk-00002}, ...), as generated flag keys and ids are,
* against random names of the same length.
*
* <p>Sequential names have nearly equal {@code String.hashCode}s. Unless the hash spread mixes them
* apart, they fill runs of adjacent slots, and linear probing walks those runs: a hit probes until
* it reaches its key, and a miss probes until it reaches an empty slot. Random names show the cost
* when the spread doesn't matter. Hits look up distinct {@code String} instances, so {@code equals}
* runs as it does for keys read from a request or a payload.
*
* <p>Compare {@link HashingUtils#hashSpread} against the previous {@code h ^ (h >>> 16)} by running
* this benchmark on both, base and change alternating fork by fork.
*/
@Fork(3)
@Warmup(iterations = 3)
@Measurement(iterations = 5)
@Threads(8)
@State(Scope.Benchmark)
public class StringIndexKeyShapeBenchmark {
@Param({"sequential", "random"})
public String keys;

@Param({"64", "1024", "10030"})
public int size;

private StringIndex index;
private String[] hits;
private String[] misses;

@Setup
public void setUp() {
final String[] names = new String[size];
hits = new String[size];
misses = new String[size];
final Random random = new Random(42);
for (int i = 0; i < size; i++) {
names[i] = name(i, random);
// A distinct instance with the same characters, so equals runs on a hit.
hits[i] = new String(names[i].toCharArray());
misses[i] = name(size + i, random);
}
index = StringIndex.of(names);
}

private String name(final int i, final Random random) {
if ("sequential".equals(keys)) {
return String.format("scale-bulk-%05d", i);
}
final char[] chars = new char[16];
for (int c = 0; c < chars.length; c++) {
chars[c] = (char) ('a' + random.nextInt(26));
}
return new String(chars);
}

/** Each thread walks the keys from its own offset. */
@State(Scope.Thread)
public static class Cursor {
private static final AtomicInteger THREADS = new AtomicInteger();

int next = THREADS.getAndIncrement() * 7919;

int next(final int size) {
final int i = Math.floorMod(next, size);
next = i + 1;
return i;
}
}

@Benchmark
public int hit(final Cursor cursor) {
return index.indexOf(hits[cursor.next(size)]);
}

@Benchmark
public int miss(final Cursor cursor) {
return index.indexOf(misses[cursor.next(size)]);
}
}