Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
215 changes: 215 additions & 0 deletions .agents/plans/B9-stdlib-hot-paths.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,215 @@
---
id: B9
title: "stdlib hot paths: string.format iolist + plain-table fast paths"
issue: 273
pr: 299
branch: perf/stdlib-hot-paths
base: main
status: review
direction: B
unlocks:
- closes most of the string.format gap vs Luerl (1.77x) and C Lua (5.5x)
- removes per-slot Executor dispatch overhead from table.sort / table.concat on plain tables
---

## Goal

Close three stdlib-side performance gaps surfaced by the benchmark suite.
All three are pure constant-factor wins on hot paths; observable behavior
is byte-for-byte identical before and after.

1. **`string.format` iolist accumulation.** `format_string/3` in
`lib/lua/vm/stdlib/string.ex` (around lines 333-350) builds its result
with per-character binary concatenation (`acc <> <<char::utf8>>` and
`acc <> str`). Each literal byte forces a binary reallocation, making
format O(n^2) in the length of the format string. Accumulate an iolist
instead and collapse it once with `IO.iodata_to_binary/1` at the base
case. This is the dominant cost in the 1.77x-vs-Luerl / 5.5x-vs-C-Lua
gap for `string.format`.

2. **`table.sort` / `table.concat` plain-table fast path.** Both
functions in `lib/lua/vm/stdlib/table.ex` route every element read
through `Executor.table_index/3` and (for sort) every write-back
through `Executor.table_newindex/3`. For a plain integer-indexed table
with no metatable these dispatch calls do ~200 extra `Map.fetch!` +
branch checks per 100-element sort. When `table.metatable == nil`,
read directly with `Lua.VM.Table.get_data/2` and write directly with
`Lua.VM.Table.put/3` + a single `Map.put/3` into `state.tables`,
skipping the metamethod-chain machinery entirely. This mirrors the
no-metatable fast path that already exists in
`Executor.table_newindex/5`.

3. **`apply_width_flags` byte-length padding.** `apply_width_flags/3` in
`lib/lua/vm/stdlib/string.ex` (around lines 815-836) measures the
string with `String.length/1` (O(graphemes), full UTF-8 decode) to
decide padding. The output of `%d` / `%f` / `%x` etc. is by definition
single-byte ASCII, so `byte_size/1` gives the same width count without
the grapheme walk.

## Out of scope

- The O(n^2) insertion-sort path used when a user-supplied Lua comparator
is passed (`sort_values/2` and `insert_sorted/4` in `table.ex`). Latent
but no current benchmark exercises it; defer until a comparator workload
motivates it. The comparator branch must keep going through
`Executor.call_function/3` and the existing read/write-back code so its
semantics (state threading, `__index`/`__newindex` observation) are
unchanged.
- `Lua.VM.Table.put/3`'s `order_tail` allocation on every write. Defer;
re-profile after #271 to see whether it is still the ceiling.
- Any change to the comparator-driven `table.sort` write-back, error
messages, or argument validation.

## Success criteria

- [ ] `mix format` produces no diff.
- [ ] `mix compile --warnings-as-errors` passes.
- [ ] `mix test` is green with no regressions (same pass/fail counts as
`main` before the change).
- [ ] `mix test --only lua53` shows no regression in suite pass count.
- [ ] `string.format` builds its result via an iolist with a single
`IO.iodata_to_binary/1` at the base case; no `acc <> ...` binary
concatenation remains in `format_string/3`.
- [ ] `table.sort` and `table.concat` read plain (metatable-less) tables
via `Lua.VM.Table.get_data/2`, and `table.sort` writes them back via
`Lua.VM.Table.put/3` + `Map.put/3`, only when
`table.metatable == nil`.
- [ ] Tables that DO have a metatable still go through
`Executor.table_index/3` / `Executor.table_newindex/3` (the
`__index` / `__newindex` / `__len` observation path is unchanged).
- [ ] `apply_width_flags/3` uses `byte_size/1` rather than
`String.length/1` for the width comparison.
- [ ] No behavioral change: existing
`test/lua/vm/stdlib/string_test.exs` and
`test/lua/vm/stdlib/table_test.exs` pass unmodified (no test
expectations changed).

