Skip to content

perf: keep default encode path baseline-identical with Marshaler support - #1090

Closed
pelletier wants to merge 2 commits into
v2from
raw-marshaler-default-path-perf
Closed

pelletier wants to merge 2 commits into
v2from
raw-marshaler-default-path-perf

Conversation

@pelletier

@pelletier pelletier commented Jul 3, 2026 •

Copy link
Copy Markdown
Owner

What

Follow-up to #1084 (Encoder.EnableMarshalerInterface). Benchmarking that feature against v2 on linux/amd64 (idle host, pinned cores, interleaved rounds, n=12, benchstat) showed statistically significant sec/op regressions on the default (interface-disabled) Marshal path — up to +10% on micro-benchmarks — with allocations unchanged.

Root cause

Bisecting the #1084 diff piece by piece isolated the dominant cost: widening the per-type typeEncProps cache struct from 2 to 3 bytes (the added marshaler uint8 classification). Its cached p.(typeEncProps) assertion and by-value return run 2–3× per encoded value (via isValueKind and the TextMarshaler switch), and the extra field changes the copy size and register-ABI shape of every lookup. That lone change — with zero encoder-code modifications — reproduced the regression (geomean +3.8% on the Marshal micro set); padding the struct to 4 bytes only halved it.

Changes

  • typeEncProps / encPropsForType restored to their exact baseline form; the unstable.Marshaler classification lives in its own sync.Map (typeMarshalerCache / marshalerPropsForType), consulted only on EnableMarshalerInterface paths.
  • encodeTable, encodeKeyValue, encodeArrayTable restored to their exact baseline source; the Marshaler-aware table passes live in encodeTableWithMarshalers / encodeArrayTableWithMarshalers, selected by one branch per table instead of one per entry. Marshaler values on a key = line flow through appendValue's gated guard, which returns without rejoining the fall-through path and re-classifies the fetched bytes (keeping the emit-time guard against non-deterministic marshalers).
  • All Marshaler-interface machinery moves to a new marshaler_raw.go, out from between the default path's hot functions.

After this change the interface-off encoder differs from the pre-#1084 source only by four single-branch dispatches; typeEncProps, encPropsForType and the hot encoder functions are byte-identical to baseline. No behavior change: the #1084 test suite passes unmodified.

Measurements

