Fory Performance Optimization

Fory Performance Optimization

Mission

Deliver measurable performance improvements in Apache Fory without protocol drift, correctness regressions, benchmark-shape tricks, or accidental API rollback.

Operating Principles

• Start from data, not intuition.
• Profile before changing hot code.
• Change one bottleneck at a time.
• Benchmark sequentially on the same machine state (one benchmark process at a time).
• Compare old/new benchmark results case-by-case in adjacent pairs: run one case on apache/main, then immediately run that same case on the current branch before moving to the next case.
• Under high or variable host load, run multiple short adjacent baseline/current pairs. Keep each process short and alternate sides instead of lengthening one run or batching all baseline runs.
• Keep only measured wins or explicitly requested architecture cleanups.
• Revert speculative changes that do not pay off.
• During each optimization round, benchmark only cases directly affected by the change. Defer unrelated controls, full-suite sanity benchmarks, and full comparison matrices to final verification of the whole optimization task unless the user explicitly requests them earlier.
• Align with reference runtimes (usually C++ first, then Rust/Java) when behavior and ownership models differ.

Enforce Hard Constraints

• Preserve wire protocol unless explicitly requested.
• Preserve cross-language semantics and xlang compatibility.
• Never run two benchmarks at the same time on one host; run exactly one benchmark command at a time.
• Do not optimize by changing benchmark payload definitions, field encodings, or benchmark methodology.
• Do not add payload-identity or repeated-input caches that depend on benchmark shape.
• Do not restore removed APIs/legacy wrappers when the user forbids it.
• Do not preserve legacy/dead code or stale docs in optimization rounds; remove them when touched.
• Keep API surface minimal: do not add new API unless required by protocol/correctness or explicitly requested.
• Never add public hacky API for performance shortcuts; keep optimization helpers internal/private and conceptually clean.
• Do not hide regressions behind unsafe compiler flags or benchmark-only code paths.
• Keep optimization surfaces nested-safe; avoid root-only shortcuts unless they are architecturally valid and requested.
• Do not add reader-side validation solely to produce an earlier or more precise malformed-input error. A necessary crash, panic, undefined-behavior, out-of-bounds, resource-amplification, no-progress, state-pollution, type, or policy guard must keep its hot success path to a primitive branch and move exception allocation and message formatting into a cold no-inline helper when supported. If an existing bounds-safe downstream operation already raises a controlled root error, do not duplicate its validation on the hot path.

Execute Workflow

1. Read context and constraints.

• Read tasks/perf_optimization_rounds.md and tasks/lessons.md.
• Read the relevant spec in docs/specification/ for any path that may affect wire behavior.
• Record explicit user constraints (forbidden APIs, naming, architecture, protocol rules).

2. Define target and baseline.

• Identify one primary KPI (for example Struct Serialize ns/op or ops/sec).
• Benchmark current HEAD.
• If a reference commit is provided, persist its built benchmark artifact and commit identity. Treat stored numbers as historical context, not a substitute for an adjacent baseline run in each comparison pair.

3. Profile the hotspot.

• Capture a flamegraph or sampled stacks on the exact benchmark command.
• Quantify top costs by bucket (runtime bookkeeping, dispatch, allocation/copy, map/cache operations, buffer growth, metadata parse/validation).
• Tie each bucket to concrete file/line ownership before proposing changes.

4. Form one round hypothesis.

• State one bottleneck and one expected effect.
• Prefer structural fixes over micro-tweaks.
• If another runtime already solved the same bottleneck, port its design shape first.

5. Implement minimal change.

• Touch the smallest surface that can validate the hypothesis.
• Keep invariants explicit: protocol bytes, ownership, cache lifetime, reference semantics, nullability, schema-compatible behavior.

6. Verify correctness.

• Run language-local build/test/lint for the touched implementation.
• Run cross-language checks when runtime/type/protocol behavior can affect xlang.
• Confirm serialized sizes and compatibility expectations where applicable.
• For Java performance work, defer local GraalVM image builds and executions to the final verification of the whole optimization task. Do not repeat them in individual rounds unless the user explicitly requests an earlier run.

7. Benchmark and compare.