## Implementation notes

Files to touch:

- `lib/lua/vm/stdlib/string.ex`
- `format_string/3` (~lines 333-350): change `acc` from a binary to an
iolist. The `""` base clause returns `IO.iodata_to_binary(acc)` (the
accumulator should be reversed-append-safe — prepend with
`[acc | piece]` is wrong for order; append with `[acc, piece]` keeps
order and is still O(1) per step since iolists nest). Concretely:
`format_string("", _args, acc), do: IO.iodata_to_binary(acc)`;
the `%%` clause becomes `format_string(rest2, args, [acc, "%"])`;
the spec clause becomes `format_string(rest2, remaining_args, [acc, str])`;
the literal clause becomes
`format_string(rest, args, [acc, <<char::utf8>>])`. The initial caller
`string_format/2` passes `""` today; `""` is a valid iodata seed so it
can stay, or switch to `[]`.
- `apply_width_flags/3` (~lines 815-836): replace
`if String.length(str) >= width` with
`if byte_size(str) >= width`. The padding branches
(`String.pad_leading/3`, `String.pad_trailing/3`,
`String.slice/2`) are left unchanged — they already operate on the
single-byte ASCII output of the numeric specifiers.

- `lib/lua/vm/stdlib/table.ex`
- `table_sort/2` (~lines 262-301): after resolving `len` (keep the
existing `Executor.table_length/2` call so `__len` is still observed),
branch on the table's metatable. Fetch the table once via
`Map.fetch!(state.tables, id)` (destructure the `id` from the `tref`).
When `table.metatable == nil`, build `values` with
`Lua.VM.Table.get_data(table.data, i)` over `1..len` and write the
sorted slice back with a single fold that threads an updated `data`
map / table struct and ends with one `Map.put(state.tables, id, ...)`
— i.e. use `Lua.VM.Table.put/3` per slot on the in-memory struct and
store the result once. When the metatable is present, fall through to
the existing `Executor.table_index/3` read loop and
`Executor.table_newindex/3` write-back loop unchanged. The
comparator-vs-default sort (`sort_values/2`) is untouched.
- `table_concat/2` (~lines 180-247): same metatable branch for the
element read loop (~lines 218-244). When `table.metatable == nil`,
read each slot via `Lua.VM.Table.get_data(table.data, idx)`; otherwise
keep `Executor.table_index/3`. The `Executor.table_length/2` call for
the default `j` must stay (it observes `__len`). The
`is_binary`/`is_number`/error handling for each value, and the final
`Enum.join/2`, are unchanged.

Subtleties:

- `Lua.VM.Table.get_data/2` already normalizes the key (it does
`Map.get(data, normalize_key(key))`), so integer indices behave the same
as the `Executor.table_index/3` path for plain tables. Do not
re-normalize.
- The fast path must only trigger when `metatable == nil`. Any non-nil
metatable (even one without `__index`/`__newindex`/`__len`) keeps the
Executor path, to preserve identical observable access ordering against
the reference impl.
- Keep `IO.iodata_to_binary/1` at exactly one place (the base case) so a
single binary is produced; do not intersperse `to_string`/`<>` collapses.

## Verification

```
mix format
mix compile --warnings-as-errors
mix test test/lua/vm/stdlib/string_test.exs
mix test test/lua/vm/stdlib/table_test.exs
mix test
mix test --only lua53
```

Capture `mix test` and `mix test --only lua53` pass/fail counts on `main`
before changing code and confirm the post-change counts match. The
`string_test.exs` and `table_test.exs` runs must pass without editing any
test expectations, since the change is behavior-preserving.

## Risks

