perf(pine-java): pool OperatorOutput — requires nested-map → flat list refactor first

[Liam0205]

Context

#119 (PR #120) brought a profile-driven 7-9% ns/op + 19% B/op reduction to pine-go by pooling *OperatorOutput via sync.Pool in the scheduler, eliminating per-Execute alloc of OperatorOutput + the dominant itemWrites []ItemWrite grow cost.

The win does not transfer to pine-java. Java and Go runtimes are independent — sharing only the JSON contract and Apple DSL. #119 touched pine-go/internal/runtime/scheduler.go; nothing in that change reaches the JVM side.

Current Java state

pine-java/src/main/java/page/liam/pine/OperatorOutput.java uses:

private final Map<String, Object> commonWrites = new LinkedHashMap<>();
private final Map<Integer, Map<String, Object>> itemWrites = new HashMap<>();  // nested
private final List<Map<String, Object>> addedItems = new ArrayList<>();
private final Set<Integer> removedItems = new HashSet<>();

The blocker is structural, not lifetime-related:

Storage	Per-Execute behaviour	Pooling viability
itemWrites: Map<Integer, Map<String,Object>> (nested)	Each setItem(i, field, v) does computeIfAbsent(i, k -> new LinkedHashMap<>()).put(field, v) — tree-node alloc on first touch per row, then per-cell map put	Pooling the outer map keeps O(N) inner LinkedHashMaps live; clearing them on Reset is itself O(N×M) — worse than current alloc

pine-go had the same nested form historically (commit d238098 "replace nested map item writes with flat []ItemWrite slice", v0.7 era). The refactor unlocked everything downstream — including #119's pool. Java needs the same structural refactor first.

Suggested phasing

Phase 1 (refactor — separate PR, no pooling yet):

• Introduce ItemWrite { int index; String field; Object value; } record
• Change itemWrites to List<ItemWrite> (or ArrayList<ItemWrite> for capacity reuse later)
• Update Engine.applyOutput / ColumnFrame.applyOutput / DataFrame.applyOutput / ParallelExecutor.mergeOutputs to iterate the flat list
• Update Java fuzz / unit tests as needed; cross-validate's byte-equal /execute parity (scripts/cross-validate/02-engine-byte-exact.sh) gates correctness — no behaviour change should leak

Phase 2 (pool — once Phase 1 lands):

• Reset() method analogous to Go's: null slot refs, truncate to size 0 (ArrayList.clear() retains capacity)
• ThreadLocal<OperatorOutput> or ConcurrentLinkedDeque pool keyed at Engine instance
• Expect 5-10% throughput improvement based on Go numbers + JVM GC overhead profile

Why JVM-specific concerns matter

JVM is not Go:

• Short-lived objects often live in TLAB (Thread-Local Allocation Buffer), young gen, never reach old gen
• Escape analysis can sometimes stack-allocate
• BUT: nested LinkedHashMap allocs are heavy enough to escape TLAB on hot paths; profiling is required to confirm the win

Recommended approach: profile pine-java first via JMH (which #119 already noted is missing — see pine-java/benchmarks/'s placeholder note). If OperatorOutput.setItem map allocs dominate hot-path GC pressure, do Phase 1+2. If JVM is amortizing it away cheaply, defer indefinitely.

Risk

• Behaviour parity: byte-equal /execute parity is gated by cross-validate/02-engine-byte-exact.sh. Both phases must preserve it.
• Concurrency: Java's OperatorOutput is currently mutable-by-single-thread per Execute; the same contract must hold post-refactor.
• Phase 1 LOC: ~80-120 lines (Java reformat of the nested-map walk is the bulk).

Related

• perf: pool *OperatorOutput via sync.Pool — -7% ns/op + -19% B/op across all 3 lua backends #119 — the Go-side optimization that triggered this issue
• PR perf(scheduler): pool *OperatorOutput via sync.Pool + wangshu rc5 (#119) #120 — Go implementation that this Java counterpart would mirror at a structural level
• pine-go commit d238098 — the prior-art refactor (Go side, v0.7 era)

[Liam0205]

评估结论：不做 / defer indefinitely

刚做了端到端复测对一下口径，结论与本 issue 自己列出的 "Recommended approach: profile pine-java first via JMH... If JVM is amortizing it away cheaply, defer indefinitely" 完全吻合——前置条件不满足，应当 defer。

1. 前置条件未满足

issue 写：profile via JMH 是开工前提。但 pine-java/benchmarks/ 目录根本不存在（已确认）。JMH 还没起步就开工 Phase 1 重构，违反 issue 自定的纪律。

2. Java 端到端今天 ≥ Go（noise 带内）

2026-06-24 复跑 calibrated 三 fixture，10000 req × 16 conc，cgroup 2c4g：

Fixture	go QPS	java QPS	java/go
calibrated_2c4g	122.2	123.6	+1.2%
calibrated	121.9	123.5	+1.3%
calibrated_itemlua	121.5	126.5	+4.1%

nested LinkedHashMap 在 JVM 上已经被 TLAB / escape analysis / G1 摊掉——这正是 issue 自己列出的 JVM 特性。Java 端到端不慢于 Go，没有结构层 next-optimization 的入口。

3. issue 的"5-10% Java 收益"推算前提已崩

issue 写 "Expect 5-10% throughput improvement based on Go numbers"。但 Go 端 #119 落地前后 calibrated 端到端：

| 时间 | 状态 | go calibrated QPS | Δ |
|---|---:|---|
| 2026-06-11 | pre-#119 | 120.6 | baseline |
| 2026-06-24 | post-#119 | 121.9 | +1.1%（noise 带内） |

#119 在 wangshu 隔离 -9% sec/op / -19% B/op，但 Go 端到端 calibrated 完全不可见——这是 perf-evolution-roadmap 校准事实 2 的第 4 次实证（前 3 次：luajc / CallInto / args_mode 提案）。基于 Go 端到端"+1.1% noise"推算 Java 收益，前提崩了。

4. Phase 1 是纯成本无回报 risky 重构

issue 自估 80-120 行 Java，但实际触面：

• OperatorOutput 字段层重写
• Engine.applyOutput / ColumnFrame.applyOutput / DataFrame.applyOutput / ParallelExecutor.mergeOutputs 全面改动
• cross-validate Section 2 byte-equal 必须保持
• parity 审计 round 18-19 花大量精力的 OperatorException 传播路径要重审

只有 Phase 2 pool 端到端有收益时 Phase 1 才值得。而 Phase 2 收益先验在 Go 上已被证为不可见。

建议

defer 直到：

1. pine-java/benchmarks/ JMH 落地
2. 实测 OperatorOutput.setItem map allocs 在 hot-path GC pressure 占主导
3. 同时 calibrated 端到端 Java 显著弱于 Go（目前不是）

三个条件全部成立才重启。当前可以 close 或转 deferred 标签。