Add FlatHashtable (perf toolbox)

[dougqh]

What Does This Do

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

Unlike Hashtable, can work with arbitrary types not just its own Entry subclasses

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

[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.87 s	[+0.0%; +1.7%] (maybe worse)
startup:insecure-bank:tracing:Agent	12.90 s	13.05 s	[-1.8%; -0.5%] (maybe better)
startup:petclinic:appsec:Agent	17.06 s	16.81 s	[+0.6%; +2.3%] (maybe worse)
startup:petclinic:iast:Agent	17.01 s	16.99 s	[-0.6%; +0.8%] (no difference)
startup:petclinic:profiling:Agent	16.74 s	16.93 s	[-2.4%; +0.2%] (no difference)
startup:petclinic:sca:Agent	16.84 s	16.66 s	[-0.0%; +2.1%] (no difference)
startup:petclinic:tracing:Agent	16.14 s	16.07 s	[-0.4%; +1.2%] (no difference)

Commit: e7eb628a · 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]

View session in Datadog

Bits Code status: ✅ Done

Comment @DataDog to request changes

[datadog-prod-us1-6]

The FlatHashtable creation benchmark does not apply duplicate updates that the HashMap and TreeMap benchmarks apply. This difference makes the creation results invalid.

_{Open Bits AI session}

_{🤖 Datadog Autotest · Commit 3586400 · What is Autotest? · @DataDog review to ask questions · Any feedback? Reach out in #autotest}

[amarziali]

Review via Claude (automated review). Verified against head 3586400f on OpenJDK 25.

Requesting changes — one blocking issue.

Strings.caseInsensitiveHashCode folds per UTF-16 char, but String.equalsIgnoreCase on JDK 9+ reconstructs supplementary code points before folding. I brute-forced every defined code point against its upper/lower/title variants, keeping only pairs where equalsIgnoreCase returns true:

equalsIgnoreCase-equal pairs checked: 4368
  current implementation mismatches:   846
  code-point fold mismatches:            0

Through CaseInsensitiveStringStrategy, two equal keys get different home slots — get stops at the first empty slot and false-misses, and getOrCreate silently inserts a duplicate. The method's javadoc asserts the opposite invariant, so it needs rewriting alongside the fix. Details and a validated patch are inline.

Five non-blocking comments are also inline (growth overflow, resizingInsert load factor, racy-publication wording, null-key contract, a broken javadoc link) — none of them block.

The probing, wraparound, full-table termination, resize, and iterator-specialization logic is carefully done and well covered, and the fixed-vs-growable split in D1/D2 makes the boundedness policy explicit at call sites.

[amarziali]

Thanks for having addressed the main point. I did not find any other outstanding blocking points.

[dougqh]

Thanks for having addressed the main point. I did not find any other outstanding blocking points.

@amarziali Thanks for the thorough review.

[dd-octo-sts]

/merge

[gh-worker-devflow-routing-ef8351]

View all feedbacks in Devflow UI.

2026-08-21 21:19:16 UTC ℹ️ Start processing command /merge

---

2026-08-21 21:19:22 UTC ℹ️ MergeQueue: pull request added to the queue

The expected merge time in master is approximately 2h (p90).

---

2026-08-21 22:23:51 UTC ℹ️ MergeQueue: This merge request was merged