- **iolist ordering bug.** Appending in the wrong order (`[piece | acc]`)
reverses the output. Mitigation: append as `[acc, piece]` and rely on
the existing `string_test.exs` `%%`, literal-text, and multi-spec cases
to catch a regression.
- **Fast path diverges from metatable path semantics.** If `get_data`/`put`
key normalization differed from `table_index`/`table_newindex`, plain
tables could read/write the wrong slot. Mitigation: both paths funnel
through `normalize_key/1`; gate strictly on `metatable == nil` and keep
metatable tables on the Executor path. `table_test.exs` covers both
plain and metatable-backed sort/concat.
- **`byte_size` vs `String.length` for non-ASCII.** `%s` can carry
multi-byte content, where `byte_size` over-counts graphemes. This change
is scoped to `apply_width_flags/3`, which is fed the numeric/ASCII
specifier output; verify no `%s` width test regresses in
`string_test.exs`. If a `%s` width case exists and relies on grapheme
width, restrict the `byte_size` swap to the numeric specifiers only.
- **Out-of-scope creep.** The comparator insertion sort is tempting to
"fix while here." Do not. Leave `sort_values/2` / `insert_sorted/4` and
`Table.put` `order_tail` exactly as-is; log any new finding under
`## Discoveries`.

## What changed

Shipped as PR #299.

Files touched:

- `lib/lua/vm/stdlib/string.ex`
- `format_string/3` now accumulates an iolist (`[acc, piece]`) and
materializes once with `IO.iodata_to_binary/1` at the `""` base
clause. The initial seed in `string_format/2` switched from `""` to
`[]`. No `acc <> ...` concatenation remains.
- `apply_width_flags/3` compares width with `byte_size/1` instead of
`String.length/1`. This also brings `%s` width into line with
PUC-Lua, which measures by bytes.
- `lib/lua/vm/stdlib/table.ex`
- Added `alias Lua.VM.Table`.
- `table_concat/2` binds the `tref` id, fetches the table once, and
reads slots via `Table.get_data/2` when `metatable == nil`; the
metatable case keeps `Executor.table_index/3`. Per-element coercion
extracted into `concat_value/2`.
- `table_sort/2` branches on `metatable`: `sort_plain/5` reads directly
from `data`, sorts, re-fetches the table (so a state-mutating
comparator is honored), writes back with `Table.put/3` per slot, and
stores once with `Map.put/3`. `sort_via_metamethods/4` preserves the
original `Executor.table_index/3` read + `table_newindex/3`
write-back for metatable-backed tables.

Verification: `mix test` 2092 passed / 19 skipped / 1 excluded and
`mix test --only lua53` 17 passed / 12 skipped — both identical to `main`.

No follow-up issues opened; no `## Discoveries`.
129 changes: 129 additions & 0 deletions benchmarks/string_format.exs
Original file line number Diff line number Diff line change
@@ -0,0 +1,129 @@
# Run with: mix run benchmarks/string_format.exs
#
# Benchmarks string.format across format strings whose cost is dominated by
# different things, so the formatter is exercised on more than one axis:
#
# - long_format: a long, literal-heavy format string (~430 chars of
# literal text around three specifiers). Stresses how the
# formatter accumulates literal runs — the dominant cost
# here is copying literal bytes, not converting arguments.
# - width_format: many width-flagged specifiers (%-20s, %8d, %12.4f, %6x),
# exercising the width/padding path on every conversion.
# - many_specs: a dozen specifiers interleaved with short literal runs,
# the conversion-heavy counterpart to long_format.
#
# Each workload formats n=1000 strings per invocation so the per-call cost
# is visible above harness overhead.
#
# Compares:
# - This Lua implementation (eval with string, eval with pre-compiled chunk)
# - Luerl (Erlang-based Lua 5.3 implementation)
# - C Lua 5.4 via luaport (port-based; results include IPC overhead)
#
# NOTE: luaport requires C Lua 5.4 development headers and a small in-tree
# patch (its 1.6.3 release defaults to LuaJIT and uses LUA_GLOBALSINDEX which
# was removed in Lua 5.2). On macOS:
# brew install lua@5.4
# ./benchmarks/setup_luaport.sh # idempotent; patches + builds
# MIX_ENV=benchmark mix run benchmarks/string_format.exs
# If luaport fails to start, the benchmark prints a notice and skips it.

