Add FlatHashtable

[dougqh]

What Does This Do

Adds a light weight map-like FlatHashtable suitable for a variety of use cases
FlatHashtable is often suitable replacement for both HashMap and TreeMap

Motivation

Provide a safer, faster, lighter alternative to regular JDK Map-s. Unlike JDK Map-s, FlatHashtable is bounded in size by default, but the caller can still resize if necessary.

FlatHashtable's API is also designed to work with static polymorphism patterns to allow for optimal performance while serving as...

• case-insensitive map
• simple bounded lock free cache

Additional Notes

From Claude:

A reusable open-addressed, single-array find-or-create table over self-contained entries — one reference per slot, so entry publication is a single reference store and readers see null-or-complete (no torn reads, no volatile/atomics when the payload makes a stale/lost read benign). Pure mechanism; cardinality cap / overflow / live-size counting are caller policy.

Intended as the general-purpose primitive of the flat-collection family — the one to reach for by default in perf-critical core code (works mutable and immutable, with POJO or Entry objects, and with custom hashing/matching). The narrower members are triggered specialists: StringIndex (expert dense name→ID interner), a future TreeTable (ordered), ConcurrentHashtable (concurrent writers); simple immutable cases stay on Set.copyOf/Map.copyOf.

Bounded by construction (a safety primitive, not just a fast one)

create takes a cardinality budget, so you can't build one without deciding how big it may get — the question whose unasked version becomes an unbounded-growth leak in a long-lived agent embedded in someone else's process. A regular Map's auto-resize lets you forget that (fine when you own the heap; the wrong default when you're a guest). The table never grows on its own — get/getOrCreate/insert cap (a full table degrades to recompute-on-miss with bounded memory, no reallocation); growth is an explicit resize/resizingInsert. It defaults to the bounded-footprint posture the agent needs, with unbounded growth an opt-in you must reach for. (Trade pays when a miss is benign — a cache/interner — not a must-hold-everything map.)

Static-polymorphism strategies

Split by concern, each held as a concrete-typed static final singleton the JIT devirtualizes and inlines (one algorithm, one monomorphic instantiation per call site):

• MatchingStrategy<E,K> — key side (get/getOrCreate): matches(entry, key) + hashKey(key) defaulting to key.hashCode() (override only for custom hashing, e.g. case-insensitive). A @FunctionalInterface.
• HashStrategy<E> — entry side (insert/iterator/resize): hashOf(entry). For Entry-based tables it's the cached Entry.hash, so those get strategy-free overloads.
• EntryStrategy<E,K> — both, the abstract base a do-everything user extends.
• CaseInsensitiveStringStrategy<E> — seals hashKey to the new, allocation-free Strings.caseInsensitiveHashCode (consistent with String.equalsIgnoreCase).
• CreateStrategy<E,K> — cold entry minting (non-capturing lambda / ctor-ref).

The table owns the spread (home — a golden-ratio/Fibonacci mix), so a strategy returns a plain hashCode; hashKey(key) must stay consistent with hashOf(entry).

Operations

capacityFor/create (typed backing array) with load-factor control — DEFAULT_LOAD_FACTOR (0.5) / LOW_LOAD_FACTOR (0.25) + (…, float) overloads; get/getOrCreate; insert (Entry and strategy flavors); resize/resizingInsert; forEach; iterator (hash-filtered, specialized via the same static-polymorphism move so Entry iteration inlines hashOf — plain Iterator<E> API unchanged).

Benchmarks (JMH, Zulu 21)

• Map comparisons (SingleThreadedMapBenchmark/ThreadSafeMapBenchmark): FlatHashtable vs HashMap/TreeMap/ConcurrentHashMap. A CHA-defeat rig + -XX:+PrintInlining confirms the strategy calls devirtualize structurally (constant INSTANCE), not via a CHA/type-profile bet. Plain get runs in the billions of ops/s (cached String.hashCode, single probe).
• CaseInsensitiveMapBenchmark: the CI FlatHashtable is ~2× TreeMap at the same zero allocation and matches HashMap's throughput without HashMap's per-lookup toLowerCase garbage. (All three create arms do equal work; LOW_LOAD_FACTOR is a wash — the char-fold dominates.)
• FlatHashtableIteratorBenchmark: shows the iterator specialization is robust — @Setup poisons the shared hashOf type profile, after which the single-strategy general iterator pays 2.1× (18.1M vs 37.9M ops/s, F5), while the specialized iterator's constant type-flow is immune. Unpoisoned the two tie.

Stacked on #11984 (the @Strategy / @StrategyConsumer markers). Real callers land separately (tick-tock).

