Files
ForgeMultipart/JAVA_MIGRATION_PROFILE.md
T

225 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Java migration — focused performance baseline and results
This is the reproducible pre-optimization baseline for Phase 4. It runs inside the real deobfuscated Forge dedicated
server, using the same generated tiles as the functional suite. It is intentionally focused rather than a claim about
whole-pack TPS.
The broader follow-up is planned in [Phase 4b](JAVA_MIGRATION.md#phase-4b--measured-performance-pass). The historical
numbers below remain scoped to their recorded workloads and revisions; no new performance result is claimed by
adding this plan.
## Broader performance pass protocol (planned)
Begin after the Java API/representative extension workloads are stable, alongside consumer migration and before
final Scala removal. A workload manifest must identify the world/seed or reproducible world snapshot, pack and mod
versions, FMP/consumer commits, hardware, exact JVM/flags/heap, view distance and graphics settings, part/tile/trait
counts, and the action sequence or replay command. Restore equivalent world state before each run.
Use the pack's selected modern Java runtime for primary results; check the supported Java 8 artifact separately for
behavior and regressions. Hold the runtime and configuration fixed within every A/B comparison. Never attribute a
JVM, renderer, pack-version or hardware change to the Java port.
Measure fresh-process startup and cold first-use/class generation separately from warmed steady-state play. For each
variant, start with at least five independent runs, alternate baseline/candidate order, use identical warm-up and
measurement windows, and extend runs/repetitions when results are noisy. Keep profiling overhead matched; confirm
end-to-end timing without profiling when overhead is material. Preserve raw reports and recordings under a named
ignored evidence directory rather than overwriting the only baseline.
Report median and variability across runs. Derive p95/p99 tick or frame times from enough samples within each run,
not from five aggregate timings. Include absolute units and relative differences: CPU time, ms/tick, ms/frame,
allocation bytes per operation or second, GC pause time, peak/retained heap, cold latency and network bytes where
relevant. TPS alone can hide an improvement below the 50 ms tick budget. Separate CPU-bound and GPU-bound client
scenes, and do not turn a helper microbenchmark ratio into an FPS/TPS claim.
Use two controlled comparisons: baseline versus optimized FMP with consumer code unchanged; then legacy versus
migrated consumer calls on the same FMP artifact, including adapters and any required snapshots. Where compatible,
also compare with the Scala/reference release on the same runtime and inputs. Compare equivalent results/world state,
packet/NBT fixtures and callback behavior; explicitly exclude scenarios whose behavior cannot be matched.
Each accepted change records: hypothesis and targeted profile site; scenario/manifest and commands; before/after
commits; raw evidence location; absolute/relative measurements with variability; correctness checks; controls,
regressions and tradeoffs; and the acceptance decision. Define practical benefit above noise before editing. A
below-noise result or a bottleneck outside FMP is a valid finding, not a reason to invent more optimization work.
Use the existing harness and local profiling tools first. Extend only the missing representative workloads, and keep
small microbenchmarks as attribution/regression aids alongside actual pack/client measurements. Update this document
with results when that pass runs; performance is not established by completing the API migration table.
## Re-run
The local server EULA must already contain `eula=true`. From PowerShell at the repository root:
```powershell
.\gradlew.bat runFunctionalTestServer "-Pforgemultipart.profileFunctionalTests=true"
```
The property is quoted because PowerShell otherwise splits the dotted Gradle property. Normal
`runFunctionalTestServer` runs remain unchanged. Profile mode overwrites these ignored files:
- `run/server/forgemultipart-profile.txt` — exact timings and per-thread allocation counts;
- `run/server/forgemultipart-baseline.jfr` — JFR CPU, allocation-site, and GC events.
Useful JDK commands after the run:
```powershell
Get-Content run/server/forgemultipart-profile.txt
jfr summary run/server/forgemultipart-baseline.jfr
jfr view --width 220 hot-methods run/server/forgemultipart-baseline.jfr
jfr view thread-allocation run/server/forgemultipart-baseline.jfr
```
Open the `.jfr` in Java Mission Control for flame graphs and allocation-site inspection. The `startEpochMillis` and
`nanos` values in the text file define the exact time window for each phase. Java 8 recordings expose TLAB allocation
events rather than the newer `ObjectAllocationSample`, so `jfr view allocation-by-site` from a recent JDK is not a
valid summary of this recording.
## Workload
The fixture uses Zulu OpenJDK 8, eight parts per tile, 1,000,000 warm-up iterations, then 50,000,000 measured
iterations per phase:
- `updateEntity`: one `TileMultipart.updateEntity()` call, dispatching `update()` to eight ticking parts;
- `operate`: one `TileMultipart.operate(Function1)` call with one reused function and eight bound parts;
- `lightValue`: one `TileMultipart.getLightValue()` call across eight parts;
- `getTile`: one `BlockMultipart.getTile()` lookup returning the same non-empty eight-part tile;
- `redstoneQueries`: one `strongPowerLevel`, one `getConnectionMask`, and one masked `weakPowerLevel` call on a
generated `TRedstoneTile` containing eight `IRedstonePart` implementations.
The checksum consumes all observable work. Allocation bytes come from HotSpot's per-thread allocation counter, not
from sampled JFR events. JFR remains the source for CPU samples and allocation-site ranking.
## Baseline captured 2026-08-27
Environment: Zulu 8.96 / OpenJDK `1.8.0_504-b01`, Windows 11, 16 hardware threads, `-Xms1G -Xmx4G`, JFR `profile`
settings.
| Phase | Elapsed | Operations/s | Allocated bytes | Bytes/operation | CPU samples |
| --- | ---: | ---: | ---: | ---: | ---: |
| `updateEntity` | 2.970 s | 16,835,622 | 9,198,500,864 | 184.0 | 209 |
| `operate` | 3.004 s | 16,646,549 | 9,195,084,824 | 183.9 | 205 |
| `redstoneQueries` | 3.689 s | 13,553,242 | 4,023,003,032 | 80.5 | 239 |
Timing is machine- and JIT-sensitive; compare it only with the same workload and environment. Allocation per operation
is the more stable regression metric.
### CPU and allocation-site findings
- `updateEntity` and `operate` are dominated by `TileMultipart.parts()`, `AbstractCollection.toArray`, Scala list
length/iteration, and Java-conversion wrappers. Their nearly identical 184-byte allocation cost shows that the
traversal snapshot, not the update callback itself, is the first target.
- The current Java `parts()` constructs an `ArrayList` from the published Scala `Seq` on every traversal. The reference
Scala `operate` captured the immutable `Seq` and iterated it directly, so this cost is a port artifact rather than a
compatibility requirement.
- Redstone CPU samples are concentrated in Scala `List.foreach` (118/239), `PartMap.edgeBetween` (46/239), iterator
`foreach` (35/239), and the generated strong-power closure (31/239). Allocation events identify
`scala.runtime.IntRef`, Scala iterators, and generated closures as the major sites.
## Decision
The first Phase 4 implementation targeted `TileMultipart` traversal after focused tests froze its mutation semantics:
iteration observes the captured part order, skips a part whose tile was cleared before its turn, and does not visit a
part added during the callback. The implementation retains the public Scala `Seq` and `operate(Function1)` ABI.
## Traversal result captured 2026-08-27
`operate` now captures `partList` directly. The normal immutable Scala `List` path walks its existing head/tail chain,
which creates no iterator, Java wrapper, array, or copied collection. The published setter still accepts any Scala
`Seq`; unusual implementations use the reference-style iterator fallback rather than being forced into the fast-path
representation.
The retained post-change report is from the same machine, JVM, arguments, warm-up, and 50,000,000-iteration workload:
| Phase | Baseline elapsed | Result elapsed | Baseline B/op | Result B/op | Throughput change |
| --- | ---: | ---: | ---: | ---: | ---: |
| `updateEntity` | 2.970 s | 0.682 s | 184.0 | 0.05 | 4.36x |
| `operate` | 3.004 s | 0.700 s | 183.9 | 0.0 | 4.29x |
| `redstoneQueries` | 3.689 s | 7.286 s | 80.5 | 80.4 | control only |
A repeat produced 0.732 s / 0.687 s for `updateEntity` / `operate`, with the same 0.05 / 0.0 B/op. The result therefore
removes effectively all measured traversal allocation and raises throughput from roughly 16.7 million to 68–73
million calls/s. The post-change JFR hot-method view no longer contains `TileMultipart.parts()`,
`AbstractCollection.toArray`, or the Java-conversion wrappers in these paths.
The unchanged redstone allocation is the useful control. Its timing was consistently slower in both post-change runs,
but its code did not change and it now starts several seconds earlier because the preceding phases finish faster; do
not attribute that timing difference to this traversal change. Re-baseline the redstone unit immediately before its
own implementation comparison.
## Redstone helper-unit comparison captured 2026-08-28
Immediately before converting `IRedstonePart.scala`, the same workload measured `redstoneQueries` at 7.603 s,
6,575,956 iterations/s, 4,022,151,064 allocated bytes, and 80.4 B/iteration. After its six interfaces and
`RedstoneInteractions` were converted together, the retained report measured 3.880 s, 12,884,996 iterations/s,
4,023,003,032 allocated bytes, and 80.5 B/iteration. Both runs produced checksum `3315999992`.
The allocation result is unchanged. The elapsed-time difference is not treated as a port win: earlier unchanged
Scala runs ranged from 3.689 to 7.603 s on this machine. More importantly, the post-port JFR has the same dominant
sites: Scala `List.foreach`, `Iterator.foreach`, `PartMap.edgeBetween`, and
`TRedstoneTile$$anonfun$strongPowerLevel$1`.
That evidence corrects the earlier plan. `IRedstonePart.scala` owned the public interfaces and routing helpers, but the
measured `IntRef`, iterator, and closure allocations are emitted by `scalatraits/TRedstoneTile.scala`. Removing them
requires the Phase 5 `registerJavaTrait` path and must not be smuggled into this otherwise descriptor-identical port.
`MicroRecipe.scala` was the next independent Phase 4 unit and is now Java. Its five recipe forms and precedence are
characterized, and ordinary loops replaced its range/closure scans and exception-backed non-local returns. The focused
server workload does not craft recipes, so no timing claim is made for that structural removal.
The generated-trait checkpoints are complete. `TPartialOcclusionTile` proved the no-field path; `TSlottedTile` proved
field/accessor generation, initialization, copying, lifecycle behavior, and caching. Its ordinary loops remove four
Scala range closures and the exception-backed slot-scan return structurally, but the focused workload has no slotted
placement phase, so no numeric performance claim is made for that port.
## TRedstoneTile result captured 2026-08-28
The port was measured immediately before and after with the same JVM, eight-part generated tile, warm-up, and
50,000,000-iteration workload. Both runs produced checksum `3315999992`.
| Implementation | Elapsed | Operations/s | Allocated bytes | Bytes/operation |
| --- | ---: | ---: | ---: | ---: |
| Scala trait | 7.534 s | 6,636,424 | 4,023,855,000 | 80.5 |
| Java trait | 6.261 s | 7,986,213 | 0 | 0.0 |
The Java trait removes all measured allocation from the three-query iteration and improves throughput by 20.3% in
this paired run. The checksum and all characterization tests are unchanged. Normal immutable Scala `List` part
storage is traversed through its existing head/tail chain; the published `partList` setter still accepts any `Seq`,
so non-`List` implementations retain an iterator fallback.
The existing Java-trait transformer cannot safely rewrite bytecode that directly reads inherited Minecraft fields or
calls inherited `TileMultipart` methods. A package-private `TRedstoneTileAccess` shim keeps coordinate, `partList`, and
virtual `partMap` access outside the transformed class. This changes no public facade or generated-trait member and
required no generator change.
The two focused steady-state allocation targets identified by this workload are now resolved: `TileMultipart.operate`
and generated redstone queries are effectively allocation-free on their normal immutable-list paths. Further
optimization should follow a new representative profile rather than extending this synthetic workload speculatively.
## Multipart read-path baseline captured 2026-08-28
A consumer-audit sanity check identified two Java-port allocations that the original three-phase workload did not
exercise. Focused tests now pin empty/non-empty `BlockMultipart.getTile`, direct ordered `Seq` indexing, and read
queries over the mutable `Seq` implementations accepted by the public setter. The two matching profile phases measured:
| Phase | Elapsed | Operations/s | Allocated bytes | Bytes/operation |
| --- | ---: | ---: | ---: | ---: |
| `lightValue` | 3.170 s | 15,772,691 | 9,196,067,864 | 183.9 |
| `getTile` | 0.271 s | 184,225,439 | 1,200,000,000 | 24.0 |
`lightValue` pays for `TileMultipart.parts()`'s copied `ArrayList`; `getTile` pays for the Java list wrapper returned by
`jPartList()`. Both are absent from the reference Scala implementation, which reads the published `Seq` directly.
Mutation paths still require a snapshot before publishing a replacement immutable `Seq`.
### Read-path result captured 2026-08-28
The paired run used the same JVM, eight-part tiles, warm-up, iteration count, and checksum:
| Phase | Baseline elapsed | Result elapsed | Baseline B/op | Result B/op | Throughput change |
| --- | ---: | ---: | ---: | ---: | ---: |
| `lightValue` | 3.170 s | 0.278 s | 183.9 | 0.0 | 11.42x |
| `getTile` | 0.271 s | 0.094 s | 24.0 | 0.0 | 2.89x |
Internal read paths now traverse or index the published Scala `Seq` directly. The normal immutable-list light query
walks the existing head/tail chain; arbitrary `Seq` implementations retain an iterator fallback. The public
`jPartList()` bridge remains unchanged for downstream ABI compatibility, and only add/remove paths take mutable
snapshots before publishing a replacement immutable `Seq`.