Repository navigation
perf(table): O(1)-per-step hash iteration via memoized order index - #349
Conversation
Replace the linear advance_past/2 scan in next_entry/2 with an O(1) position lookup. flush_order/1 now builds a memoized order array (order_arr) and a key => index map (order_index) once at the start of an iteration, so each hash step is an index lookup plus a forward scan to the next live key — making a full pairs loop O(n) instead of O(n^2). Any structural mutation of the order list invalidates the memo; clearing a value does not, preserving the Lua 5.3 §6.1 dead-key resume point. Plan: D
Adds StreamData properties asserting that a full next_entry/2 walk visits exactly the live key set once each, that the memoized order index agrees with the list-based fallback, and that clearing the current key mid-walk still visits every live key (the §6.1 dead-key resume guarantee) on both the memo and fallback paths.
🤖 Ultracode review — round 1Two findings, both nits — durability/coverage gaps in the new table-iteration tests, not correctness bugs. The reviewer confirmed the underlying behavior works by hand; these are about pinning it down with tests.
|
🤖 Ultracode review — round 1Two minor findings, both confirmed against the PR head. No blockers.
|
🤖 Ultracode review — round 2All four findings are confirmed against the PR head. None are blockers — the Round 1 fix is correct; these are coverage and cleanup gaps. [MAJOR]
Suggestion: Add a regression test (in [MINOR] The optimization targets the hash arm of Suggestion: Add (or extend [MINOR]
Suggestion: Add a unit test in [NIT] After the Round 1 reroute of Suggestion: Delete |
🤖 Ultracode review — round 3Blockers
Minor
|
What changed and why
lua_next/flush_ordernow memoizes the hash-key iteration order (an:arrayof keys plus akey => indexmap) on the first step of an iteration, so each subsequentnextis O(1) instead of re-scanning from the front. This turnspairsover a large hash-keyed table from O(n^2) into O(n).Motivated by an external performance review flagging the quadratic
pairspath on hash-keyed (string-keyed) tables.Benchmark delta
Scenario:
pairsover a large hash-keyed table (sum all values viafor k,v in pairs(t)wherethas N string keys"k1".."kN", forcing the hash/order iteration path, not the integer array fast path).origin/main@016fa35origin/main@016fa35Measurement notes: Wrote a minimal Benchee script
benchmarks/hash_pairs.exs(this-impl-only, no Luerl/luaport; buildsT=build(N)once into a global, then measures the chunkreturn sum_pairs(T)). Removed it after the run; NOT committed to this branch. Ran on both refs via detached-HEAD checkout in a worktree,MIX_ENV=benchmark. Sanity:sum_pairsreturnsn*(n+1)/2on both refs. Branch quick-mode N=2000 showed high deviation (+/-140%) on the now-sub-ms path, which is why the stable full-mode N=2000 figure is the reported headline. Env: Elixir 1.20.0 / Erlang 29 JIT, single run per ref (not multi-trial), so absolute ms carry normal single-machine noise; the order-of-magnitude speedup is unambiguous.Review verdict
State: ready. Tests pass after changes. No fixes required. Two nits noted (no action taken):
flush_ordernow eagerly allocates:array.from_list/1and akey => indexmap on the firstlua_nextof every iteration. For tables iterated once viapairsthis is pure win (O(n^2)->O(n)), but for anext(t, k)called a single time on a large table it does more upfront work than the old singleadvance_pastscan. Not a regression in practice (pairs always iterates fully) and the memo is correctly skipped on subsequent steps; noting only as a micro-tradeoff.pairsloop that nils keys, dead keys remain inorder_arrandfirst_live_fromscans past them viaMap.fetchon data. Total work stays O(n) across the loop (scan only advances forward), so the O(1)-amortized claim holds, but worst-case a single resumed step can scan past an accumulated run of dead keys. Documented correctly in thenext_hash_aftercomment.Merge
Human-gated merge: this PR is intentionally a draft. Do not merge without human review and sign-off.
Stabilization + independent verification
No stabilization changes were required — the PR shipped ready-as-is. All review findings were nit-severity; each was independently re-confirmed, not just taken on trust.
Correctness
mix test: 2255 passed, 0 failures (19 skipped).nextvar.luapasses unconditionally (no skip ranges).test/lua/vm/table_iteration_test.exs(8 tests) + existing nextvar/table unit tests (95) all green.next(t, "k1")returns{k51, 51}; the full live walk visits exactly k51..k60; an absent key returns:invalid_keyvia the memo. Clearing a value does not invalidate the memo (resume point preserved); inserting/reviving a key does.Performance (interpreter path,
LUA_BENCH_MODE=full, n=10k)Bytecode stripped to force the interpreter (
:lua_closure), baseline =origin/main@016fa35.pairslarge hash (n=10k)pairssmall (n=8)pairslarge array (n=10k)Memory: large hash 14.04 MB → 15.05 MB (+1 MB, expected from the one-time order-array/index memo); small table +~1.6 KB (the author-flagged build-memo-for-tiny-tables nit; trivial). The array path is untouched by the hash memo, so its small delta is pure variance.
The O(n²)→O(n) win for interpreter-routed hash iteration holds; small-table and array iteration show no regression.