Add an interactive Hashtable internals demo

[bric3]

What Does This Do

Adds a standalone animated demo for datadog.trace.util.Hashtable. Each step keeps the abridged Java code, bucket array, linked entry chains, hash masking, and iterator state synchronized.

The demo contains five sections with a suggested scenario for each:

• Single key (D1)
  • Suggested scenario: insert same-hash and masked collisions, spread keys across other buckets, follow get through the linked chain, then mutate the returned entry in place.
• Composite key (D2)
  • Suggested scenario: store route counters keyed by HTTP method and status without allocating a composite key, then look up and update one route.
• Counter pattern (getOrCreate and forEach)
  • Suggested scenario: follow CardinalityLimitReporter from a miss through creator invocation and insertion, reuse the entry on a hit, summarize with a context-passing consumer, then clear the table.
• Chain surgery (insertOrReplace and remove)
  • Suggested scenario: traverse a collision chain with MutatingBucketIterator, expose its predecessor/current/next references in a separate band, replace a middle entry, then unlink the tail in constant time.
• Custom table (Hashtable.Support)
  • Suggested scenario: follow an AggregateTable across reporting cycles, leave one aggregate stale, miss on a new key at the logical cap, evict through a cursor-resumed sweep, then admit the new aggregate.

A final API map compares when to use D1, D2, or Support and summarizes their contracts.

Motivation

Hashtable is deliberately smaller and more specialized than HashMap, but several important mechanics are easy to miss during code review: an array slot points to a linked entry chain, bucket masking does not establish key identity, getOrCreate invokes its creator only after a miss, mutating iterators retain splice pointers, and custom callers own capacity and eviction policy.

The demo makes those relationships visible and gives reviewers concrete scenarios for the main APIs and their production usage.

Additional Notes

• The demo is standalone and does not change production behavior or add dependencies.
• Controlled hashes and an eight-bucket view keep the diagrams readable while preserving the relevant mechanics.
• The embedded JavaScript passes syntax checks, and the lookup, capacity, mutation, and lifecycle states were rendered in Firefox.

Contributor Checklist

• Format the title according to the contribution guidelines
• Assign the type: and (comp: or inst:) labels in addition to any other useful labels
• Avoid using close, fix, or any linking keywords when referencing an issue
• Update the CODEOWNERS file on source file addition, migration, or deletion
• Update public documentation with any new configuration flags or behaviors
• Once approved, use merge queue to merge the PR

Jira ticket: N/A

[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	14.77 s	14.80 s	[-1.3%; +0.8%] (no difference)
startup:insecure-bank:tracing:Agent	13.72 s	13.70 s	[-1.0%; +1.3%] (no difference)
startup:petclinic:appsec:Agent	17.55 s	16.92 s	[-0.8%; +8.2%] (no difference)
startup:petclinic:iast:Agent	17.49 s	17.53 s	[-1.0%; +0.5%] (no difference)
startup:petclinic:profiling:Agent	17.44 s	17.36 s	[-0.8%; +1.6%] (no difference)
startup:petclinic:sca:Agent	17.45 s	17.16 s	[+0.6%; +2.8%] (maybe worse)
startup:petclinic:tracing:Agent	16.54 s	16.61 s	[-1.4%; +0.6%] (no difference)

Commit: 63634d0d · 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.