From 12b1ddaa8ba8f5667021bf257418cce00b9eb783 Mon Sep 17 00:00:00 2001 From: Fadion Dashi Date: Fri, 28 Aug 2026 01:20:05 +0200 Subject: [PATCH] docs: the slot-scopes number bounds half the question, not all of it #74 said the deep-versus-shallow name lookup difference was "the ceiling on what slots could win". It is not, and the overclaim is the kind that gets read later as a settled answer. Both benchmarks pay exactly one successful map lookup. What differs between them is the failed lookups at the scopes in between, so the fifth-more-time figure bounds chain-walking and says nothing about the other half of the change: replacing that final map lookup with an array index. No benchmark in the file can see that half, and none of them was built to. Two things worth writing down while correcting it. The cheaper half stands alone. Ref.Hops already records how far up a binding lives, so the evaluator could walk exactly that many parents and do one map lookup instead of up to Hops + 1. That collects the entire measured difference with `vars` still a map, no scope sizes plumbed anywhere, and define and assign untouched. And either version is a bigger step than swapping a data structure, because the evaluator has no runtime dependency on resolution at all: i.info is assigned in two places and read in none. Both would introduce one. The paths that would still need names are real -- the REPL's :vars walks globals.vars, an aliased import builds its module from scope.vars[name], and four New(file, nil) call sites have no Info to consult at all. The benchmark's own comment said the same loose thing and now says which half it measures, since that is where somebody reads it. Co-Authored-By: Claude Opus 5 --- docs/architecture.md | 33 ++++++++++++++++++++++++++------- internal/interp/bench_test.go | 10 ++++++---- 2 files changed, 32 insertions(+), 11 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index f5a4c30..c8ec6a1 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -999,11 +999,30 @@ itself a compatibility break. evaluator ignores, walking a chain of name maps instead. Switching would make lookup an array index. - There is now a number attached to this. `BenchmarkMicro/name-lookup-deep` and + There is a number attached to part of this. `BenchmarkMicro/name-lookup-deep` and `name-lookup-shallow` run the same loop and the same arithmetic, differing only in - whether the names come from three scopes up or from beside the loop, so the gap between - them is chain-walking and nothing else. On one machine the deep case costs around a fifth - more time and **ten more allocations out of eleven thousand** — the chain costs pointer - chasing, not garbage. That is the ceiling on what slots could win, in a case built to - make the chain as expensive as possible; a real program keeps its names closer. Measure - with benchstat before believing any of it, and before spending a rewrite on it. + whether the names come from three scopes up or from beside the loop. On one machine the + deep case costs around a fifth more time and **ten more allocations out of eleven + thousand**: the chain costs pointer chasing, not garbage. + + That bounds the chain-walking half and nothing else, which is worth being precise about. + Both cases pay exactly one *successful* map lookup, so what the difference measures is + the *failed* lookups at the scopes in between. Replacing that final map lookup with an + array index is the other half of what slots would do, and no benchmark here can see it. + So a fifth is not the ceiling on slots; it is the ceiling on the part that has been + measured, in a case built to make the chain as expensive as possible. + + The cheaper half can be had on its own. `Ref.Hops` already says how far up the binding + lives, so the evaluator could walk exactly that many parents and do one map lookup + instead of up to `Hops + 1`. That collects the whole measured difference while `vars` + stays a map, with no scope sizes to plumb through and no change to `define` or `assign`. + + Either version is a bigger step than swapping a data structure, because the evaluator has + no runtime dependency on resolution at all: `i.info` is assigned in two places and read + in none. Both would introduce one, and the name-keyed paths that would still need names + are real — the REPL's `:vars` walks `globals.vars`, an aliased import builds its module + by reading `scope.vars[name]`, and four `New(file, nil)` call sites have no `Info` to + consult. + + Measure with benchstat before believing any of this, and before spending a rewrite on + it. diff --git a/internal/interp/bench_test.go b/internal/interp/bench_test.go index d837dae..4455525 100644 --- a/internal/interp/bench_test.go +++ b/internal/interp/bench_test.go @@ -48,10 +48,12 @@ var workloads = []string{ // The micro workloads isolate what the examples exercise but do not separate. const ( - // Name lookup through a chain of scopes, which is what the resolver's unused - // slot indices would replace with an array index. See the Known Gaps entry - // in docs/architecture.md: this benchmark is what turns that from an opinion - // into a number. + // Name lookup through a chain of scopes. Paired with the shallow case below, + // this measures the cost of walking the chain -- and only that. Both cases + // pay one successful map lookup, so neither says anything about replacing + // that lookup with an array index, which is the other half of what slots + // would do. The Known Gaps entry in docs/architecture.md spells out which + // half is bounded and which is not. srcNameLookup = ` let outer = 1 let level1 = func ()