perf(encode): audit the write path and apply the wins that measured

[Fyzu]

Audit of the three encode paths against what fastjson2 and protobuf-java actually make available, plus the changes that measured as wins. docs/encoding-performance.md is the standing record: what was applied, what measured as nothing and why, and a ranked backlog with the reasoning for each item.

Measurement method

run-benchmarks.sh numbers are not comparable across sessions on a shared host — the first baseline run here showed score errors up to 40% of the score at -f 1 -i 3. Everything below is an interleaved A/B: two benchmarks.jar builds from the same reactor, run back to back on the same host at -f 3 -wi 3 -i 5 -r 1 -w 1. Score error was ±2–5% on both sides except where noted.

Throughput (ops/s)

benchmark	before	after	delta
SimpleMessage.compiledUtf16	9,874,885	11,071,259	+12.1%
SimpleMessage.compiledUtf8	11,474,893	13,021,993	+13.5%
SimpleMessage.runtimeUtf16	7,485,001	8,064,932	+7.7%
SimpleMessage.runtimeUtf8	8,870,673	9,099,641	+2.6%
ComplexMessage.buffJsonCompiled	749,489	773,347	+3.2%
ComplexMessage.buffJsonRuntime	646,093	662,785	+2.6%
Wkt.structCompiled	296,651	467,034	+57.4%
Wkt.structRuntime	292,599	481,153	+64.4%
Wkt.timestampCompiled	4,736,791	4,891,055	+3.3%
RepeatedAndMap.*	—	—	flat (within noise)

Allocation (gc.alloc.rate.norm, B/op)

benchmark	before	after	delta
SimpleMessage.compiledUtf16	296	208	−88
SimpleMessage.compiledUtf8	272	184	−88
ComplexMessage.buffJsonCompiled	1,532	1,444	−88
Wkt.struct*	1,305	648	−657
RepeatedAndMap.mapRuntime	8,021	6,727	−1,294

The flat −88 B/op everywhere is the per-call JSONWriter.Context — 30% of SimpleMessage's total. After the change the returned String/byte[] is essentially the only thing allocated per encode.

Changes

Word-packed field names (codegen). fastjson2 exposes a writeName2Raw(long) … writeName16Raw(long, long) family that takes the name already packed into machine words and stores it with one or two Unsafe.putLongs — what fastjson2's own ASM/@JSONCompiled writers use, and the largest structural gap to the POJO ceiling CeilingBenchmark measures. The old writeNameRaw(byte[])/writeNameRaw(char[]) path cost a static array load, a length read, an arraycopy, and an isUTF8() branch per field.

The layout is an undocumented fastjson2 detail and irregular — native-order word reads out of the literal "name":, at offset 0 for every length except 8 and 16, where fastjson2 emits the opening quote itself. New FieldNames derives it and documents the table. JSONWriterUTF16 consumes the same constants (it widens the packed ASCII to chars on the way out), so the encoding branch and the second array disappear rather than moving.

Typed Struct/Value/ListValue. Descriptor.getOneofs() is Collections.unmodifiableList(Arrays.asList(oneofs)) — two allocations on every call — and WellKnownTypes.writeValue called it once per Value written, then scanned for the set oneof field and switched on its String name. Compiled messages now use getFieldsMap()/getKindCase(); DynamicMessage keeps the reflective path with the map-entry descriptors hoisted out of the per-entry loop and the kind oneof cached per Descriptor. Biggest single win in the audit, and it was hiding inside a WKT helper rather than on the main field loop.

Typed WKT wrapper writes in codegen. An Int32Value/StringValue/… field emits jsonWriter.writeInt32(wrap.getValue()) instead of routing through WellKnownTypes.write()'s full-name String switch, descriptor cache probe and getField() boxing.

One JSONWriter.Context per encoder instead of one per encode() call.

Reflection path: hasField before getField. The old order paid a boxed reflective read for every absent optional field and discarded it.

Map key/value descriptors resolved at schema-build time. FieldWriter.writeMap was calling findFieldByName("key") and findFieldByName("value") on every map field write.

Repeated primitives / strings. Numeric and bool lists narrow to Internal.IntList/LongList/DoubleList/FloatList/BooleanList and read primitives; repeated strings go through writeString(List<String>) in one call.

Two results worth calling out

One idea measured worse and was reverted. Routing the runtime paths through the packed names needs a switch on the name length — an indirect branch in the hottest code, keyed on a per-field instance value. On ComplexMessage (15 fields, 9 distinct name lengths) that cost −10.8% on the typed path. Reverting to the pre-encoded arrays turned that into +2.6%, and moved SimpleMessage.runtimeUtf16 from −0.4% to +7.7%. The reasoning is recorded in FieldName's javadoc so it does not get "fixed" again.

One measured as exactly nothing. IntArrayList.get(i) returns Integer.valueOf(...), which looks like a per-element allocation — but the change measured 0 B/op and 0% on a field holding 50–200 rng.nextInt() values (essentially no cache hits). HotSpot already scalar-replaces the boxes once the loop inlines; if boxing were really allocating there it alone would have been ~2,000 of the 5,385 B/op measured. Kept only as insurance for the C1 and interpreted tiers, and documented as not-a-win so nobody re-measures it hoping.

Correctness fix found on the way

[json_name = "…"] accepts any string, and two things were broken independently of performance:

• buildNameWithColonUtf8 did (byte) name.charAt(i), truncating non-ASCII into corrupt UTF-8 and emitting a raw "/\ straight into the JSON string;
• EncoderGenerator interpolated the name into a Java string literal unescaped, so a json_name containing a quote or newline generated source that does not compile.

FieldNames.isRawWritable now gates the raw arrays; anything else goes through JSONWriter.writeName(String) + writeColon() so fastjson2 escapes and transcodes it, and all emitted literals go through FieldNames.javaStringLiteral.

Testing

• 545 tests pass, including the existing cross-path fuzz test that asserts codegen == typed == reflection == JsonFormat byte-for-byte.
• New FieldNamesTest (54 cases) pins the fastjson2 packing layout for every length 2–16 on both encodings, plus the escaping fallback. A fastjson2 upgrade that moves the layout now fails there instead of silently corrupting every field name in every message.
• allocation-check.sh passes with budgets tightened to the new baselines (SimpleMessage 380→290, ComplexMessage 2300→2000, etc.).
• The official protobuf conformance runner binary is not available in this environment, so that suite was not run; it is report-only in CI.

Not included

docs/encoding-performance.md Part 2 ranks what's left. Top three: devirtualizing JSONWriter via per-encoding generated writeFields bodies (the remaining big structural item, but 2× generated bytecode — must be measured, not assumed); pre-sizing the output buffer through the public-but-unused ensureCapacity(int); and fusing constant name+value pairs for bools and enums. It also records the ideas that look promising and aren't — e.g. writeName(int) writes an unquoted number with no colon, so it cannot serve proto3 map keys.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Rjh5q2cHevWc6DPzyoACQp

---

Generated by Claude Code