Full benchstat posted as a collapsed comment below (and on #1084). Summary: allocs/op identical across the whole ./benchmark suite; ms-scale dataset benchmarks unchanged; remaining µs-scale sec/op deltas are within the measurement host's address-alignment noise floor (demonstrated with dead-code A/A controls and -ldflags=-randlayout runs).

🤖 Generated with Claude Code

@pelletier
pelletier force-pushed the raw-marshaler-default-path-perf branch 3 times, most recently from cbb3f96 to c0a09d4 Compare July 3, 2026 04:15
@pelletier

Copy link
Copy Markdown
Owner Author

Benchstat: v2 pre-#1084 (79f82e3) vs this PR (c0a09d4 = #1084 + this fix)

Setup: linux/amd64 (AMD Ryzen Threadripper PRO 3975WX), go1.26.4, taskset -c 2-9, 6 interleaved rounds of -count=2 per side (n=12), full ./benchmark suite, benchstat v2 CIs.

Summary

  • allocs/op and B/op: identical across the entire suite (all ~, most "all samples equal").
  • ms-scale dataset benchmarks: unchanged (UnmarshalDataset/* all ~; canada even −3.6%).
  • µs-scale Marshal micro-benchmarks: a residual +2–6% remains (Marshal/ReferenceFile/map +4.7%, HugoFrontMatter +5.8%, ViperWrite +5.3%); full-suite geomean +1.4% (default layout), +0.9% on the micro set under -ldflags=-randlayout (function-layout randomization, 6 seeds).
  • Without this PR the picture is materially worse: the merged Add RawMessage marshal support to unstable #1084 alone measured up to +10% on the same set; the dominant term (the typeEncProps widening, +3.8% geomean in isolation) is what this PR removes.
Full ./benchmark suite, default layout (sec/op, B/s, B/op, allocs/op)
goos: linux
goarch: amd64
pkg: github.com/pelletier/go-toml/v2/benchmark
cpu: AMD Ryzen Threadripper PRO 3975WX 32-Cores     
                                  │ /tmp/pub2-old.txt │         /tmp/pub2-new.txt          │
                                  │      sec/op       │   sec/op     vs base               │
UnmarshalDataset/config-8                10.037m ± 2%   9.990m ± 2%       ~ (p=0.755 n=12)
UnmarshalDataset/canada-8                 26.48m ± 3%   25.53m ± 4%  -3.58% (p=0.024 n=12)
UnmarshalDataset/citm_catalog-8           14.59m ± 2%   14.55m ± 1%       ~ (p=0.843 n=12)
UnmarshalDataset/twitter-8                3.534m ± 2%   3.636m ± 4%       ~ (p=0.068 n=12)
UnmarshalDataset/code-8                   32.48m ± 1%   32.60m ± 3%       ~ (p=0.671 n=12)
UnmarshalDataset/example-8                67.40µ ± 3%   67.91µ ± 3%       ~ (p=0.291 n=12)
Unmarshal/SimpleDocument/struct-8         345.0n ± 3%   357.5n ± 3%  +3.62% (p=0.002 n=12)
Unmarshal/SimpleDocument/map-8            397.1n ± 2%   401.0n ± 4%       ~ (p=0.089 n=12)
Unmarshal/ReferenceFile/struct-8          37.37µ ± 2%   37.84µ ± 3%       ~ (p=0.319 n=12)
Unmarshal/ReferenceFile/map-8             30.20µ ± 2%   30.87µ ± 4%       ~ (p=0.561 n=12)
Unmarshal/HugoFrontMatter-8               5.346µ ± 2%   5.399µ ± 4%       ~ (p=0.745 n=12)
Marshal/SimpleDocument/struct-8           369.8n ± 3%   385.9n ± 3%  +4.37% (p=0.032 n=12)
Marshal/SimpleDocument/map-8              608.1n ± 4%   615.0n ± 2%       ~ (p=0.386 n=12)
Marshal/ReferenceFile/struct-8            20.90µ ± 3%   21.38µ ± 3%  +2.28% (p=0.028 n=12)
Marshal/ReferenceFile/map-8               39.74µ ± 6%   41.61µ ± 2%  +4.70% (p=0.010 n=12)
Marshal/HugoFrontMatter-8                 7.953µ ± 5%   8.416µ ± 2%  +5.82% (p=0.000 n=12)
RealWorldContainerdConfig-8               35.36µ ± 1%   36.10µ ± 3%       ~ (p=0.068 n=12)
RealWorldViperRead-8                      7.784µ ± 3%   7.764µ ± 5%       ~ (p=0.514 n=12)
RealWorldViperWrite-8                     13.07µ ± 4%   13.76µ ± 3%  +5.27% (p=0.010 n=12)
RealWorldHugoFrontMatterBatch-8           88.29µ ± 4%   87.60µ ± 4%       ~ (p=0.143 n=12)
RealWorldGitleaksRules-8                  55.18µ ± 2%   55.56µ ± 3%       ~ (p=0.160 n=12)
RealWorldPyproject-8                      14.11µ ± 2%   13.89µ ± 2%       ~ (p=0.198 n=12)
RealWorldGolangciStrict-8                 10.37µ ± 3%   10.39µ ± 2%       ~ (p=0.713 n=12)
geomean                                   44.78µ        45.41µ       +1.40%

                                  │ /tmp/pub2-old.txt │          /tmp/pub2-new.txt           │
                                  │        B/s        │      B/s       vs base               │
UnmarshalDataset/config-8                99.64Mi ± 3%   100.12Mi ± 2%       ~ (p=0.744 n=12)
UnmarshalDataset/canada-8                79.28Mi ± 3%    82.22Mi ± 4%  +3.71% (p=0.024 n=12)
UnmarshalDataset/citm_catalog-8          36.48Mi ± 2%    36.57Mi ± 1%       ~ (p=0.832 n=12)
UnmarshalDataset/twitter-8               119.2Mi ± 2%    115.9Mi ± 5%       ~ (p=0.068 n=12)
UnmarshalDataset/code-8                  78.81Mi ± 1%    78.52Mi ± 3%       ~ (p=0.671 n=12)
UnmarshalDataset/example-8               114.6Mi ± 3%    113.7Mi ± 3%       ~ (p=0.291 n=12)
Unmarshal/SimpleDocument/struct-8        30.41Mi ± 3%    29.34Mi ± 3%  -3.50% (p=0.002 n=12)
Unmarshal/SimpleDocument/map-8           26.42Mi ± 2%    26.16Mi ± 4%       ~ (p=0.089 n=12)
Unmarshal/ReferenceFile/struct-8         133.8Mi ± 2%    132.1Mi ± 3%       ~ (p=0.319 n=12)
Unmarshal/ReferenceFile/map-8            165.5Mi ± 2%    161.9Mi ± 4%       ~ (p=0.561 n=12)
Unmarshal/HugoFrontMatter-8              97.41Mi ± 2%    96.45Mi ± 5%       ~ (p=0.755 n=12)
Marshal/SimpleDocument/struct-8          30.94Mi ± 2%    29.66Mi ± 3%  -4.15% (p=0.032 n=12)
Marshal/SimpleDocument/map-8             18.82Mi ± 4%    18.61Mi ± 2%       ~ (p=0.386 n=12)
Marshal/ReferenceFile/struct-8           93.85Mi ± 3%    91.76Mi ± 3%  -2.23% (p=0.030 n=12)
Marshal/ReferenceFile/map-8              48.11Mi ± 5%    45.95Mi ± 2%  -4.49% (p=0.010 n=12)
Marshal/HugoFrontMatter-8                62.72Mi ± 4%    59.26Mi ± 2%  -5.51% (p=0.000 n=12)
RealWorldContainerdConfig-8              73.39Mi ± 1%    71.88Mi ± 3%       ~ (p=0.068 n=12)
RealWorldViperRead-8                     79.40Mi ± 3%    79.60Mi ± 5%       ~ (p=0.514 n=12)
RealWorldViperWrite-8                    47.22Mi ± 4%    44.86Mi ± 3%  -5.00% (p=0.010 n=12)
RealWorldHugoFrontMatterBatch-8          85.33Mi ± 4%    86.01Mi ± 4%       ~ (p=0.143 n=12)
RealWorldGitleaksRules-8                 59.50Mi ± 2%    59.09Mi ± 3%       ~ (p=0.160 n=12)
RealWorldPyproject-8                     78.01Mi ± 2%    79.24Mi ± 2%       ~ (p=0.198 n=12)
RealWorldGolangciStrict-8                64.36Mi ± 3%    64.23Mi ± 2%       ~ (p=0.713 n=12)
geomean                                  65.63Mi         64.73Mi       -1.38%

                                  │ /tmp/pub2-old.txt │           /tmp/pub2-new.txt           │
                                  │       B/op        │     B/op      vs base                 │
UnmarshalDataset/config-8               3.560Mi ±  0%   3.560Mi ± 0%       ~ (p=0.580 n=12)
UnmarshalDataset/canada-8               5.531Mi ± 15%   5.531Mi ± 1%       ~ (p=0.988 n=12)
UnmarshalDataset/citm_catalog-8         4.319Mi ±  5%   4.330Mi ± 5%       ~ (p=0.620 n=12)
UnmarshalDataset/twitter-8              1.255Mi ±  0%   1.255Mi ± 0%       ~ (p=0.178 n=12)
UnmarshalDataset/code-8                 6.183Mi ±  0%   6.183Mi ± 0%       ~ (p=0.075 n=12)
UnmarshalDataset/example-8              28.96Ki ±  0%   28.96Ki ± 0%       ~ (p=0.182 n=12)
Unmarshal/SimpleDocument/struct-8         21.00 ±  0%     21.00 ± 0%       ~ (p=1.000 n=12) ¹
Unmarshal/SimpleDocument/map-8            365.0 ±  0%     365.0 ± 0%       ~ (p=1.000 n=12) ¹
Unmarshal/ReferenceFile/struct-8        3.314Ki ±  0%   3.315Ki ± 0%       ~ (p=0.408 n=12)
Unmarshal/ReferenceFile/map-8           14.14Ki ±  0%   14.14Ki ± 0%       ~ (p=0.651 n=12)
Unmarshal/HugoFrontMatter-8             3.017Ki ±  0%   3.017Ki ± 0%       ~ (p=1.000 n=12)
Marshal/SimpleDocument/struct-8           176.0 ±  0%     176.0 ± 0%       ~ (p=1.000 n=12) ¹
Marshal/SimpleDocument/map-8              176.0 ±  0%     176.0 ± 0%       ~ (p=1.000 n=12) ¹
Marshal/ReferenceFile/struct-8          3.033Ki ±  0%   3.033Ki ± 0%       ~ (p=0.671 n=12)
Marshal/ReferenceFile/map-8             3.470Ki ±  0%   3.470Ki ± 0%       ~ (p=0.640 n=12)
Marshal/HugoFrontMatter-8                 944.0 ±  0%     944.0 ± 0%       ~ (p=1.000 n=12) ¹
RealWorldContainerdConfig-8             8.614Ki ±  0%   8.614Ki ± 0%       ~ (p=0.788 n=12)
RealWorldViperRead-8                    3.635Ki ±  0%   3.634Ki ± 0%  -0.03% (p=0.027 n=12)
RealWorldViperWrite-8                     560.0 ±  0%     560.0 ± 0%       ~ (p=1.000 n=12) ¹
RealWorldHugoFrontMatterBatch-8         37.84Ki ±  0%   37.84Ki ± 0%       ~ (p=0.128 n=12)
RealWorldGitleaksRules-8                11.48Ki ±  0%   11.48Ki ± 0%       ~ (p=1.000 n=12)
RealWorldPyproject-8                    7.762Ki ±  0%   7.762Ki ± 0%       ~ (p=0.304 n=12)
RealWorldGolangciStrict-8               2.463Ki ±  0%   2.463Ki ± 0%       ~ (p=0.494 n=12)
geomean                                 11.01Ki         11.01Ki       +0.01%
¹ all samples are equal

                                  │ /tmp/pub2-old.txt │          /tmp/pub2-new.txt           │
                                  │     allocs/op     │  allocs/op   vs base                 │
UnmarshalDataset/config-8                 70.19k ± 0%   70.19k ± 0%       ~ (p=1.000 n=12) ¹
UnmarshalDataset/canada-8                 223.2k ± 0%   223.2k ± 0%       ~ (p=0.590 n=12)
UnmarshalDataset/citm_catalog-8           49.98k ± 0%   49.98k ± 0%       ~ (p=0.739 n=12)
UnmarshalDataset/twitter-8                15.78k ± 0%   15.78k ± 0%       ~ (p=1.000 n=12)
UnmarshalDataset/code-8                   129.5k ± 0%   129.5k ± 0%       ~ (p=1.000 n=12) ¹
UnmarshalDataset/example-8                 399.0 ± 0%    399.0 ± 0%       ~ (p=1.000 n=12) ¹
Unmarshal/SimpleDocument/struct-8          2.000 ± 0%    2.000 ± 0%       ~ (p=1.000 n=12) ¹
Unmarshal/SimpleDocument/map-8             5.000 ± 0%    5.000 ± 0%       ~ (p=1.000 n=12) ¹
Unmarshal/ReferenceFile/struct-8           83.00 ± 0%    83.00 ± 0%       ~ (p=1.000 n=12) ¹
Unmarshal/ReferenceFile/map-8              194.0 ± 0%    194.0 ± 0%       ~ (p=1.000 n=12) ¹
Unmarshal/HugoFrontMatter-8                54.00 ± 0%    54.00 ± 0%       ~ (p=1.000 n=12) ¹
Marshal/SimpleDocument/struct-8            4.000 ± 0%    4.000 ± 0%       ~ (p=1.000 n=12) ¹
Marshal/SimpleDocument/map-8               4.000 ± 0%    4.000 ± 0%       ~ (p=1.000 n=12) ¹
Marshal/ReferenceFile/struct-8             4.000 ± 0%    4.000 ± 0%       ~ (p=1.000 n=12) ¹
Marshal/ReferenceFile/map-8                91.00 ± 0%    91.00 ± 0%       ~ (p=1.000 n=12) ¹
Marshal/HugoFrontMatter-8                  20.00 ± 0%    20.00 ± 0%       ~ (p=1.000 n=12) ¹
RealWorldContainerdConfig-8                144.0 ± 0%    144.0 ± 0%       ~ (p=1.000 n=12) ¹
RealWorldViperRead-8                       65.00 ± 0%    65.00 ± 0%       ~ (p=1.000 n=12) ¹
RealWorldViperWrite-8                      33.00 ± 0%    33.00 ± 0%       ~ (p=1.000 n=12) ¹
RealWorldHugoFrontMatterBatch-8            820.0 ± 0%    820.0 ± 0%       ~ (p=1.000 n=12) ¹
RealWorldGitleaksRules-8                   259.0 ± 0%    259.0 ± 0%       ~ (p=1.000 n=12) ¹
RealWorldPyproject-8                       142.0 ± 0%    142.0 ± 0%       ~ (p=1.000 n=12) ¹
RealWorldGolangciStrict-8                  48.00 ± 0%    48.00 ± 0%       ~ (p=1.000 n=12) ¹
geomean                                    211.1         211.1       +0.00%
¹ all samples are equal
Micro set under -ldflags=-randlayout (6 seeds × count=2 per side)
goos: linux
goarch: amd64
pkg: github.com/pelletier/go-toml/v2/benchmark
cpu: AMD Ryzen Threadripper PRO 3975WX 32-Cores     
                                  │ /tmp/pub-old-rl.txt │        /tmp/pub-new-rl.txt         │
                                  │       sec/op        │   sec/op     vs base               │
Unmarshal/SimpleDocument/struct-8           379.4n ± 2%   382.2n ± 3%       ~ (p=0.156 n=12)
Unmarshal/SimpleDocument/map-8              441.3n ± 4%   433.3n ± 3%       ~ (p=0.062 n=12)
Unmarshal/ReferenceFile/struct-8            39.52µ ± 1%   39.89µ ± 1%       ~ (p=0.101 n=12)
Unmarshal/ReferenceFile/map-8               32.03µ ± 2%   32.56µ ± 4%       ~ (p=0.319 n=12)
Unmarshal/HugoFrontMatter-8                 5.552µ ± 2%   5.451µ ± 3%       ~ (p=0.291 n=12)
Marshal/SimpleDocument/struct-8             418.0n ± 2%   420.4n ± 2%       ~ (p=0.671 n=12)
Marshal/SimpleDocument/map-8                668.3n ± 2%   664.7n ± 4%       ~ (p=0.945 n=12)
Marshal/ReferenceFile/struct-8              22.75µ ± 2%   22.67µ ± 2%       ~ (p=0.932 n=12)
Marshal/ReferenceFile/map-8                 43.23µ ± 1%   44.15µ ± 4%  +2.15% (p=0.000 n=12)
Marshal/HugoFrontMatter-8                   8.686µ ± 2%   9.095µ ± 4%  +4.71% (p=0.014 n=12)
RealWorldViperWrite-8                       14.36µ ± 1%   14.86µ ± 3%  +3.54% (p=0.001 n=12)
geomean                                     4.913µ        4.956µ       +0.87%

                                  │ /tmp/pub-old-rl.txt │         /tmp/pub-new-rl.txt         │
                                  │         B/s         │     B/s       vs base               │
Unmarshal/SimpleDocument/struct-8          27.65Mi ± 2%   27.45Mi ± 3%       ~ (p=0.160 n=12)
Unmarshal/SimpleDocument/map-8             23.78Mi ± 4%   24.21Mi ± 3%       ~ (p=0.062 n=12)
Unmarshal/ReferenceFile/struct-8           126.5Mi ± 1%   125.3Mi ± 1%       ~ (p=0.101 n=12)
Unmarshal/ReferenceFile/map-8              156.0Mi ± 2%   153.5Mi ± 4%       ~ (p=0.319 n=12)
Unmarshal/HugoFrontMatter-8                93.80Mi ± 2%   95.53Mi ± 2%       ~ (p=0.291 n=12)
Marshal/SimpleDocument/struct-8            27.38Mi ± 2%   27.22Mi ± 2%       ~ (p=0.671 n=12)
Marshal/SimpleDocument/map-8               17.12Mi ± 2%   17.22Mi ± 4%       ~ (p=0.966 n=12)
Marshal/ReferenceFile/struct-8             86.23Mi ± 2%   86.54Mi ± 2%       ~ (p=0.900 n=12)
Marshal/ReferenceFile/map-8                44.23Mi ± 1%   43.31Mi ± 4%  -2.09% (p=0.000 n=12)
Marshal/HugoFrontMatter-8                  57.43Mi ± 2%   54.85Mi ± 4%  -4.49% (p=0.014 n=12)
RealWorldViperWrite-8                      42.98Mi ± 1%   41.51Mi ± 3%  -3.42% (p=0.001 n=12)
geomean                                    50.44Mi        50.00Mi       -0.86%

                                  │ /tmp/pub-old-rl.txt │          /tmp/pub-new-rl.txt          │
                                  │        B/op         │     B/op      vs base                 │
Unmarshal/SimpleDocument/struct-8            21.00 ± 0%     21.00 ± 0%       ~ (p=1.000 n=12) ¹
Unmarshal/SimpleDocument/map-8               365.0 ± 0%     365.0 ± 0%       ~ (p=1.000 n=12) ¹
Unmarshal/ReferenceFile/struct-8           3.314Ki ± 0%   3.314Ki ± 0%       ~ (p=0.967 n=12)
Unmarshal/ReferenceFile/map-8              14.14Ki ± 0%   14.14Ki ± 0%       ~ (p=0.653 n=12)
Unmarshal/HugoFrontMatter-8                3.017Ki ± 0%   3.017Ki ± 0%       ~ (p=1.000 n=12)
Marshal/SimpleDocument/struct-8              176.0 ± 0%     176.0 ± 0%       ~ (p=1.000 n=12) ¹
Marshal/SimpleDocument/map-8                 176.0 ± 0%     176.0 ± 0%       ~ (p=1.000 n=12) ¹
Marshal/ReferenceFile/struct-8             3.033Ki ± 0%   3.033Ki ± 0%       ~ (p=0.400 n=12)
Marshal/ReferenceFile/map-8                3.470Ki ± 0%   3.471Ki ± 0%       ~ (p=0.220 n=12)
Marshal/HugoFrontMatter-8                    944.0 ± 0%     944.0 ± 0%       ~ (p=1.000 n=12) ¹
RealWorldViperWrite-8                        560.0 ± 0%     560.0 ± 0%       ~ (p=1.000 n=12) ¹
geomean                                      867.8          867.8       +0.00%
¹ all samples are equal

                                  │ /tmp/pub-old-rl.txt │         /tmp/pub-new-rl.txt         │
                                  │      allocs/op      │ allocs/op   vs base                 │
Unmarshal/SimpleDocument/struct-8            2.000 ± 0%   2.000 ± 0%       ~ (p=1.000 n=12) ¹
Unmarshal/SimpleDocument/map-8               5.000 ± 0%   5.000 ± 0%       ~ (p=1.000 n=12) ¹
Unmarshal/ReferenceFile/struct-8             83.00 ± 0%   83.00 ± 0%       ~ (p=1.000 n=12) ¹
Unmarshal/ReferenceFile/map-8                194.0 ± 0%   194.0 ± 0%       ~ (p=1.000 n=12) ¹
Unmarshal/HugoFrontMatter-8                  54.00 ± 0%   54.00 ± 0%       ~ (p=1.000 n=12) ¹
Marshal/SimpleDocument/struct-8              4.000 ± 0%   4.000 ± 0%       ~ (p=1.000 n=12) ¹
Marshal/SimpleDocument/map-8                 4.000 ± 0%   4.000 ± 0%       ~ (p=1.000 n=12) ¹
Marshal/ReferenceFile/struct-8               4.000 ± 0%   4.000 ± 0%       ~ (p=1.000 n=12) ¹
Marshal/ReferenceFile/map-8                  91.00 ± 0%   91.00 ± 0%       ~ (p=1.000 n=12) ¹
Marshal/HugoFrontMatter-8                    20.00 ± 0%   20.00 ± 0%       ~ (p=1.000 n=12) ¹
RealWorldViperWrite-8                        33.00 ± 0%   33.00 ± 0%       ~ (p=1.000 n=12) ¹
geomean                                      16.96        16.96       +0.00%
¹ all samples are equal
Methodology and attribution ledger

The regression was invisible to allocation counts and to low-power benchstat runs on a busy host (~ with ±5–8% CIs swallows a +5% delta). Protocol used here: idle 64-thread box, pinned cores, interleaved base/candidate rounds so thermal/scheduler drift cancels, n=12.

Attribution was done by applying the #1084 diff piece by piece to the pre-#1084 base and A/B-ing each isolate (Marshal micro set geomean):

isolate geomean verdict
typeEncProps widened 2→3 bytes (nothing else) +3.8% root cause; its cached p.(typeEncProps) assertion + by-value return run 2–3× per encoded value; padding to 4 bytes only halved it → fixed here via a dedicated sync.Map
encoderState growth (112→216 B embedded parser) + per-op stores +0.35% negligible
appendValue gated guard (with vs without) ≈ +0.2% negligible
dead-code A/A controls (300 lines linker-kept, prepended or appended) ~ (+0.3%) code presence / address shifts alone don't move these benchmarks
remainder (dispatches + cold code + unstable pkg changes) ~ +2% resists further decomposition: no inlining diffs (-gcflags=-m identical), no alloc diffs, pprof -diff_base smears over runtime leaves; pieces measure non-additively at this scale

🤖 Generated with Claude Code

Benchmarking the Marshaler-interface commit (#1084) against v2 on
linux/amd64 (interleaved rounds, n=12, benchstat) showed statistically
significant sec/op regressions on the default (interface-disabled)
Marshal path — up to +10% on micro-benchmarks — with allocations
unchanged. Bisecting the diff piece by piece isolated the dominant
cause: widening the per-type typeEncProps cache struct from 2 to 3
bytes. Its cached p.(typeEncProps) assertion and by-value return run
two to three times per encoded value, and the extra field changes the
copy size and register shape of every lookup; that lone change
reproduced the regression with zero encoder-code modifications.

- typeEncProps and encPropsForType are restored to their exact baseline
  form. The unstable.Marshaler classification lives in its own
  sync.Map (typeMarshalerCache/marshalerPropsForType), consulted only
  on EnableMarshalerInterface paths.
- encodeTable, encodeKeyValue and encodeArrayTable are restored to
  their exact baseline source. The Marshaler-aware variants of the
  table passes live in encodeTableWithMarshalers and
  encodeArrayTableWithMarshalers, selected by one branch per table
  instead of one per entry. Marshaler values on a `key =` line flow
  through appendValue's gated guard, which returns without rejoining
  the fall-through path and re-classifies the fetched bytes (keeping
  the emit-time guard), so appendMarshalerInlineValue is gone.
- All Marshaler-interface machinery moves to a new marshaler_raw.go so
  the feature's cold code does not sit between the default path's hot
  functions.

After this change the interface-off encoder differs from baseline only
by four single-branch dispatches; typeEncProps, encPropsForType and the
hot encoder functions are byte-identical to the pre-#1084 source.
allocs/op are identical across the whole ./benchmark suite. Remaining
µs-scale sec/op deltas are within this host's address-alignment noise
floor, demonstrated by dead-code A/A controls and -randlayout runs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@pelletier
pelletier force-pushed the raw-marshaler-default-path-perf branch from c0a09d4 to 63016c7 Compare July 11, 2026 17:08
…unctions

Splitting the EnableMarshalerInterface passes out of the default encode
functions duplicated their non-Marshaler branches, which no existing test
exercised with the interface enabled, failing the coverage gate. Cover them:
plain (and failing) array-of-tables elements, emit-time MarshalTOML failure
inside an array of tables, nested classification errors (with and without
SetOmitEmptySuperTables), a bad map key under a sub-table, and a
non-deterministic Marshaler that turns in empty content at emit time.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@pelletier

Copy link
Copy Markdown
Owner Author

Rebased onto the current v2 tip (now includes #1091, #1092, #1094) and re-validated.

Conflict resolution (#1091, SetOmitEmptySuperTables)

#1091 restructured encodeTable into collectEntries + encodeTableEntries and made its omit-empty-super-tables second pass consult the Marshaler shapes. The resolution keeps this PR's invariant — the interface-off path never executes a Marshaler branch — by carrying the split through #1091's additions:

Coverage

Splitting the Marshaler-aware passes out of the hot functions duplicated their non-Marshaler branches, which no test exercised with the interface enabled — the coverage gate flagged it (97.6% → 97.5%). Added tests for the duplicated branches (plain and failing array-of-tables elements, emit-time MarshalTOML failure in an array of tables, nested classification errors with and without omitted super-tables, bad map key under a sub-table, empty content at emit time). Gate now passes with margin: v2 97.6% → HEAD 97.7%.

Post-rebase measurements

Same setup as the original report (interleaved rounds, benchstat, n=12 → n=10 here). B/op and allocs/op are bit-identical across the whole suite on both platforms. sec/op:

  • linux/amd64: geomean −0.84%; every significant delta is an improvement except Marshal/SimpleDocument/map (+3.74%). That benchmark is 590 ns, its struct sibling moved −1.90% in the same run, and the delta does not reproduce on arm64 (, p=0.45) — consistent with the address-alignment noise documented in the original description (A/A + -randlayout controls), not with a systematic cost, since both variants run the identical interface-off table passes.
  • darwin/arm64: geomean −0.23%, no significant regressions.
benchstat sec/op tables

linux/amd64 (GCP t2d spot, AMD EPYC 7B13, go1.26.4, 5 interleaved rounds × count=2, n=10)

                              │           sec/op           │              sec/op               vs base               │
Marshal/SimpleDocument/struct                  394.5n ± 1%                        387.0n ± 1%  -1.90% (p=0.000 n=10)
Marshal/SimpleDocument/map                     588.5n ± 1%                        610.5n ± 1%  +3.74% (p=0.000 n=10)
Marshal/ReferenceFile/struct                   19.95µ ± 1%                        19.34µ ± 1%  -3.04% (p=0.000 n=10)
Marshal/ReferenceFile/map                      37.98µ ± 7%                        38.21µ ± 3%       ~ (p=0.971 n=10)
Marshal/HugoFrontMatter                        7.645µ ± 3%                        7.524µ ± 3%  -1.58% (p=0.029 n=10)
RealWorldContainerdConfig                      39.00µ ± 2%                        38.55µ ± 1%  -1.14% (p=0.023 n=10)
RealWorldViperRead                             8.151µ ± 1%                        8.033µ ± 1%  -1.45% (p=0.000 n=10)
RealWorldViperWrite                            12.49µ ± 3%                        12.28µ ± 2%       ~ (p=0.403 n=10)
RealWorldHugoFrontMatterBatch                  92.64µ ± 1%                        91.44µ ± 1%  -1.30% (p=0.000 n=10)
RealWorldGitleaksRules                         62.87µ ± 1%                        62.18µ ± 1%  -1.10% (p=0.001 n=10)
RealWorldPyproject                             14.61µ ± 1%                        14.45µ ± 1%  -1.10% (p=0.000 n=10)
RealWorldGolangciStrict                        11.65µ ± 1%                        11.66µ ± 1%       ~ (p=0.670 n=10)
geomean                                        11.49µ                             11.39µ       -0.84%

darwin/arm64 (Apple M1 Pro, go1.26.4, 5 interleaved rounds × count=2, n=10)

                                │    sec/op    │   sec/op     vs base               │
Marshal/SimpleDocument/struct-8    197.8n ± 2%   196.8n ± 1%  -0.53% (p=0.025 n=10)
Marshal/SimpleDocument/map-8       301.3n ± 3%   299.2n ± 3%       ~ (p=0.446 n=10)
Marshal/ReferenceFile/struct-8     12.83µ ± 2%   12.70µ ± 3%  -1.03% (p=0.043 n=10)
Marshal/ReferenceFile/map-8        22.60µ ± 2%   22.61µ ± 1%       ~ (p=0.739 n=10)
Marshal/HugoFrontMatter-8          4.560µ ± 1%   4.509µ ± 1%  -1.13% (p=0.011 n=10)
RealWorldContainerdConfig-8        17.25µ ± 1%   17.22µ ± 1%       ~ (p=0.754 n=10)
RealWorldViperRead-8               3.886µ ± 1%   3.881µ ± 1%       ~ (p=0.726 n=10)
RealWorldViperWrite-8              7.582µ ± 2%   7.577µ ± 2%       ~ (p=0.726 n=10)
RealWorldHugoFrontMatterBatch-8    44.86µ ± 2%   44.96µ ± 3%       ~ (p=0.971 n=10)
RealWorldGitleaksRules-8           28.17µ ± 5%   28.22µ ± 1%       ~ (p=0.971 n=10)
RealWorldPyproject-8               7.217µ ± 1%   7.231µ ± 1%       ~ (p=0.591 n=10)
RealWorldGolangciStrict-8          4.904µ ± 1%   4.923µ ± 2%       ~ (p=0.542 n=10)
geomean                            5.903µ        5.890µ       -0.23%

@pelletier pelletier closed this Jul 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant