Improve Performance

JMH + JFR Performance Optimization Skill

A skill for running JMH benchmarks, collecting JFR profiles, and driving iterative performance improvements in Java/Maven projects.

Workflow Overview

setup → benchmark → profile → analyze → change → repeat

Step 1 — Verify readiness

Confirm the workload under test is already covered by a JMH benchmark in the performance/ module (e.g. JavaVsJniReadBenchmark). If the column / codec / path is not benched, add it before profiling. Always pass a fully-qualified JMH filter (ClassName.methodName) when invoking the harness — never class-only or empty.

Step 2 — Use the existing benchmark script

./benchmark.sh in the repo root drives JMH + JFR. It runs:

./mvnw package -DskipTests -q -pl performance --also-make
java -jar performance/target/benchmarks.jar \
  ${BENCHMARK_FILTER} \
  -f 1 -wi 3 -i 5 \
  -rf json -rff performance/target/jmh-results.json \
  -jvmArgs "-XX:StartFlightRecording=filename=performance/target/recording.jfr,settings=profile"

Never substitute mvn for ./mvnw (project mandates the wrapper) and never run mvn install.

Step 3 — Run the baseline

./benchmark.sh JavaVsJniReadBenchmark.javaReadVolume

Read both output files:

• performance/target/jmh-results.json — throughput / latency per benchmark
• performance/target/recording-filtered.json — JFR events

Store the baseline score. Compare every subsequent run against it.

Step 4 — Analyze results

Key things to look for:

In jmh-results.json:

• primaryMetric.score — the main result (ops/s or ns/op depending on mode)
• primaryMetric.scoreError — high error = unstable benchmark, increase -i
• Compare AverageTime vs Throughput to understand the shape of the workload

In recording-filtered.json:

• jdk.ObjectAllocationInNewTLAB — allocation hotspots; look for large allocationSize or high-frequency small allocations in hot methods
• jdk.GarbageCollection — GC pause duration and frequency; long pauses = allocation pressure
• jdk.TLBMiss — high counts suggest memory access patterns not benefiting from huge pages
• jdk.GCHeapSummary — heap growth between events reveals live-set size

Priority order for investigation:

1. If GC pauses are long → reduce allocations first
2. If allocations are high but pauses are short → object pooling or value types
3. If TLB misses are high → evaluate huge pages or access pattern changes
4. If CPU is saturated with no GC/alloc issues → algorithmic / cache-locality problem

Step 5 — Apply one change at a time

Critical rule: change one thing per iteration.

Do not batch multiple optimizations. Each iteration must produce a clear before/after comparison so regressions are traceable.

Common optimizations to consider (in order of typical impact):

0. Branch-split modulo / division / variable-target branches out of hot loops. ⚠️ Top of the list because we shipped this regression twice in this codebase. A single i % cap per element blocks C2's auto-vectorizer (superword pass refuses Op_ModL/Op_DivL; no SIMD ISA has integer divide). Loop-invariant cap doesn't save you — strength-reduction needs a compile-time constant divisor. Per-element scalar modulo is also 20–40 cycles on Apple silicon. Combined: easy 5–10× throughput loss. Fix shape: hoist the divisor once, gate two specialized loop bodies on a single boolean check so the fast path has zero modulos and the slow path covers the rare case (broadcast, clamp, etc.).

   long cap = SegmentBroadcast.capacity(src, 8);
   if (cap == n) {
       for (long i = 0; i < n; i++) ... src.getAtIndex(LE_LONG, i) ...
   } else {
       for (long i = 0; i < n; i++) ... src.getAtIndex(LE_LONG, i % cap) ...
   }
   

   Same trap: per-element validity-bit checks, sign-extension switches, narrow-vs-wide branches — anything that makes the body non-uniform across rows. History: commit ed658b7 added modulo for ConstantEncoding broadcast safety with a (wrong) "JIT hoists it" claim; bisect later proved single-commit 5.5× regression on vortexRead. Fixes in 051a794, 442021f.
1. Allocate decode output from ctx.arena() — hard rule from CLAUDE.md. Never new byte[n] + MemorySegment.ofArray() for codec output: heap allocation, GC pressure, extra copy. Use ctx.arena().allocate(n * elemBytes, alignment) so the buffer lives on the confined arena tied to the VortexFile.
2. Reduce allocations elsewhere — reuse objects, use primitives, avoid boxing.
3. Hoist ValueLayout constants — declare static final ValueLayout.OfXxx L = ... so JIT constant-folds the stride / alignment / order. Inline ValueLayout.JAVA_LONG_UNALIGNED on each call defeats this.
4. Use getAtIndex / setAtIndex in tight loops over a MemorySegment — stride is implicit, bounds check hoists, and the auto-vectorizer reads the shape cleanly.
5. Aligned arena allocation — arena.allocate(n, 64) keeps SIMD-friendly addresses.
6. Improve data locality — colocate fields accessed together, prefer flat arrays / segments over linked structures.
7. Avoid synchronization on hot paths — VarHandle, AtomicLong, lock-free structures.
8. Reduce GC pressure — pool expensive objects, avoid finalizers, off-heap where justified.
9. Enable huge pages — add -XX:+UseTransparentHugePages to jvmArgs for comparison.

After each change, run ./bench and compare the new score against the stored baseline. If JFR -prof stack:lines=10 shows idiv, sdiv, or any arithmetic-helper frame as a hot stack, suspect modulo/division in a hot loop first — go straight to #0.

Step 6 — Report progress

After each iteration, report:

Iteration N
  Change   : <one-line description of what changed>
  Before   : <score> ± <error> <unit>
  After    : <score> ± <error> <unit>
  Delta    : <+/- %>
  JFR note : <key observation from JFR events>
  Next     : <what to investigate next>

If performance regressed, revert the change immediately and explain why it likely hurt.

Step 7 — Stop conditions

Stop iterating when any of the following is true:

• The goal stated by the user has been reached
• Three consecutive iterations produce < 2% improvement
• All obvious hotspots from JFR have been addressed
• The user says stop

Produce a final summary table of all iterations.

Important constraints

• Never modify the benchmark harness (@Benchmark, @Setup, @TearDown) unless the user explicitly asks. Benchmark changes invalidate all prior comparisons.
• Do not change JMH flags (-f, -wi, -i) between iterations. Consistency is required for valid comparisons.
• Keep JFR event filter consistent across all runs.
• If jmh-results.json shows scoreError > 10% of score, warn the user the benchmark is noisy and suggest increasing -i before drawing conclusions.