🤖 Generated with Claude Code

[datadog-prod-us1-6]

🎯 Code Coverage (details)
• Patch Coverage: 100.00%
• Overall Coverage: 57.33% (+0.04%)

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 60a69a3 | Docs | Datadog PR Page | Give us feedback!}

[dd-octo-sts]

🟢 Java Benchmark SLOs — All performance SLOs passed

Suite	Status
Startup	🟢 pass

SLO thresholds are defined here based on automatically generated metrics. A warning is raised when results are within 5% of the threshold.

PR vs. master results

Scenario	Candidate	master	Δ (95% CI of mean)
startup:insecure-bank:iast:Agent	13.99 s	13.90 s	[-0.2%; +1.4%] (no difference)
startup:insecure-bank:tracing:Agent	12.91 s	13.00 s	[-1.3%; +0.0%] (no difference)
startup:petclinic:appsec:Agent	16.95 s	16.43 s	[+2.0%; +4.3%] (significantly worse)
startup:petclinic:iast:Agent	16.88 s	16.82 s	[-0.3%; +1.1%] (no difference)
startup:petclinic:profiling:Agent	16.01 s	16.86 s	[-9.3%; -0.8%] (maybe better)
startup:petclinic:sca:Agent	16.80 s	16.73 s	[-0.5%; +1.4%] (no difference)
startup:petclinic:tracing:Agent	16.11 s	15.68 s	[-1.5%; +6.9%] (no difference)

Commit: 60a69a39 · CI Pipeline · Benchmarking Platform UI

---

Load and DaCapo benchmarks can be triggered manually in the GitLab pipeline. Results will appear in the Benchmarking Platform UI after completion.

[datadog-prod-us1-6]

More details

The FlatHashtable implementation is logically sound across every adversarial scenario tested — full-table iteration with no null sentinel, iterator wrap-around starting at a non-zero home slot, non-ASCII case folding (Turkish ı/İ) staying consistent with equalsIgnoreCase, and resize preserving findability of collided entries. No behavioral regressions or contract violations were found.

Was this helpful? React 👍 or 👎

_{📊 Validated against 10 scenarios · Open Bits AI session}

_{🤖 Datadog Autotest · Commit ba5e1c6 · What is Autotest? · Any feedback? Reach out in #autotest}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ba5e1c6b60

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[datadog-prod-us1-6]

Executed 12 adversarial scenarios covering capacityFor edge cases, caseInsensitiveHashCode consistency with equalsIgnoreCase across HTTP headers and Unicode (including Turkish-I and German ß), iterator wrap-around on full tables, and mixed-hash probe filtering. One real defect found: capacityFor silently returns Integer.MIN_VALUE (-2^31) for cardinalityLimit >= 536870913 at DEFAULT_LOAD_FACTOR (or >= 268435457 at LOW_LOAD_FACTOR) because Integer.highestOneBit(min-1) << 1 overflows; the caller's subsequent Array.newInstance then throws an opaque NegativeArraySizeException. Fixed with a post-shift guard that throws a clear IllegalArgumentException, and a test case was added to lock in the rejection.

_{📊 Validated against 12 scenarios · Open Bits AI session}

_{🤖 Datadog Autotest · Commit 60a69a3 · What is Autotest? · Any feedback? Reach out in #autotest}

[datadog-prod-us1-6]

capacityFor silently returns negative capacity on large cardinalities

Any caller that passes a cardinality > 536870912 (at DEFAULT_LOAD_FACTOR) or > 268435456 (at LOW_LOAD_FACTOR) gets a confusing NegativeArraySizeException from deep inside create(), not a clear argument error. Fixed by adding a post-shift guard.

Assertion details

• Input: FlatHashtable.capacityFor(536870913, DEFAULT_LOAD_FACTOR) — first cardinality at 0.5 load factor where required capacity (2^31) exceeds Integer.MAX_VALUE
• Expected: IllegalArgumentException with clear message, or a valid positive power-of-two capacity
• Actual: Returns Integer.MIN_VALUE (-2147483648); any subsequent Array.newInstance call throws an opaque NegativeArraySizeException rather than a clear precondition violation

Was this helpful? React 👍 or 👎
_{🤖 Datadog Autotest · What is Autotest? · Any feedback? Reach out in #autotest}

Suggested change

	return Integer.highestOneBit(min - 1) << 1;
	int cap = Integer.highestOneBit(min - 1) << 1;
	if (cap <= 0) {
	throw new IllegalArgumentException(
	"cardinalityLimit " + cardinalityLimit + " at loadFactor " + loadFactor
	+ " requires capacity > Integer.MAX_VALUE");
	}
	return cap;