perf: background-warm GatewayConnection class during startSocket (issue #557)

[Tagar]

Summary

Cold-start work, C2 of the issue py4j/py4j#557 series.

GatewayConnection.<clinit> references 14 command classes via class literals — so the first time GatewayConnection is touched at runtime, the JVM class-loads all 14 in sequence. Today that first touch happens inside the accept() loop when the first client connects, on the same thread that needs to immediately handshake back. The class-loading cost lands on the cold-call critical path.

This change kicks off a one-shot daemon thread inside startSocket() that calls Class.forName("py4j.GatewayConnection", true, classLoader) — its <clinit> runs in parallel with the bind() on the main thread. By the time a client connects and we instantiate the first GatewayConnection in the accept loop, the class data is already in the JVM's class cache.

What this is NOT

The original C2 plan also included "cache 14 command instance prototypes globally" to skip the clazz.newInstance() × 14 per connection in initCommands. I explored that and dropped it from this PR: Command instances hold per-connection state via init(gateway, connection), so they cannot be shared without changing the Command interface contract. The class-loading win above is the safe subset.

Risk: ~zero

• Pure work re-ordering — no API change, no behavior change for any existing caller.
• Best-effort: errors in the warm-up thread are swallowed; if Class.forName fails for any reason, the accept loop still triggers the same class-load on first connection — just without the parallelism benefit.
• Daemon thread — never blocks JVM exit.
• Thread name "py4j-warmup" for visibility in jstack output.

Expected impact

Modest: ~10-100 ms on first connect depending on filesystem cache state. Subsequent connects to the same JVM are unchanged (classes already loaded). Targets:

Scenario	Expected delta
XD (full cold start)	Some win each round (every round spawns a fresh JVM)
XB (gateway reconnect against running JVM)	Win on first iteration only
X1 / X2 / X4 / X6 (held connections)	None — connections are long-lived, classes loaded once

Local measurement

XD median ~350 ms with C2 applied (M-series + JDK 21). Variance on a single laptop with 5 rounds (~350-2400 ms range) is too high to see a 10-50 ms delta — CodSpeed CI's uniform hardware + larger sample size should surface it.

Diff

• py4j-java/src/main/java/py4j/GatewayServer.java: +41 / -0

Test plan

• All Python integration tests pass locally (83/83 in java_gateway_test + client_server_test, minus 14 pre-existing GatewayLauncher jar-path issues unrelated to this change)
• Java matrix CI green across Java 8/11/17/21 × ubuntu/macos/windows
• CodSpeed shows XD delta (small but consistent if the hypothesis holds)

[codspeed-hq]

Merging this PR will not alter performance

✅ 22 untouched benchmarks
⏩ 7 skipped benchmarks¹

---

_{Comparing c2-java-class-prewarm (12dd189) with master (77eb450)}

Footnotes

1. 7 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[Tagar]

Closing — the change is theoretically correct but its impact is permanently below CodSpeed's noise floor on our current scenarios.

Evidence

After rebasing onto post-#16 master (which tightened XD's polling and got us to 2 samples with proper variance):

Scenario	Time	Noise	Samples
XD (full cold start)	1.08 s	3.2%	2
XB (gateway reconnect, warm JVM)	65 ms	6.4%	32

C2's expected impact is 10-30 ms shaved off first-connect class loading = 0.9-2.8% of XD's 1.08 s baseline. CodSpeed's measured noise on XD is 3.2% — C2's signal is permanently below it.

Why XD can't shrink further with py4j-side work

The 1.08 s breaks down approximately as:

• JVM subprocess spawn: ~200 ms
• JDK bootstrap + JIT C1 warmup: ~600-800 ms ← bedrock, py4j has no lever here
• py4j class load + handshake: ~50-100 ms ← only this slice is what C2 targets

To make XD shrink enough for py4j-class-level optimizations to be visible (and to dent the user's reported 3 s cold start in issue py4j#557 generally), we need JVM-level levers — AppCDS, -XX:TieredStopAtLevel=1, CRaC. C2's class-load parallelism would be a rounding error on top of those.

No correctness concerns

The implementation itself was reviewed clean: pure work-reordering, JVM's per-class <clinit> lock guarantees no race, best-effort daemon thread, zero API change. If JVM-level cold-start work later changes the breakdown such that py4j class loading becomes a meaningful fraction, this PR can be revived as-is.