From 71c1711ce4f25b13bf193231890ef581e45f4545 Mon Sep 17 00:00:00 2001 From: Artur Shiriev Date: Sun, 30 Aug 2026 20:57:36 +0300 Subject: [PATCH 1/2] docs(performance): disclose that the tables are a 3.3.0 snapshot The Results provenance block named the measurement date and version but was silent on the fact that a release never regenerates the tables, so a reader took them as current. Adds a disclosure adjacent to the tables and points a reader on a newer version at `just bench-report`. No published figure changes. Closes #437 Claude-Session: https://claude.ai/code/session_01FBic7HFGR6sdRfSW3cGEv2 --- docs/introduction/performance.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/introduction/performance.md b/docs/introduction/performance.md index cb30c880..8a7042e4 100644 --- a/docs/introduction/performance.md +++ b/docs/introduction/performance.md @@ -64,6 +64,13 @@ across-run dispersion of each side's own median. Rival versions: dishka 1.10.1, dependency-injector 4.49.1, that-depends 4.0.2, wireup 2.12.0. Generated by `just bench-report`. +> **These numbers are a snapshot of modern-di 3.3.0; a newer release does not update them.** +> Regenerating the tables needs the isolated comparative environment and a quiet machine, so it +> is a manual step that lags a release rather than part of one. If you are running a version +> later than 3.3.0, nothing below has been re-measured against it: run `just bench-report` +> yourself (see [Reproduce it yourself](#reproduce-it-yourself)) to measure the version you +> actually have. + Each cell is modern-di ÷ rival: below 1.0 (bold) means modern-di is faster, above 1.0 means slower. Every ratio is **paired within each run** — one run measures both sides under the same machine state, so the published statistic is the median of the per-run ratios, From 05999d2384e910752cd9f65b017c8313131548aa Mon Sep 17 00:00:00 2001 From: Artur Shiriev Date: Sun, 30 Aug 2026 20:59:46 +0300 Subject: [PATCH 2/2] docs(performance): anchor the crossover claims to 3.3.0 Two bolded lead-ins in "What the numbers show" read "modern-di is now faster than dishka" and "the by-type surcharge is now small enough", where "now" anchors to the reader's present rather than to the measured version. Names the version instead. Also drops the republication rationale from the snapshot blockquote, which restates benchmarks/README.md, and points it at the version line above rather than repeating the number. No published figure changes. Claude-Session: https://claude.ai/code/session_01FBic7HFGR6sdRfSW3cGEv2 --- docs/introduction/performance.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/introduction/performance.md b/docs/introduction/performance.md index 8a7042e4..a164dfcf 100644 --- a/docs/introduction/performance.md +++ b/docs/introduction/performance.md @@ -64,12 +64,11 @@ across-run dispersion of each side's own median. Rival versions: dishka 1.10.1, dependency-injector 4.49.1, that-depends 4.0.2, wireup 2.12.0. Generated by `just bench-report`. -> **These numbers are a snapshot of modern-di 3.3.0; a newer release does not update them.** -> Regenerating the tables needs the isolated comparative environment and a quiet machine, so it -> is a manual step that lags a release rather than part of one. If you are running a version -> later than 3.3.0, nothing below has been re-measured against it: run `just bench-report` -> yourself (see [Reproduce it yourself](#reproduce-it-yourself)) to measure the version you -> actually have. +> **These numbers are a snapshot of the version named above; a newer release does not update +> them.** The tables are regenerated by hand, so they lag a release rather than ship with one. If +> you are running a later modern-di, nothing below has been re-measured against it: run +> `just bench-report` yourself (see [Reproduce it yourself](#reproduce-it-yourself)) to measure +> the version you have. Each cell is modern-di ÷ rival: below 1.0 (bold) means modern-di is faster, above 1.0 means slower. Every ratio is **paired within each run** — one run measures both sides @@ -132,8 +131,8 @@ _Across-run IQR of each side's own median (5 runs): modern-di ≤1.9%, rivals that-depends, whose implied C2 absolute is unchanged at ~83 ns. that-depends remains faster on C2 warm-singleton (1.90); the suite does not decompose its `resolve_sync` cache-hit path, so no mechanism is asserted for the remaining gap. -- **Against the two `exec`-codegen frameworks, the by-type table has crossed over.** modern-di - is now faster than `dishka` on C1 (**0.91**) and C2 (**0.81**), and faster than `wireup` on +- **Against the two `exec`-codegen frameworks, the by-type table has crossed over.** At 3.3.0 + modern-di is faster than `dishka` on C1 (**0.91**) and C2 (**0.81**), and faster than `wireup` on C3 (**0.90**) while level on C1 (1.01). One publication earlier it was slower than both on every one of these cells. dishka keeps a clear lead on C3 (1.30), the deepest graph, which is consistent with the per-node call frame that `exec`-inlined source removes and modern-di @@ -141,7 +140,7 @@ _Across-run IQR of each side's own median (5 runs): modern-di ≤1.9%, rivals still dominates. modern-di does not generate code (a [documented non-goal](design-decisions.md#non-goals)); the gap closed by removing frames from the interpreted path instead. -- **The by-type surcharge is now small enough to stop mattering.** Dividing modern-di's +- **At 3.3.0 the by-type surcharge is small enough to stop mattering.** Dividing modern-di's by-reference cells by its by-type ones gives a fixed cost of 21/17/23 ns on C1/C2/C3, against 54-65 ns one publication earlier. `Container.resolve` no longer delegates to `resolve_provider` — it carries that body itself — so what remains is close to the bare