Code.require_file("helpers.exs", __DIR__)

Application.ensure_all_started(:luerl)

string_def = """
-- A long, literal-heavy format string: ~430 chars of literal text wrapped
-- around three specifiers. The literal runs dominate the cost.
local LONG = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, " ..
"sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. " ..
"Ut enim ad minim veniam, quis nostrud exercitation [%d] ullamco " ..
"laboris nisi ut aliquip ex ea commodo consequat [%s]. Duis aute " ..
"irure dolor in reprehenderit in voluptate velit esse cillum dolore " ..
"eu fugiat nulla pariatur [%.3f]. Excepteur sint occaecat cupidatat " ..
"non proident, sunt in culpa qui officia deserunt mollit anim id est."

function run_long_format(n)
local last = ""
for i = 1, n do
last = string.format(LONG, i, "tag", i * 0.5)
end
return #last
end

-- Width-flagged specifiers exercise the padding path on every call.
function run_width_format(n)
local last = ""
for i = 1, n do
last = string.format("[%-20s][%8d][%12.4f][%-15s][%6x]",
"name", i, i * 1.25, "label", i)
end
return #last
end

-- Many specifiers interleaved with short literal runs.
function run_many_specs(n)
local last = ""
for i = 1, n do
last = string.format(
"a=%d b=%d c=%d d=%s e=%s f=%.2f g=%.2f h=%x i=%x j=%d k=%s l=%d",
i, i + 1, i + 2, "x", "y", i * 1.5, i * 2.5, i, i + 1, i + 3, "z", i + 4)
end
return #last
end
"""

call_long = "return run_long_format(1000)"
call_width = "return run_width_format(1000)"
call_many = "return run_many_specs(1000)"

# --- This Lua implementation ---
lua = Lua.new()
{_, lua} = Lua.eval!(lua, string_def)
{long_chunk, _} = Lua.load_chunk!(lua, call_long)
{width_chunk, _} = Lua.load_chunk!(lua, call_width)
{many_chunk, _} = Lua.load_chunk!(lua, call_many)

# --- Luerl ---
luerl_state = :luerl.init()
{:ok, _, luerl_state} = :luerl.do(string_def, luerl_state)

# --- C Lua via luaport (optional) ---
{c_lua, c_lua_cleanup} =
case Application.ensure_all_started(:luaport) do
{:ok, _} ->
scripts_dir = Path.join(__DIR__, "scripts")
{:ok, port_pid, _} = :luaport.spawn(:string_format_bench, to_charlist(scripts_dir))
:luaport.load(port_pid, string_def)

{
fn func -> %{"C Lua (luaport)" => fn -> :luaport.call(port_pid, func, [1000]) end} end,
fn -> :luaport.despawn(:string_format_bench) end
}

{:error, reason} ->
IO.puts("luaport not available (#{inspect(reason)}) — skipping C Lua benchmarks")
{fn _func -> %{} end, fn -> :ok end}
end

bench = fn name, call_str, chunk, c_lua_func ->
Bench.banner(name)

Benchee.run(
Map.merge(
%{
"lua (eval)" => fn -> Lua.eval!(lua, call_str) end,
"lua (chunk)" => fn -> Lua.eval!(lua, chunk) end,
"luerl" => fn -> :luerl.do(call_str, luerl_state) end
},
c_lua.(c_lua_func)
),
Bench.opts()
)
end

bench.("string.format: long literal-heavy format string (n=1000)", call_long, long_chunk, :run_long_format)
bench.("string.format: width-flagged specifiers (n=1000)", call_width, width_chunk, :run_width_format)
bench.("string.format: many specifiers (n=1000)", call_many, many_chunk, :run_many_specs)

c_lua_cleanup.()
Loading
Loading