From 3a97d0f57338b5f2d36064e11f73b4830f635870 Mon Sep 17 00:00:00 2001 From: Dave Lucia Date: Mon, 1 Jun 2026 09:52:46 -0700 Subject: [PATCH 1/4] chore(B10): start plan --- .../plans/B10-table-sort-batch-writeback.md | 136 ++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 .agents/plans/B10-table-sort-batch-writeback.md diff --git a/.agents/plans/B10-table-sort-batch-writeback.md b/.agents/plans/B10-table-sort-batch-writeback.md new file mode 100644 index 00000000..5b8e4ba5 --- /dev/null +++ b/.agents/plans/B10-table-sort-batch-writeback.md @@ -0,0 +1,136 @@ +--- +id: B10 +title: Batch write-back in table.sort plain fast path +issue: 307 +pr: null +branch: perf/table-sort-batch-writeback +base: main +status: in-progress +direction: B +--- + +## Goal + +`table.sort` on plain (metatable-less) tables is ~1.44x slower than luerl +at n=100 (46.1µs vs 31.9µs in `benchmarks/table_ops.exs`). The plain-table +fast path (PR #299) reads and sorts efficiently, but the write-back loop in +`lib/lua/vm/stdlib/table.ex` (~312-326) still calls `Table.put/3` once per +index inside an `Enum.reduce`. Each call rebuilds the seven-field +`%Table{}` struct and walks the `order`/`dead` insertion-order bookkeeping, +so writing back an n-element slice is O(n) struct rebuilds. + +Replace the per-index reduce with a single map build plus one +`Table.replace_data/2` call. `replace_data/2` already exists +(`lib/lua/vm/table.ex:80`): it sets `data`, rebuilds `order` from +`Map.keys(data)`, and clears `dead` in one struct update. Because sort +rewrites every integer key `1..len` and never depends on the prior +`order`/`dead` state, the wholesale replacement is observably identical to +the per-index writes. + +This is a perf-only change. Observable behavior — sorted result, error +behavior, metatable path, comparator-mutation re-fetch — is unchanged. + +Target: bring the plain-sort path to ≤ 1.10x luerl at n=100. + +## Out of scope + +- The metatable-backed sort path (`sort_via_metamethods/4`). It must keep + reading via `__index` and writing via `__newindex` so metamethod + observation order matches the reference impl; it is untouched here. +- The comparator/sort algorithm itself (`sort_values/3`) and the read loop + (`Enum.map(1..len//1, ...)`). Only the write-back step changes. +- Any change to `Table.replace_data/2`, `Table.put/3`, or the `%Table{}` + struct shape. This plan only changes the *caller* in the stdlib. +- Optimizing `table.insert`, `table.remove`, or other table stdlib ops. +- Array-part / threshold-promotion storage rework (the deferred B7 idea). + +## Success criteria + +- [ ] `mix format` clean and `mix compile --warnings-as-errors` passes. +- [ ] `mix test` full suite green with no regressions. +- [ ] `mix test test/lua/vm/stdlib/table_test.exs` passes — sort behavior + (sorted result, custom comparator, comparator that mutates the table, + stable handling of `len <= 1`) unchanged. +- [ ] `mix run benchmarks/table_ops.exs` shows the plain `table.sort` path + at ≤ 1.10x luerl at n=100 (down from ~1.44x). New ratio recorded in + the PR body. +- [ ] No behavior change: the write-back produces the same final table + contents and `order`/`dead` state as a fresh sequence of `Table.put/3` + writes over keys `1..len`. + +## Implementation notes + +Single file: `lib/lua/vm/stdlib/table.ex`, in `sort_plain/5` (~312-326). + +Replace the per-index reduce: + +```elixir +updated = + sorted + |> Enum.with_index(1) + |> Enum.reduce(table, fn {val, idx}, tbl -> Table.put(tbl, idx, val) end) + +{[], %{state | tables: Map.put(state.tables, id, updated)}} +``` + +with a single map build and one `Table.replace_data/2` call, e.g.: + +```elixir +data = + sorted + |> Enum.with_index(1) + |> Map.new(fn {val, idx} -> {idx, val} end) + +updated = Table.replace_data(table, data) + +{[], %{state | tables: Map.put(state.tables, id, updated)}} +``` + +Notes: + +- `replace_data/2` (`lib/lua/vm/table.ex:80`) sets `data`, rebuilds `order` + from `Map.keys(data)`, and clears `dead`. Since sort assigns every key + `1..len`, this is equivalent to the per-key writes that the old reduce + performed. +- `sorted` always has exactly `len` elements (it is the sorted permutation + of the `len` values read at the top of `sort_plain/5`), so the rebuilt + `data` map has keys `1..len` and no stale keys remain. +- Keep the `len <= 1` clause and the comparator-mutation re-fetch + (`table = Map.fetch!(state.tables, id)`) exactly as they are; only the + write-back lines change. +- Update the fast-path comment so it describes the single + `Table.replace_data/2` write-back rather than per-index `Table.put/3`. + Do not reference the plan id in any source comment. +- Run `mix format` after the edit. + +## Verification + +```bash +mix format +mix compile --warnings-as-errors +mix test +mix test test/lua/vm/stdlib/table_test.exs +mix run benchmarks/table_ops.exs +``` + +Record the "Table Sort" n=100 luerl ratio from the benchmark output in the +PR body (before: ~1.44x; target: ≤ 1.10x). If `mix run benchmarks/table_ops.exs` +honors a bench mode env var, note which mode was used. + +## Risks + +- **Stale keys after replace.** If `sorted` somehow had fewer elements than + the original `len`, `replace_data/2` would drop the extra keys. Mitigation: + sort is a pure permutation of the `len` values read up front, so + `length(sorted) == len` by construction; verified by the existing sort + tests in `table_test.exs`. +- **Order/dead semantics divergence.** A future caller could rely on the + old per-index revive-dead-key behavior. Not a concern here: a freshly + sorted plain array has all keys `1..len` live, and `replace_data/2` + clearing `dead` matches the observable result of overwriting every live + key. Covered by full-suite `mix test`. +- **Benchmark target not met.** If the change lands below the projected win + and stays above 1.10x, the perf criterion fails. Mitigation: the change + is still a strict reduction in struct rebuilds and is safe to ship as an + improvement; record the actual ratio and, if short of target, note a + follow-up rather than expanding this PR's scope. From a82155327b9a160646a3a06b6f7a63e03ca522ca Mon Sep 17 00:00:00 2001 From: Dave Lucia Date: Mon, 1 Jun 2026 10:01:12 -0700 Subject: [PATCH 2/4] perf(stdlib): batch write-back in table.sort plain fast path MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The plain-table sort fast path wrote the sorted slice back with an Enum.reduce that called Table.put/3 once per index, rebuilding the seven-field %Table{} struct and walking order/dead bookkeeping on every iteration — O(n) struct rebuilds. Sort rewrites every integer key 1..len and never depends on the prior order/dead state, so build the new data map in one pass and swap it in with a single Table.replace_data/2 call. Perf-only: sorted result, error behavior, metatable path, and comparator-mutation re-fetch are unchanged. Plan: B10 Closes #307 --- lib/lua/vm/stdlib/table.ex | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/lib/lua/vm/stdlib/table.ex b/lib/lua/vm/stdlib/table.ex index 784ea775..ace2ec7f 100644 --- a/lib/lua/vm/stdlib/table.ex +++ b/lib/lua/vm/stdlib/table.ex @@ -302,7 +302,7 @@ defmodule Lua.VM.Stdlib.Table do # Fast path for a metatable-less table: read each slot directly from # `data`, sort, then write the sorted slice back with a single - # `Map.put/3` into `state.tables`. Skips the __index/__newindex dispatch + # `Table.replace_data/2` call. Skips the __index/__newindex dispatch # machinery entirely, which is safe because there are no metamethods to # observe. defp sort_plain(_id, _table, len, _comp, state) when len <= 1 do @@ -318,10 +318,16 @@ defmodule Lua.VM.Stdlib.Table do # comparator the table is unchanged and this is the same struct. table = Map.fetch!(state.tables, id) - updated = + # Sort rewrites every integer key 1..len, so build the new data map in + # one pass and swap it in wholesale instead of rebuilding the struct per + # index. `replace_data/2` resets order/dead, which is correct because the + # sorted array has all keys 1..len live. + data = sorted |> Enum.with_index(1) - |> Enum.reduce(table, fn {val, idx}, tbl -> Table.put(tbl, idx, val) end) + |> Map.new(fn {val, idx} -> {idx, val} end) + + updated = Table.replace_data(table, data) {[], %{state | tables: Map.put(state.tables, id, updated)}} end From 5376eba6d66f6a6098177291039e2349c46ec50a Mon Sep 17 00:00:00 2001 From: Dave Lucia Date: Mon, 1 Jun 2026 10:02:01 -0700 Subject: [PATCH 3/4] chore(B10): mark plan as review --- .../plans/B10-table-sort-batch-writeback.md | 30 +++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/.agents/plans/B10-table-sort-batch-writeback.md b/.agents/plans/B10-table-sort-batch-writeback.md index 5b8e4ba5..18047ce5 100644 --- a/.agents/plans/B10-table-sort-batch-writeback.md +++ b/.agents/plans/B10-table-sort-batch-writeback.md @@ -2,10 +2,10 @@ id: B10 title: Batch write-back in table.sort plain fast path issue: 307 -pr: null +pr: 318 branch: perf/table-sort-batch-writeback base: main -status: in-progress +status: review direction: B --- @@ -134,3 +134,29 @@ honors a bench mode env var, note which mode was used. is still a strict reduction in struct rebuilds and is safe to ship as an improvement; record the actual ratio and, if short of target, note a follow-up rather than expanding this PR's scope. + +## What changed + +PR #318. Replaced the per-index `Enum.reduce(... Table.put/3 ...)` +write-back in `sort_plain/5` (`lib/lua/vm/stdlib/table.ex`) with a single +`Map.new/2` build plus one `Table.replace_data/2` call, and updated the +fast-path comment to describe the wholesale swap. No other files changed. + +Verification on this run: + +- `mix format` clean; `mix compile --warnings-as-errors` produced no + warnings from the `lua` app. +- `mix test`: `2114 passed, 19 skipped, 1 excluded`. +- `mix test test/lua/vm/stdlib/table_test.exs`: `60 passed (6 properties, + 54 tests)`. +- `MIX_ENV=benchmark mix run benchmarks/table_ops.exs` — Table Sort, n=100 + (mode: quick), `lua (chunk)` vs `luerl`, same M4 machine: + - main: 34.03 µs vs luerl 21.76 µs = 1.56x + - this PR: 30.06 µs vs luerl 20.45 µs = 1.47x + +Outcome: a consistent ~12% speedup on the plain-sort path and a strict +reduction in struct rebuilds. The issue's ≤1.10x target was set against a +recorded luerl baseline of 31.9 µs; on this M4 luerl benches at ~21 µs, so +the ratio target is not reachable by this single optimization. Per the +Risks section, shipped as a genuine improvement with the actual ratio +recorded; closing the remaining gap is follow-up work, not scope creep. From f00466cc0c0e96f82af808039c9fa199d7349966 Mon Sep 17 00:00:00 2001 From: Dave Lucia Date: Mon, 1 Jun 2026 10:14:52 -0700 Subject: [PATCH 4/4] perf(stdlib): address review feedback Preserve non-array keys in table.sort plain fast path. The previous wholesale data-map swap dropped string and sparse keys; merge the sorted slice over the existing data instead so only keys 1..len are reordered, matching Lua 5.3 table.sort. Adds a regression test. Plan: B10 --- lib/lua/vm/stdlib/table.ex | 20 ++++++++++---------- test/lua/vm/stdlib/table_test.exs | 16 ++++++++++++++++ 2 files changed, 26 insertions(+), 10 deletions(-) diff --git a/lib/lua/vm/stdlib/table.ex b/lib/lua/vm/stdlib/table.ex index ace2ec7f..a9b4fea4 100644 --- a/lib/lua/vm/stdlib/table.ex +++ b/lib/lua/vm/stdlib/table.ex @@ -301,10 +301,9 @@ defmodule Lua.VM.Stdlib.Table do end # Fast path for a metatable-less table: read each slot directly from - # `data`, sort, then write the sorted slice back with a single - # `Table.replace_data/2` call. Skips the __index/__newindex dispatch - # machinery entirely, which is safe because there are no metamethods to - # observe. + # `data`, sort, then merge the sorted slice back over `data` in one pass. + # Skips the __index/__newindex dispatch machinery entirely, which is safe + # because there are no metamethods to observe. defp sort_plain(_id, _table, len, _comp, state) when len <= 1 do {[], state} end @@ -318,16 +317,17 @@ defmodule Lua.VM.Stdlib.Table do # comparator the table is unchanged and this is the same struct. table = Map.fetch!(state.tables, id) - # Sort rewrites every integer key 1..len, so build the new data map in - # one pass and swap it in wholesale instead of rebuilding the struct per - # index. `replace_data/2` resets order/dead, which is correct because the - # sorted array has all keys 1..len live. - data = + # Sort only reorders the values under keys 1..len; every other key + # (string fields, sparse integers > len, etc.) must survive untouched, + # matching Lua 5.3 table.sort. Keys 1..len already exist in `data` and + # in `order`, so merging the sorted slice over the existing map changes + # values in place without disturbing order/dead or any other key. + sorted_slice = sorted |> Enum.with_index(1) |> Map.new(fn {val, idx} -> {idx, val} end) - updated = Table.replace_data(table, data) + updated = %{table | data: Map.merge(table.data, sorted_slice)} {[], %{state | tables: Map.put(state.tables, id, updated)}} end diff --git a/test/lua/vm/stdlib/table_test.exs b/test/lua/vm/stdlib/table_test.exs index 72c84ccb..af4a78f6 100644 --- a/test/lua/vm/stdlib/table_test.exs +++ b/test/lua/vm/stdlib/table_test.exs @@ -186,6 +186,22 @@ defmodule Lua.VM.Stdlib.TableTest do assert {:ok, [1, 1, 2, 3], _state} = VM.execute(proto, state) end + test "table.sort preserves non-array keys" do + code = """ + local t = {30, 10, 20} + t.name = "hi" + t[100] = "sparse" + table.sort(t) + return t[1], t[2], t[3], t.name, t[100] + """ + + assert {:ok, ast} = Parser.parse(code) + assert {:ok, proto} = Compiler.compile(ast, source: "test.lua") + state = Stdlib.install(State.new()) + + assert {:ok, [10, 20, 30, "hi", "sparse"], _state} = VM.execute(proto, state) + end + test "table.move copies elements" do code = """ local t1 = {1, 2, 3, 4, 5}