From 517b036f4c9f753e957d927cf5129f223002aaa7 Mon Sep 17 00:00:00 2001 From: Dave Lucia Date: Thu, 4 Jun 2026 08:24:20 -0700 Subject: [PATCH 01/12] test(vm): pin Lua 5.3 pcall heap-effect preservation semantics Red tests for protected-call error unwinding: heap effects (globals, table fields, upvalue cells, metatables) made before an error must survive pcall/xpcall trapping the error, matching reference Lua. Covers both the dispatcher and interpreter engines plus the Lua.call_function Elixir API error path. --- test/lua/vm/pcall_state_preservation_test.exs | 401 ++++++++++++++++++ 1 file changed, 401 insertions(+) create mode 100644 test/lua/vm/pcall_state_preservation_test.exs diff --git a/test/lua/vm/pcall_state_preservation_test.exs b/test/lua/vm/pcall_state_preservation_test.exs new file mode 100644 index 00000000..72115bb5 --- /dev/null +++ b/test/lua/vm/pcall_state_preservation_test.exs @@ -0,0 +1,401 @@ +defmodule Lua.VM.PcallStatePreservationTest do + @moduledoc """ + Pins Lua 5.3 §2.3 / §6.1 protected-call semantics: `pcall`/`xpcall` trap + the error and unwind the stack, but heap effects performed before the + error — global writes, table field mutations, upvalue assignments, + metatable changes — are kept, never rolled back. + + Reference behavior (PUC Lua 5.3): + + $ lua -e 'x = 1; pcall(function() x = 2; error("boom") end); print(x)' + 2 + + Each case runs under both execution engines: the default compile path + (closures carry bytecode and run on the dispatcher) and with bytecode + recursively stripped (closures run on the instruction interpreter). + """ + use ExUnit.Case, async: true + + alias Lua.Compiler + alias Lua.Compiler.Prototype + alias Lua.Parser + alias Lua.VM + alias Lua.VM.State + alias Lua.VM.Stdlib + + defp run(code, engine, state_fun \\ &Function.identity/1) do + {:ok, ast} = Parser.parse(code) + {:ok, proto} = Compiler.compile(ast, source: "test.lua") + + proto = + case engine do + :compiled -> proto + :interpreted -> strip_bytecode(proto) + end + + state = state_fun.(Stdlib.install(State.new())) + {:ok, results, state} = VM.execute(proto, state) + {results, state} + end + + # Forces every closure onto the instruction interpreter — the closure + # tag flips on `proto.bytecode`, so stripping it recursively keeps the + # whole program off the dispatcher. + defp strip_bytecode(%Prototype{} = proto) do + %{proto | bytecode: nil, prototypes: Enum.map(proto.prototypes, &strip_bytecode/1)} + end + + for engine <- [:compiled, :interpreted] do + @engine engine + + describe "pcall keeps heap effects on error (#{engine} engine)" do + test "global write before error() is kept" do + {results, _state} = + run( + """ + x = 1 + local ok, err = pcall(function() + x = 2 + error("boom") + end) + return x, ok, err + """, + @engine + ) + + assert [2, false, err] = results + assert err =~ "boom" + end + + test "table field write before error() is kept" do + {results, _state} = + run( + """ + local t = {} + local ok = pcall(function() + t.a = 1 + error("e") + end) + return t.a, ok + """, + @engine + ) + + assert [1, false] = results + end + + test "upvalue write before error() is kept" do + {results, _state} = + run( + """ + local v = 1 + local ok = pcall(function() + v = 2 + error("e") + end) + return v, ok + """, + @engine + ) + + assert [2, false] = results + end + + test "global write before an arithmetic type error is kept" do + {results, _state} = + run( + """ + x = 1 + local ok = pcall(function() + x = 2 + return nil + 1 + end) + return x, ok + """, + @engine + ) + + assert [2, false] = results + end + + test "table write before an index-nil error is kept" do + {results, _state} = + run( + """ + local t = {} + local ok = pcall(function() + t.a = 1 + local y = nil + return y.field + end) + return t.a, ok + """, + @engine + ) + + assert [1, false] = results + end + + test "global write before a concat type error is kept" do + {results, _state} = + run( + """ + x = 1 + local ok = pcall(function() + x = 2 + return "a" .. nil + end) + return x, ok + """, + @engine + ) + + assert [2, false] = results + end + + test "global write before assert(false) is kept" do + {results, _state} = + run( + """ + x = 1 + local ok = pcall(function() + x = 2 + assert(false) + end) + return x, ok + """, + @engine + ) + + assert [2, false] = results + end + + test "global write before a stdlib bad-argument error is kept" do + {results, _state} = + run( + """ + x = 1 + local ok = pcall(function() + x = 2 + return string.rep() + end) + return x, ok + """, + @engine + ) + + assert [2, false] = results + end + + test "mutation before error() with a table error object is kept" do + {results, _state} = + run( + """ + x = 1 + local ok, err = pcall(function() + x = 2 + error({code = 1}) + end) + return x, ok, err ~= nil + """, + @engine + ) + + assert [2, false, true] = results + end + + test "nested pcall keeps mutations at every level" do + {results, _state} = + run( + """ + local ok_outer = pcall(function() + a = 1 + local ok_inner = pcall(function() + b = 2 + error("inner") + end) + c = ok_inner == false and 3 or -1 + error("outer") + end) + return a, b, c, ok_outer + """, + @engine + ) + + assert [1, 2, 3, false] = results + end + + test "setmetatable before error is kept" do + {results, _state} = + run( + """ + local t = {} + local ok = pcall(function() + setmetatable(t, {__index = function() return 42 end}) + error("e") + end) + return ok, t.missing + """, + @engine + ) + + assert [false, 42] = results + end + + test "call stack unwinds cleanly after recursion errors under pcall" do + {results, state} = + run( + """ + x = 0 + local function deep(n) + x = x + 1 + if n == 0 then error("bottom") end + deep(n - 1) + end + local ok = pcall(deep, 5) + local function f() return x end + return ok, f(), x + """, + @engine + ) + + assert [false, 6, 6] = results + # No leaked frames from the unwound protected call. + assert state.call_depth == 0 + assert state.call_stack == [] + end + + test "closure captured before pcall still reads the kept upvalue after" do + {results, _state} = + run( + """ + local v = 1 + local function get() return v end + local function set(n) v = n end + local ok = pcall(function() + set(2) + error("e") + end) + return ok, get(), v + """, + @engine + ) + + assert [false, 2, 2] = results + end + + test "mutations before a stack-overflow error are kept" do + {results, _state} = + run( + """ + x = 0 + local function loop() + x = x + 1 + loop() + return 1 + end + local ok = pcall(loop) + return ok, x > 1 + """, + @engine, + fn state -> %{state | max_call_depth: 30} end + ) + + assert [false, true] = results + end + + test "pcall that errors without mutating leaves prior state untouched" do + {results, _state} = + run( + """ + z = 9 + local ok = pcall(function() + error("e") + end) + return z, ok + """, + @engine + ) + + assert [9, false] = results + end + + test "pcall success path is unchanged" do + {results, _state} = + run( + """ + x = 1 + local ok, v = pcall(function() + x = 2 + return 7 + end) + return x, ok, v + """, + @engine + ) + + assert [2, true, 7] = results + end + end + + describe "xpcall keeps heap effects on error (#{engine} engine)" do + test "message handler observes mutations made before the error" do + {results, _state} = + run( + """ + x = 1 + local ok, seen = xpcall(function() + x = 2 + error("e") + end, function(msg) + return x + end) + return ok, seen, x + """, + @engine + ) + + assert [false, 2, 2] = results + end + + test "mutations are kept even when the handler itself errors" do + {results, _state} = + run( + """ + x = 1 + local ok = xpcall(function() + x = 2 + error("first") + end, function(msg) + h = 5 + error("handler") + end) + return x, h, ok + """, + @engine + ) + + assert [2, 5, false] = results + end + end + end + + describe "Elixir API error path" do + test "Lua.call_function/3 returns state retaining pre-error mutations" do + lua = Lua.new() + + {_, lua} = + Lua.eval!(lua, """ + x = 1 + function f() + x = 2 + error("boom") + end + """) + + assert {:error, reason, lua} = Lua.call_function(lua, [:f], []) + assert reason =~ "boom" + assert Lua.get!(lua, [:x]) == 2 + end + end +end From ab203af48aa35432b8adde16d453f115c48657a0 Mon Sep 17 00:00:00 2001 From: Dave Lucia Date: Thu, 4 Jun 2026 08:29:05 -0700 Subject: [PATCH 02/12] fix(vm): keep heap effects across protected-call error unwinding MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit VM exceptions gain a :state field carrying the raise-time State. pcall/xpcall/Lua.call_function recover it via State.unwind_to/2 — heap fields (tables, userdata, metatables, upvalue cells, private) come from the raise-time snapshot, control fields (call stack, open upvalues) restore from the protected-call entry, matching Lua 5.3 §2.3 error semantics. Annotates the raise sites that already have state in scope: error(), assert(), stack-overflow, and call-type errors in both engines. --- lib/lua.ex | 13 +++++-- lib/lua/vm/argument_error.ex | 10 ++++- lib/lua/vm/assertion_error.ex | 9 ++++- lib/lua/vm/executor.ex | 38 ++++++++++++------- lib/lua/vm/runtime_error.ex | 9 ++++- lib/lua/vm/state.ex | 45 +++++++++++++++++++++- lib/lua/vm/stdlib.ex | 70 ++++++++++++++++++----------------- lib/lua/vm/type_error.ex | 9 ++++- 8 files changed, 144 insertions(+), 59 deletions(-) diff --git a/lib/lua.ex b/lib/lua.ex index 47bb84b7..c89db484 100644 --- a/lib/lua.ex +++ b/lib/lua.ex @@ -771,7 +771,7 @@ defmodule Lua do {results, new_state} = fun.(args, state) {:ok, List.wrap(results), new_state} rescue - e -> {:error, Exception.message(e), state} + e -> {:error, Exception.message(e), recover_state(e, state)} end defp do_call_function({:lua_closure, proto, upvalues}, args, state) do @@ -789,7 +789,7 @@ defmodule Lua do {:ok, results, new_state} rescue - e -> {:error, Exception.message(e), state} + e -> {:error, Exception.message(e), recover_state(e, state)} end defp do_call_function({:compiled_closure, _, _} = closure, args, state) do @@ -798,13 +798,20 @@ defmodule Lua do {results, new_state} = Executor.call_function(closure, args, state) {:ok, results, new_state} rescue - e -> {:error, Exception.message(e), state} + e -> {:error, Exception.message(e), recover_state(e, state)} end defp do_call_function(other, _args, state) do {:error, "undefined function '#{inspect(other)}'", state} end + # This is a protected-call boundary like pcall: trapping the error + # unwinds control state, but heap effects the callee made before raising + # are kept (Lua 5.3 §2.3). VM exceptions ferry the raise-time state out + # on their `:state` field; anything else falls back to the entry state. + defp recover_state(%{state: %State{} = raised}, entry), do: State.unwind_to(entry, raised) + defp recover_state(_e, entry), do: entry + @doc """ The raising variant of `call_function/3` diff --git a/lib/lua/vm/argument_error.ex b/lib/lua/vm/argument_error.ex index 051e3550..28962708 100644 --- a/lib/lua/vm/argument_error.ex +++ b/lib/lua/vm/argument_error.ex @@ -45,6 +45,10 @@ defmodule Lua.VM.ArgumentError do @type t :: %__MODULE__{} + # `:state` carries the `Lua.VM.State` as of the raise, so protected calls + # (pcall/xpcall) can keep heap effects made before the error instead of + # rolling back to their entry snapshot. It is out-of-band metadata: it never + # participates in `message` and stays `nil` when no state was in scope. defexception [ :function_name, :arg_num, @@ -53,7 +57,8 @@ defmodule Lua.VM.ArgumentError do :details, :line, :source, - :call_stack + :call_stack, + :state ] @impl true @@ -70,7 +75,8 @@ defmodule Lua.VM.ArgumentError do details: Keyword.get(opts, :details), line: Keyword.get(opts, :line) || auto_line, source: Keyword.get(opts, :source) || auto_source, - call_stack: Keyword.get(opts, :call_stack, []) + call_stack: Keyword.get(opts, :call_stack, []), + state: Keyword.get(opts, :state) } end diff --git a/lib/lua/vm/assertion_error.ex b/lib/lua/vm/assertion_error.ex index cd6b3f88..1b590607 100644 --- a/lib/lua/vm/assertion_error.ex +++ b/lib/lua/vm/assertion_error.ex @@ -11,7 +11,11 @@ defmodule Lua.VM.AssertionError do @type t :: %__MODULE__{} - defexception [:value, :source, :message, :call_stack, :line] + # `:state` carries the `Lua.VM.State` as of the raise, so protected calls + # (pcall/xpcall) can keep heap effects made before the error instead of + # rolling back to their entry snapshot. It is out-of-band metadata: it never + # participates in `message` and stays `nil` when no state was in scope. + defexception [:value, :source, :message, :call_stack, :line, :state] @impl true def exception(opts) do @@ -28,7 +32,8 @@ defmodule Lua.VM.AssertionError do source: source, message: message, call_stack: call_stack, - line: line + line: line, + state: Keyword.get(opts, :state) } end diff --git a/lib/lua/vm/executor.ex b/lib/lua/vm/executor.ex index f80963ea..d222c52e 100644 --- a/lib/lua/vm/executor.ex +++ b/lib/lua/vm/executor.ex @@ -156,11 +156,12 @@ defmodule Lua.VM.Executor do end end - def call_function(nil, _args, _state) do + def call_function(nil, _args, state) do raise TypeError, value: "attempt to call a nil value", error_kind: :call_nil, - value_type: nil + value_type: nil, + state: state end def call_function(other, args, state) do @@ -170,7 +171,8 @@ defmodule Lua.VM.Executor do raise TypeError, value: "attempt to call a #{Value.type_name(other)} value", error_kind: :call_non_function, - value_type: value_type(other) + value_type: value_type(other), + state: state {:tref, mt_id} -> mt = Map.fetch!(state.tables, mt_id) @@ -180,7 +182,8 @@ defmodule Lua.VM.Executor do raise TypeError, value: "attempt to call a #{Value.type_name(other)} value", error_kind: :call_non_function, - value_type: value_type(other) + value_type: value_type(other), + state: state call_mm -> call_function(call_mm, [other | args], state) @@ -439,7 +442,8 @@ defmodule Lua.VM.Executor do call_stack: state.call_stack, line: 0, error_kind: :call_nil, - value_type: nil + value_type: nil, + state: state end def dispatcher_call_function({:lua_closure, _, _} = closure, args, state, _proto, _name_hint), @@ -460,7 +464,8 @@ defmodule Lua.VM.Executor do call_stack: state.call_stack, line: 0, error_kind: :call_non_function, - value_type: value_type(other) + value_type: value_type(other), + state: state {:tref, mt_id} -> mt = Map.fetch!(state.tables, mt_id) @@ -473,7 +478,8 @@ defmodule Lua.VM.Executor do call_stack: state.call_stack, line: 0, error_kind: :call_non_function, - value_type: value_type(other) + value_type: value_type(other), + state: state call_mm -> call_function(call_mm, [other | args], state) @@ -1078,7 +1084,8 @@ defmodule Lua.VM.Executor do call_stack: state.call_stack, line: line, error_kind: :call_nil, - value_type: nil + value_type: nil, + state: state other -> case get_metatable(other, state) do @@ -1089,7 +1096,8 @@ defmodule Lua.VM.Executor do call_stack: state.call_stack, line: line, error_kind: :call_non_function, - value_type: value_type(other) + value_type: value_type(other), + state: state {:tref, mt_id} -> mt = Map.fetch!(state.tables, mt_id) @@ -1102,7 +1110,8 @@ defmodule Lua.VM.Executor do call_stack: state.call_stack, line: line, error_kind: :call_non_function, - value_type: value_type(other) + value_type: value_type(other), + state: state call_mm -> args = collect_args(regs, base + 1, total_args) @@ -2142,7 +2151,8 @@ defmodule Lua.VM.Executor do call_stack: state.call_stack, line: line, error_kind: :call_nil, - value_type: nil + value_type: nil, + state: state end defp call_value(other, args, proto, state, line) do @@ -2154,7 +2164,8 @@ defmodule Lua.VM.Executor do call_stack: state.call_stack, line: line, error_kind: :call_non_function, - value_type: value_type(other) + value_type: value_type(other), + state: state {:tref, mt_id} -> mt = Map.fetch!(state.tables, mt_id) @@ -2167,7 +2178,8 @@ defmodule Lua.VM.Executor do call_stack: state.call_stack, line: line, error_kind: :call_non_function, - value_type: value_type(other) + value_type: value_type(other), + state: state call_mm -> call_value(call_mm, [other | args], proto, state, line) diff --git a/lib/lua/vm/runtime_error.ex b/lib/lua/vm/runtime_error.ex index d2ac1362..47b3594c 100644 --- a/lib/lua/vm/runtime_error.ex +++ b/lib/lua/vm/runtime_error.ex @@ -18,7 +18,11 @@ defmodule Lua.VM.RuntimeError do @type t :: %__MODULE__{} - defexception [:value, :source, :message, :call_stack, :line] + # `:state` carries the `Lua.VM.State` as of the raise, so protected calls + # (pcall/xpcall) can keep heap effects made before the error instead of + # rolling back to their entry snapshot. It is out-of-band metadata: it never + # participates in `message` and stays `nil` when no state was in scope. + defexception [:value, :source, :message, :call_stack, :line, :state] @impl true def exception(opts) do @@ -35,7 +39,8 @@ defmodule Lua.VM.RuntimeError do source: source, message: message, call_stack: call_stack, - line: line + line: line, + state: Keyword.get(opts, :state) } end diff --git a/lib/lua/vm/state.ex b/lib/lua/vm/state.ex index a7cee14f..74f416ad 100644 --- a/lib/lua/vm/state.ex +++ b/lib/lua/vm/state.ex @@ -78,8 +78,49 @@ defmodule Lua.VM.State do def check_call_depth!(%__MODULE__{max_call_depth: :infinity}), do: :ok def check_call_depth!(%__MODULE__{call_depth: depth, max_call_depth: max}) when depth < max, do: :ok - def check_call_depth!(%__MODULE__{call_stack: call_stack}) do - raise Lua.VM.RuntimeError, value: "stack overflow", call_stack: call_stack + def check_call_depth!(%__MODULE__{call_stack: call_stack} = state) do + raise Lua.VM.RuntimeError, value: "stack overflow", call_stack: call_stack, state: state + end + + @doc """ + Recovers the state a protected call should continue with after trapping + an error. + + Lua 5.3 §2.3: an error aborts the protected call, but heap effects made + before it — global writes, table mutations, upvalue-cell assignments, + metatable changes — are kept. Only control state unwinds. Accordingly, + heap fields come from `raised` (the state captured at the raise site, + ferried out on the exception's `:state` field) while control fields are + restored from `entry` (the state at protected-call entry): + + | kept from `raised` (heap) | restored from `entry` (control) | + |----------------------------------------|---------------------------------| + | `tables`, `table_next_id` | `call_stack`, `call_depth` | + | `userdata`, `userdata_next_id` | `open_upvalues` | + | `metatables`, `upvalue_cells`, `private` | `multi_return_count` | + + Keeping `upvalue_cells` while restoring `open_upvalues` matches reference + upvalue semantics: cells captured before the protected call keep their + mutated values, while cells opened by the unwound frames become + unreachable garbage. + + When no raise-time state was captured (`raised` is `nil`, e.g. the error + came from outside Lua execution), falls back to `entry` unchanged. + """ + @spec unwind_to(t(), t() | nil) :: t() + def unwind_to(%__MODULE__{} = entry, nil), do: entry + + def unwind_to(%__MODULE__{} = entry, %__MODULE__{} = raised) do + %{ + entry + | tables: raised.tables, + table_next_id: raised.table_next_id, + userdata: raised.userdata, + userdata_next_id: raised.userdata_next_id, + metatables: raised.metatables, + upvalue_cells: raised.upvalue_cells, + private: raised.private + } end @doc """ diff --git a/lib/lua/vm/stdlib.ex b/lib/lua/vm/stdlib.ex index 790c6539..f3eaa7a0 100644 --- a/lib/lua/vm/stdlib.ex +++ b/lib/lua/vm/stdlib.ex @@ -170,14 +170,14 @@ defmodule Lua.VM.Stdlib do # is called outside a Lua execution (or from a context where no line was # set), `current_position/0` returns `{nil, nil}` and the message just # omits the location. - defp lua_error([message | _], _state) do + defp lua_error([message | _], state) do {line, source} = Executor.current_position() - raise RuntimeError, value: message, line: line, source: source + raise RuntimeError, value: message, line: line, source: source, state: state end - defp lua_error([], _state) do + defp lua_error([], state) do {line, source} = Executor.current_position() - raise RuntimeError, value: nil, line: line, source: source + raise RuntimeError, value: nil, line: line, source: source, state: state end # assert(v [, message]) — raises if v is falsy @@ -190,73 +190,77 @@ defmodule Lua.VM.Stdlib do end {line, source} = Executor.current_position() - raise AssertionError, value: message, line: line, source: source + raise AssertionError, value: message, line: line, source: source, state: state else {[value | rest], state} end end - defp lua_assert([], _state) do + defp lua_assert([], state) do {line, source} = Executor.current_position() - raise AssertionError, value: "assertion failed!", line: line, source: source + raise AssertionError, value: "assertion failed!", line: line, source: source, state: state end # pcall(f [, arg1, ...]) — calls function in protected mode - # Returns true, result(s) on success or false, error_message on error + # Returns true, result(s) on success or false, error_message on error. + # The trapped error unwinds control state only: heap effects the callee + # made before raising are kept via the exception's `:state` snapshot + # (Lua 5.3 §2.3) — see `State.unwind_to/2`. defp lua_pcall([func | args], state) do {results, state} = Executor.call_function(func, args, state) {[true | results], state} rescue - e in [RuntimeError, AssertionError, TypeError] -> + e in [RuntimeError, AssertionError, TypeError, ArgumentError] -> error_msg = extract_error_message(e) - {[false, error_msg], state} + {[false, error_msg], State.unwind_to(state, e.state)} e -> # Catch any other error - {[false, Exception.message(e)], state} + {[false, Exception.message(e)], State.unwind_to(state, raised_state(e))} end defp lua_pcall([], state), do: {[false, "bad argument #1 to 'pcall' (value expected)"], state} # xpcall(f, msgh [, arg1, ...]) — calls function with message handler - # Returns true, result(s) on success or false, handler_result on error + # Returns true, result(s) on success or false, handler_result on error. + # Like pcall, heap effects made before the error are kept; the message + # handler runs against that recovered state so it observes them + # (reference Lua invokes the handler before the stack unwinds, with the + # heap intact). defp lua_xpcall([func, handler | args], state) do {results, state} = Executor.call_function(func, args, state) {[true | results], state} rescue - e in [RuntimeError, AssertionError, TypeError] -> - error_msg = extract_error_message(e) - - # Call the error handler - try do - {handler_results, state} = Executor.call_function(handler, [error_msg], state) - {[false | handler_results], state} - rescue - _ -> - # If handler fails, return original error - {[false, error_msg], state} - end + e in [RuntimeError, AssertionError, TypeError, ArgumentError] -> + run_xpcall_handler(handler, extract_error_message(e), State.unwind_to(state, e.state)) e -> # Catch any other error - error_msg = Exception.message(e) - - try do - {handler_results, state} = Executor.call_function(handler, [error_msg], state) - {[false | handler_results], state} - rescue - _ -> - {[false, error_msg], state} - end + run_xpcall_handler(handler, Exception.message(e), State.unwind_to(state, raised_state(e))) end defp lua_xpcall(_, state), do: {[false, "bad argument to 'xpcall'"], state} + # If the handler itself fails, return the original error — keeping any + # heap effects the handler made before its own error. + defp run_xpcall_handler(handler, error_msg, state) do + {handler_results, state} = Executor.call_function(handler, [error_msg], state) + {[false | handler_results], state} + rescue + e -> + {[false, error_msg], State.unwind_to(state, raised_state(e))} + end + # Extract error message from exception defp extract_error_message(%{value: value}) when is_binary(value), do: value defp extract_error_message(%{value: value}) when not is_nil(value), do: Value.to_string(value) defp extract_error_message(e), do: Exception.message(e) + # Raise-time state ferried out on VM exceptions; `nil` for anything else + # (plain Elixir exceptions carry no Lua state). + defp raised_state(%{state: %State{} = state}), do: state + defp raised_state(_), do: nil + # rawget(table, key) — get without metamethods defp lua_rawget([{:tref, id}, key | _], state) do table = Map.fetch!(state.tables, id) diff --git a/lib/lua/vm/type_error.ex b/lib/lua/vm/type_error.ex index 81b8a080..25324cd2 100644 --- a/lib/lua/vm/type_error.ex +++ b/lib/lua/vm/type_error.ex @@ -16,7 +16,11 @@ defmodule Lua.VM.TypeError do @type t :: %__MODULE__{} - defexception [:value, :source, :message, :call_stack, :line, :error_kind, :value_type] + # `:state` carries the `Lua.VM.State` as of the raise, so protected calls + # (pcall/xpcall) can keep heap effects made before the error instead of + # rolling back to their entry snapshot. It is out-of-band metadata: it never + # participates in `message` and stays `nil` when no state was in scope. + defexception [:value, :source, :message, :call_stack, :line, :error_kind, :value_type, :state] @impl true def exception(opts) do @@ -40,7 +44,8 @@ defmodule Lua.VM.TypeError do call_stack: call_stack, line: line, error_kind: error_kind, - value_type: value_type + value_type: value_type, + state: Keyword.get(opts, :state) } end From a1c6594d3209dc2acc7986bd9bfbb4db33c147b1 Mon Sep 17 00:00:00 2001 From: Dave Lucia Date: Thu, 4 Jun 2026 08:30:10 -0700 Subject: [PATCH 03/12] fix(vm): annotate escaping VM exceptions at the native-call boundary Both native invocation points (Executor.call_function and the interpreter's inline native path) reraise VM exceptions with the call's entry state when none was attached deeper, covering every stdlib bad-argument raise without threading state through each check. Innermost annotation wins. --- lib/lua/vm/executor.ex | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/lib/lua/vm/executor.ex b/lib/lua/vm/executor.ex index d222c52e..34fef093 100644 --- a/lib/lua/vm/executor.ex +++ b/lib/lua/vm/executor.ex @@ -103,6 +103,17 @@ defmodule Lua.VM.Executor do defp restore_position(@unset), do: Process.delete(@position_key) defp restore_position(pos), do: Process.put(@position_key, pos) + # Ferries the freshest state at an execution boundary out on VM + # exceptions, so protected calls (pcall/xpcall) can keep heap effects + # made before the error — see `Lua.VM.State.unwind_to/2`. + # + # Only fills the `:state` field when it's empty: an exception annotated + # deeper in the call tree already carries a fresher snapshot than any + # enclosing boundary's. Non-VM exceptions (no `:state` key) pass through + # untouched. Runs only on the error path — the happy path never pays. + defp annotate_state(%{state: nil} = e, %State{} = state), do: %{e | state: state} + defp annotate_state(e, _state), do: e + @doc """ Calls a Lua function value with the given arguments. @@ -146,6 +157,11 @@ defmodule Lua.VM.Executor do Dispatcher.execute(callee_proto, args, callee_upvalues, state) end + # The rescue annotates escaping VM exceptions with this call's entry + # state (the freshest state any stdlib raise site could have seen), so + # protected calls can keep heap effects made before the error without + # every bad-argument check threading state into its raise. Innermost + # annotation wins — see `annotate_state/2`. def call_function({:native_func, fun}, args, state) do case fun.(args, state) do {results, %State{} = new_state} when is_list(results) -> @@ -154,6 +170,8 @@ defmodule Lua.VM.Executor do {results, %State{} = new_state} -> {List.wrap(results), new_state} end + rescue + e -> reraise annotate_state(e, state), __STACKTRACE__ end def call_function(nil, _args, state) do @@ -1071,6 +1089,8 @@ defmodule Lua.VM.Executor do raise InternalError, value: "native function returned invalid result: #{inspect(other)}, expected {results, state}" end + rescue + e -> reraise annotate_state(e, state), __STACKTRACE__ after restore_position(prev_pos) end From f2c2dedfdfa578c8e737a5082418be25ffb688fd Mon Sep 17 00:00:00 2001 From: Dave Lucia Date: Thu, 4 Jun 2026 08:38:04 -0700 Subject: [PATCH 04/12] fix(vm): thread state into in-frame raise helpers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Arithmetic, comparison, concat, index, bitwise, length, and numeric-for coercion helpers raise from pure code where the freshest state lived only in the executor loop binding. They now take the caller's threaded state and attach it to the exception, so protected calls keep heap effects made earlier in the same frame (e.g. x = 2; return nil + 1 under pcall). One extra already-bound argument per helper — raise opts are only built on the error path. --- lib/lua/vm/dispatcher.ex | 5 +- lib/lua/vm/executor.ex | 251 +++++++++++++++++++++------------------ 2 files changed, 136 insertions(+), 120 deletions(-) diff --git a/lib/lua/vm/dispatcher.ex b/lib/lua/vm/dispatcher.ex index de8d7e81..a49b7ab6 100644 --- a/lib/lua/vm/dispatcher.ex +++ b/lib/lua/vm/dispatcher.ex @@ -842,7 +842,8 @@ defmodule Lua.VM.Dispatcher do Executor.dispatcher_coerce_numeric_for_controls( :erlang.element(base + 1, regs), :erlang.element(base + 2, regs), - :erlang.element(base + 3, regs) + :erlang.element(base + 3, regs), + state ) regs = :erlang.setelement(base + 1, regs, counter) @@ -1124,7 +1125,7 @@ defmodule Lua.VM.Dispatcher do if is_binary(left) and is_binary(right) do if byte_size(left) + byte_size(right) > state.max_string_bytes do - raise RuntimeError, value: "resulting string too large" + raise RuntimeError, value: "resulting string too large", state: state end regs = :erlang.setelement(dest + 1, regs, left <> right) diff --git a/lib/lua/vm/executor.ex b/lib/lua/vm/executor.ex index 34fef093..d72e3886 100644 --- a/lib/lua/vm/executor.ex +++ b/lib/lua/vm/executor.ex @@ -227,56 +227,56 @@ defmodule Lua.VM.Executor do {term(), State.t()} def dispatcher_binop(:add, a, b, state, proto, hint_a, hint_b) do try_binary_metamethod("__add", a, b, state, fn -> - safe_add(a, b, 0, proto.source, hint_a, hint_b) + safe_add(a, b, 0, proto.source, hint_a, hint_b, state) end) end def dispatcher_binop(:subtract, a, b, state, proto, hint_a, hint_b) do try_binary_metamethod("__sub", a, b, state, fn -> - safe_subtract(a, b, 0, proto.source, hint_a, hint_b) + safe_subtract(a, b, 0, proto.source, hint_a, hint_b, state) end) end def dispatcher_binop(:multiply, a, b, state, proto, hint_a, hint_b) do try_binary_metamethod("__mul", a, b, state, fn -> - safe_multiply(a, b, 0, proto.source, hint_a, hint_b) + safe_multiply(a, b, 0, proto.source, hint_a, hint_b, state) end) end def dispatcher_binop(:divide, a, b, state, proto, hint_a, hint_b) do try_binary_metamethod("__div", a, b, state, fn -> - safe_divide(a, b, 0, proto.source, hint_a, hint_b) + safe_divide(a, b, 0, proto.source, hint_a, hint_b, state) end) end def dispatcher_binop(:floor_divide, a, b, state, proto, hint_a, hint_b) do try_binary_metamethod("__idiv", a, b, state, fn -> - safe_floor_divide(a, b, 0, proto.source, hint_a, hint_b) + safe_floor_divide(a, b, 0, proto.source, hint_a, hint_b, state) end) end def dispatcher_binop(:modulo, a, b, state, proto, hint_a, hint_b) do try_binary_metamethod("__mod", a, b, state, fn -> - safe_modulo(a, b, 0, proto.source, hint_a, hint_b) + safe_modulo(a, b, 0, proto.source, hint_a, hint_b, state) end) end def dispatcher_binop(:power, a, b, state, proto, hint_a, hint_b) do try_binary_metamethod("__pow", a, b, state, fn -> - safe_power(a, b, 0, proto.source, hint_a, hint_b) + safe_power(a, b, 0, proto.source, hint_a, hint_b, state) end) end @doc false @spec dispatcher_unop(atom(), term(), State.t(), term(), term()) :: {term(), State.t()} def dispatcher_unop(:negate, val, state, proto, hint) do - try_unary_metamethod("__unm", val, state, fn -> safe_negate(val, 0, proto.source, hint) end) + try_unary_metamethod("__unm", val, state, fn -> safe_negate(val, 0, proto.source, hint, state) end) end @doc false @spec dispatcher_cmp(atom(), term(), term(), State.t(), term()) :: {term(), State.t()} def dispatcher_cmp(:less_than, a, b, state, proto) do - try_binary_metamethod("__lt", a, b, state, fn -> safe_compare_lt(a, b, 0, proto.source) end) + try_binary_metamethod("__lt", a, b, state, fn -> safe_compare_lt(a, b, 0, proto.source, state) end) end def dispatcher_cmp(:less_equal, a, b, state, proto) do @@ -285,7 +285,7 @@ defmodule Lua.VM.Executor do def dispatcher_cmp(:greater_than, a, b, state, proto) do # Lua 5.3 §3.4.4: a > b dispatches __lt with swapped operands. - try_binary_metamethod("__lt", b, a, state, fn -> safe_compare_lt(b, a, 0, proto.source) end) + try_binary_metamethod("__lt", b, a, state, fn -> safe_compare_lt(b, a, 0, proto.source, state) end) end def dispatcher_cmp(:greater_equal, a, b, state, proto) do @@ -350,8 +350,8 @@ defmodule Lua.VM.Executor do table_newindex(tref, key, value, state) end - def dispatcher_set_table(value, _key, _value, _state, proto, name_hint) do - raise_index_type_error(value, 0, proto.source, name_hint) + def dispatcher_set_table(value, _key, _value, state, proto, name_hint) do + raise_index_type_error(value, 0, proto.source, name_hint, state) end @doc false @@ -361,8 +361,8 @@ defmodule Lua.VM.Executor do table_newindex(tref, name, value, state) end - def dispatcher_set_field(value, _name, _value, _state, proto, name_hint) do - raise_index_type_error(value, 0, proto.source, name_hint) + def dispatcher_set_field(value, _name, _value, state, proto, name_hint) do + raise_index_type_error(value, 0, proto.source, name_hint, state) end # The `_proto` parameter is unused today because `try_unary_metamethod` @@ -391,10 +391,10 @@ defmodule Lua.VM.Executor do end @doc false - @spec dispatcher_coerce_numeric_for_controls(term(), term(), term()) :: + @spec dispatcher_coerce_numeric_for_controls(term(), term(), term(), State.t()) :: {number(), number(), number()} - def dispatcher_coerce_numeric_for_controls(init, limit, step) do - coerce_numeric_for_controls(init, limit, step) + def dispatcher_coerce_numeric_for_controls(init, limit, step, state) do + coerce_numeric_for_controls(init, limit, step, state) end @doc false @@ -428,7 +428,7 @@ defmodule Lua.VM.Executor do end # `:concatenate` slow path. Mirrors the interpreter's three-way fallback: - # both-binary → `<>`, both binary-or-number → `concat_coerce/3 . <>`, + # both-binary → `<>`, both binary-or-number → `concat_coerce/4 . <>`, # otherwise `__concat` metamethod via `try_binary_metamethod/5`. # The dispatcher inlines the binary-binary fast path itself, but defers # the metatable case and the coerce path here so the type-error wording @@ -440,7 +440,7 @@ defmodule Lua.VM.Executor do src = proto.source try_binary_metamethod("__concat", left, right, state, fn -> - concat_checked(concat_coerce(left, 0, src), concat_coerce(right, 0, src), state.max_string_bytes) + concat_checked(concat_coerce(left, 0, src, state), concat_coerce(right, 0, src, state), state) end) end @@ -860,7 +860,7 @@ defmodule Lua.VM.Executor do # loop start and write the canonical numbers back into the control # registers so subsequent iterations work on numbers. {counter, limit, step} = - coerce_numeric_for_controls(elem(regs, base), elem(regs, base + 1), elem(regs, base + 2)) + coerce_numeric_for_controls(elem(regs, base), elem(regs, base + 1), elem(regs, base + 2), state) regs = regs @@ -1262,7 +1262,7 @@ defmodule Lua.VM.Executor do {result, new_state} = try_binary_metamethod("__add", val_a, val_b, state, fn -> - safe_add(val_a, val_b, line, src, hint_a, hint_b) + safe_add(val_a, val_b, line, src, hint_a, hint_b, state) end) regs = put_elem(regs, dest, result) @@ -1289,7 +1289,7 @@ defmodule Lua.VM.Executor do {result, new_state} = try_binary_metamethod("__sub", val_a, val_b, state, fn -> - safe_subtract(val_a, val_b, line, src, hint_a, hint_b) + safe_subtract(val_a, val_b, line, src, hint_a, hint_b, state) end) regs = put_elem(regs, dest, result) @@ -1316,7 +1316,7 @@ defmodule Lua.VM.Executor do {result, new_state} = try_binary_metamethod("__mul", val_a, val_b, state, fn -> - safe_multiply(val_a, val_b, line, src, hint_a, hint_b) + safe_multiply(val_a, val_b, line, src, hint_a, hint_b, state) end) regs = put_elem(regs, dest, result) @@ -1331,7 +1331,7 @@ defmodule Lua.VM.Executor do {result, new_state} = try_binary_metamethod("__div", val_a, val_b, state, fn -> - safe_divide(val_a, val_b, line, src, hint_a, hint_b) + safe_divide(val_a, val_b, line, src, hint_a, hint_b, state) end) regs = put_elem(regs, dest, result) @@ -1345,7 +1345,7 @@ defmodule Lua.VM.Executor do {result, new_state} = try_binary_metamethod("__idiv", val_a, val_b, state, fn -> - safe_floor_divide(val_a, val_b, line, src, hint_a, hint_b) + safe_floor_divide(val_a, val_b, line, src, hint_a, hint_b, state) end) regs = put_elem(regs, dest, result) @@ -1359,7 +1359,7 @@ defmodule Lua.VM.Executor do {result, new_state} = try_binary_metamethod("__mod", val_a, val_b, state, fn -> - safe_modulo(val_a, val_b, line, src, hint_a, hint_b) + safe_modulo(val_a, val_b, line, src, hint_a, hint_b, state) end) regs = put_elem(regs, dest, result) @@ -1373,7 +1373,7 @@ defmodule Lua.VM.Executor do {result, new_state} = try_binary_metamethod("__pow", val_a, val_b, state, fn -> - safe_power(val_a, val_b, line, src, hint_a, hint_b) + safe_power(val_a, val_b, line, src, hint_a, hint_b, state) end) regs = put_elem(regs, dest, result) @@ -1393,12 +1393,12 @@ defmodule Lua.VM.Executor do # also concatenate without metamethods. cond do is_binary(left) and is_binary(right) -> - regs = put_elem(regs, dest, concat_checked(left, right, state.max_string_bytes)) + regs = put_elem(regs, dest, concat_checked(left, right, state)) do_execute(rest, regs, upvalues, proto, state, cont, frames, line) (is_binary(left) or is_number(left)) and (is_binary(right) or is_number(right)) -> src = proto.source - result = concat_checked(concat_coerce(left, line, src), concat_coerce(right, line, src), state.max_string_bytes) + result = concat_checked(concat_coerce(left, line, src, state), concat_coerce(right, line, src, state), state) regs = put_elem(regs, dest, result) do_execute(rest, regs, upvalues, proto, state, cont, frames, line) @@ -1407,7 +1407,7 @@ defmodule Lua.VM.Executor do {result, new_state} = try_binary_metamethod("__concat", left, right, state, fn -> - concat_checked(concat_coerce(left, line, src), concat_coerce(right, line, src), state.max_string_bytes) + concat_checked(concat_coerce(left, line, src, state), concat_coerce(right, line, src, state), state) end) regs = put_elem(regs, dest, result) @@ -1425,7 +1425,7 @@ defmodule Lua.VM.Executor do {result, new_state} = try_binary_metamethod("__band", val_a, val_b, state, fn -> Numeric.to_signed_int64( - Bitwise.band(to_integer!(val_a, line, src, hint_a), to_integer!(val_b, line, src, hint_b)) + Bitwise.band(to_integer!(val_a, line, src, hint_a, state), to_integer!(val_b, line, src, hint_b, state)) ) end) @@ -1440,7 +1440,9 @@ defmodule Lua.VM.Executor do {result, new_state} = try_binary_metamethod("__bor", val_a, val_b, state, fn -> - Numeric.to_signed_int64(Bitwise.bor(to_integer!(val_a, line, src, hint_a), to_integer!(val_b, line, src, hint_b))) + Numeric.to_signed_int64( + Bitwise.bor(to_integer!(val_a, line, src, hint_a, state), to_integer!(val_b, line, src, hint_b, state)) + ) end) regs = put_elem(regs, dest, result) @@ -1455,7 +1457,7 @@ defmodule Lua.VM.Executor do {result, new_state} = try_binary_metamethod("__bxor", val_a, val_b, state, fn -> Numeric.to_signed_int64( - Bitwise.bxor(to_integer!(val_a, line, src, hint_a), to_integer!(val_b, line, src, hint_b)) + Bitwise.bxor(to_integer!(val_a, line, src, hint_a, state), to_integer!(val_b, line, src, hint_b, state)) ) end) @@ -1470,7 +1472,7 @@ defmodule Lua.VM.Executor do {result, new_state} = try_binary_metamethod("__shl", val_a, val_b, state, fn -> - lua_shift_left(to_integer!(val_a, line, src, hint_a), to_integer!(val_b, line, src, hint_b)) + lua_shift_left(to_integer!(val_a, line, src, hint_a, state), to_integer!(val_b, line, src, hint_b, state)) end) regs = put_elem(regs, dest, result) @@ -1484,7 +1486,7 @@ defmodule Lua.VM.Executor do {result, new_state} = try_binary_metamethod("__shr", val_a, val_b, state, fn -> - lua_shift_right(to_integer!(val_a, line, src, hint_a), to_integer!(val_b, line, src, hint_b)) + lua_shift_right(to_integer!(val_a, line, src, hint_a, state), to_integer!(val_b, line, src, hint_b, state)) end) regs = put_elem(regs, dest, result) @@ -1497,7 +1499,7 @@ defmodule Lua.VM.Executor do {result, new_state} = try_unary_metamethod("__bnot", val, state, fn -> - Numeric.to_signed_int64(Bitwise.bnot(to_integer!(val, line, src, hint))) + Numeric.to_signed_int64(Bitwise.bnot(to_integer!(val, line, src, hint, state))) end) regs = put_elem(regs, dest, result) @@ -1548,7 +1550,7 @@ defmodule Lua.VM.Executor do src = proto.source {result, new_state} = - try_binary_metamethod("__lt", val_a, val_b, state, fn -> safe_compare_lt(val_a, val_b, line, src) end) + try_binary_metamethod("__lt", val_a, val_b, state, fn -> safe_compare_lt(val_a, val_b, line, src, state) end) regs = put_elem(regs, dest, result) do_execute(rest, regs, upvalues, proto, new_state, cont, frames, line) @@ -1594,7 +1596,7 @@ defmodule Lua.VM.Executor do # Lua 5.3 §3.4.4: a > b is translated to b < a, which dispatches __lt. {result, new_state} = - try_binary_metamethod("__lt", val_b, val_a, state, fn -> safe_compare_lt(val_b, val_a, line, src) end) + try_binary_metamethod("__lt", val_b, val_a, state, fn -> safe_compare_lt(val_b, val_a, line, src, state) end) regs = put_elem(regs, dest, result) do_execute(rest, regs, upvalues, proto, new_state, cont, frames, line) @@ -1650,7 +1652,7 @@ defmodule Lua.VM.Executor do defp do_execute([{:negate, dest, source, hint} | rest], regs, upvalues, proto, state, cont, frames, line) do val = elem(regs, source) src = proto.source - {result, new_state} = try_unary_metamethod("__unm", val, state, fn -> safe_negate(val, line, src, hint) end) + {result, new_state} = try_unary_metamethod("__unm", val, state, fn -> safe_negate(val, line, src, hint, state) end) regs = put_elem(regs, dest, result) do_execute(rest, regs, upvalues, proto, new_state, cont, frames, line) end @@ -1783,7 +1785,7 @@ defmodule Lua.VM.Executor do do_execute(rest, regs, upvalues, proto, state, cont, frames, line) _ -> - raise_index_type_error(table_val, line, proto.source, name_hint) + raise_index_type_error(table_val, line, proto.source, name_hint, state) end end @@ -1856,7 +1858,7 @@ defmodule Lua.VM.Executor do do_execute(rest, regs, upvalues, proto, state, cont, frames, line) _ -> - raise_index_type_error(table_val, line, proto.source, name_hint) + raise_index_type_error(table_val, line, proto.source, name_hint, state) end end @@ -2209,17 +2211,18 @@ defmodule Lua.VM.Executor do # ── Coerce a value to string for concatenation ───────────────────────────── - defp concat_coerce(value, _line, _source) when is_binary(value), do: value - defp concat_coerce(value, _line, _source) when is_integer(value), do: Integer.to_string(value) - defp concat_coerce(value, _line, _source) when is_float(value), do: Value.to_string(value) + defp concat_coerce(value, _line, _source, _state) when is_binary(value), do: value + defp concat_coerce(value, _line, _source, _state) when is_integer(value), do: Integer.to_string(value) + defp concat_coerce(value, _line, _source, _state) when is_float(value), do: Value.to_string(value) - defp concat_coerce(value, line, source) do + defp concat_coerce(value, line, source, state) do raise TypeError, value: "attempt to concatenate a #{Value.type_name(value)} value", line: line, source: source, error_kind: :concatenate_type_error, - value_type: value_type(value) + value_type: value_type(value), + state: state end # `..` builds a new binary on every step. A doubling loop (`s = s .. s`) @@ -2229,14 +2232,15 @@ defmodule Lua.VM.Executor do # stdlib checks, so the loop fails with a catchable error long before it # threatens the host. `byte_size/1` is O(1) and the ceiling is a struct # field read (`state.max_string_bytes`, settable via `Lua.new/1`), so - # this stays cheap on the hot path. + # this stays cheap on the hot path. The state is threaded through so the + # over-limit raise carries the raise-time snapshot for protected unwinds. @compile {:inline, concat_checked: 3} - defp concat_checked(left, right, max) when byte_size(left) + byte_size(right) <= max do + defp concat_checked(left, right, %{max_string_bytes: max}) when byte_size(left) + byte_size(right) <= max do left <> right end - defp concat_checked(_left, _right, _max) do - raise RuntimeError, value: "resulting string too large" + defp concat_checked(_left, _right, state) do + raise RuntimeError, value: "resulting string too large", state: state end # ── Metamethod support ───────────────────────────────────────────────────── @@ -2261,14 +2265,14 @@ defmodule Lua.VM.Executor do defp index_value(value, key, state, line, source, name_hint) do case get_metatable(value, state) do nil -> - raise_index_type_error(value, line, source, name_hint) + raise_index_type_error(value, line, source, name_hint, state) {:tref, mt_id} -> mt = Map.fetch!(state.tables, mt_id) case Map.get(mt.data, "__index") do nil -> - raise_index_type_error(value, line, source, name_hint) + raise_index_type_error(value, line, source, name_hint, state) {:tref, _} = idx_tbl -> table_index(idx_tbl, key, state) @@ -2280,13 +2284,14 @@ defmodule Lua.VM.Executor do end end - defp raise_index_type_error(value, line, source, name_hint) do + defp raise_index_type_error(value, line, source, name_hint, state) do raise TypeError, value: "attempt to index a #{Value.type_name(value)} value" <> format_target_hint(name_hint), line: line, source: source, error_kind: :index_non_table, - value_type: value_type(value) + value_type: value_type(value), + state: state end # Formats a `name_hint` tagged-tuple (or `nil`) as the @@ -2342,7 +2347,7 @@ defmodule Lua.VM.Executor do defp table_index({:tref, id}, key, state, depth) do if depth >= @metamethod_chain_limit do - raise RuntimeError, value: "'__index' chain too long; possible loop" + raise RuntimeError, value: "'__index' chain too long; possible loop", state: state end table = Map.fetch!(state.tables, id) @@ -2390,7 +2395,7 @@ defmodule Lua.VM.Executor do defp table_newindex({:tref, id}, key, value, state, depth) do if depth >= @metamethod_chain_limit do - raise RuntimeError, value: "'__newindex' chain too long; possible loop" + raise RuntimeError, value: "'__newindex' chain too long; possible loop", state: state end table = Map.fetch!(state.tables, id) @@ -2459,14 +2464,16 @@ defmodule Lua.VM.Executor do raise TypeError, value: "object length is not an integer", error_kind: :length_not_integer, - value_type: :number + value_type: :number, + state: state end _ -> raise TypeError, value: "object length is not an integer", error_kind: :length_not_integer, - value_type: value_type(raw) + value_type: value_type(raw), + state: state end end @@ -2489,17 +2496,17 @@ defmodule Lua.VM.Executor do nil -> case lookup_metamethod(b, "__lt", state) || lookup_metamethod(a, "__lt", state) do nil -> - {safe_compare_le(a, b, line, source), state} + {safe_compare_le(a, b, line, source, state), state} lt -> {lt_result, new_state} = - invoke_metamethod(lt, [b, a], state, fn -> safe_compare_lt(b, a, line, source) end) + invoke_metamethod(lt, [b, a], state, fn -> safe_compare_lt(b, a, line, source, state) end) {not Value.truthy?(lt_result), new_state} end le -> - invoke_metamethod(le, [a, b], state, fn -> safe_compare_le(a, b, line, source) end) + invoke_metamethod(le, [a, b], state, fn -> safe_compare_le(a, b, line, source, state) end) end end @@ -2572,21 +2579,21 @@ defmodule Lua.VM.Executor do # passed verbatim from the executor's threaded `line` and `proto.source`, # so they cost nothing on the success path beyond two register reads. - defp safe_add(a, b, line, source, hint_a, hint_b) do - na = number_or_arith_raise!(a, line, source, hint_a) - nb = number_or_arith_raise!(b, line, source, hint_b) + defp safe_add(a, b, line, source, hint_a, hint_b, state) do + na = number_or_arith_raise!(a, line, source, hint_a, state) + nb = number_or_arith_raise!(b, line, source, hint_b, state) narrow_if_integer(na + nb) end - defp safe_subtract(a, b, line, source, hint_a, hint_b) do - na = number_or_arith_raise!(a, line, source, hint_a) - nb = number_or_arith_raise!(b, line, source, hint_b) + defp safe_subtract(a, b, line, source, hint_a, hint_b, state) do + na = number_or_arith_raise!(a, line, source, hint_a, state) + nb = number_or_arith_raise!(b, line, source, hint_b, state) narrow_if_integer(na - nb) end - defp safe_multiply(a, b, line, source, hint_a, hint_b) do - na = number_or_arith_raise!(a, line, source, hint_a) - nb = number_or_arith_raise!(b, line, source, hint_b) + defp safe_multiply(a, b, line, source, hint_a, hint_b, state) do + na = number_or_arith_raise!(a, line, source, hint_a, state) + nb = number_or_arith_raise!(b, line, source, hint_b, state) narrow_if_integer(na * nb) end @@ -2595,14 +2602,14 @@ defmodule Lua.VM.Executor do # to the originating variable / field (PUC-Lua mirrors this via debug # info; we resolve at compile time and thread the hint through the # instruction tuple). - defp number_or_arith_raise!(v, line, source, hint) do + defp number_or_arith_raise!(v, line, source, hint, state) do case to_number(v) do {:ok, n} -> n - {:error, val} -> raise_arith_type_error(val, line, source, hint) + {:error, val} -> raise_arith_type_error(val, line, source, hint, state) end end - defp raise_arith_type_error(val, line, source, hint) do + defp raise_arith_type_error(val, line, source, hint, state) do raise TypeError, value: "attempt to perform arithmetic on a #{Value.type_name(val)} value" <> @@ -2610,7 +2617,8 @@ defmodule Lua.VM.Executor do line: line, source: source, error_kind: :arithmetic_on_non_number, - value_type: value_type(val) + value_type: value_type(val), + state: state end # Lua 5.3 §3.4.1: `/` is always float division and never raises. Division @@ -2627,9 +2635,9 @@ defmodule Lua.VM.Executor do # Arithmetic on `:nan` will surface a TypeError via `to_number/1`; that's # an accepted divergence from real IEEE 754, since the suite tests we # care about don't propagate NaN through further arithmetic. - defp safe_divide(a, b, line, source, hint_a, hint_b) do - na = number_or_arith_raise!(a, line, source, hint_a) - nb = number_or_arith_raise!(b, line, source, hint_b) + defp safe_divide(a, b, line, source, hint_a, hint_b, state) do + na = number_or_arith_raise!(a, line, source, hint_a, state) + nb = number_or_arith_raise!(b, line, source, hint_b, state) if nb == 0 or nb == 0.0 do cond do @@ -2654,13 +2662,13 @@ defmodule Lua.VM.Executor do # Only an integer `//` integer with a zero divisor raises — that's correct # per spec, since `//` between two integers is integer floor division. # PUC-Lua reports this as "attempt to divide by zero". - defp safe_floor_divide(a, b, line, source, hint_a, hint_b) do - na = number_or_arith_raise!(a, line, source, hint_a) - nb = number_or_arith_raise!(b, line, source, hint_b) + defp safe_floor_divide(a, b, line, source, hint_a, hint_b, state) do + na = number_or_arith_raise!(a, line, source, hint_a, state) + nb = number_or_arith_raise!(b, line, source, hint_b, state) cond do is_integer(na) and is_integer(nb) and nb == 0 -> - raise RuntimeError, value: "attempt to divide by zero", line: line, source: source + raise RuntimeError, value: "attempt to divide by zero", line: line, source: source, state: state is_integer(na) and is_integer(nb) -> Numeric.to_signed_int64(lua_idiv(na, nb)) @@ -2681,13 +2689,13 @@ defmodule Lua.VM.Executor do # either operand is a float, `a/0.0` is inf or nan and `inf * 0.0 = nan`, # so the result is always `:nan` regardless of `a`. Only an integer `%` # integer with a zero divisor raises; PUC-Lua reports it as `'n%0'`. - defp safe_modulo(a, b, line, source, hint_a, hint_b) do - na = number_or_arith_raise!(a, line, source, hint_a) - nb = number_or_arith_raise!(b, line, source, hint_b) + defp safe_modulo(a, b, line, source, hint_a, hint_b, state) do + na = number_or_arith_raise!(a, line, source, hint_a, state) + nb = number_or_arith_raise!(b, line, source, hint_b, state) cond do is_integer(na) and is_integer(nb) and nb == 0 -> - raise RuntimeError, value: "attempt to perform 'n%0'", line: line, source: source + raise RuntimeError, value: "attempt to perform 'n%0'", line: line, source: source, state: state is_integer(na) and is_integer(nb) -> Numeric.to_signed_int64(na - lua_idiv(na, nb) * nb) @@ -2706,9 +2714,9 @@ defmodule Lua.VM.Executor do if r != 0 and Bitwise.bxor(r, b) < 0, do: q - 1, else: q end - defp safe_power(a, b, line, source, hint_a, hint_b) do - na = number_or_arith_raise!(a, line, source, hint_a) - nb = number_or_arith_raise!(b, line, source, hint_b) + defp safe_power(a, b, line, source, hint_a, hint_b, state) do + na = number_or_arith_raise!(a, line, source, hint_a, state) + nb = number_or_arith_raise!(b, line, source, hint_b, state) pow_ieee(na, nb) end @@ -2723,13 +2731,13 @@ defmodule Lua.VM.Executor do ArithmeticError -> :nan end - defp safe_negate(a, line, source, hint) do + defp safe_negate(a, line, source, hint, state) do case to_number(a) do {:ok, na} -> narrow_if_integer(-na) {:error, val} -> - raise_arith_type_error(val, line, source, hint) + raise_arith_type_error(val, line, source, hint, state) end end @@ -2751,10 +2759,10 @@ defmodule Lua.VM.Executor do # ── Type-safe comparison ─────────────────────────────────────────────────── # IEEE 754 §5.11: any ordered comparison involving NaN is false. - defp safe_compare_lt(:nan, _, _, _), do: false - defp safe_compare_lt(_, :nan, _, _), do: false + defp safe_compare_lt(:nan, _, _, _, _state), do: false + defp safe_compare_lt(_, :nan, _, _, _state), do: false - defp safe_compare_lt(a, b, line, source) do + defp safe_compare_lt(a, b, line, source, state) do cond do is_number(a) and is_number(b) -> a < b @@ -2763,14 +2771,14 @@ defmodule Lua.VM.Executor do a < b true -> - raise_compare_type_error(a, b, line, source) + raise_compare_type_error(a, b, line, source, state) end end - defp safe_compare_le(:nan, _, _, _), do: false - defp safe_compare_le(_, :nan, _, _), do: false + defp safe_compare_le(:nan, _, _, _, _state), do: false + defp safe_compare_le(_, :nan, _, _, _state), do: false - defp safe_compare_le(a, b, line, source) do + defp safe_compare_le(a, b, line, source, state) do cond do is_number(a) and is_number(b) -> a <= b @@ -2779,17 +2787,18 @@ defmodule Lua.VM.Executor do a <= b true -> - raise_compare_type_error(a, b, line, source) + raise_compare_type_error(a, b, line, source, state) end end - defp raise_compare_type_error(a, b, line, source) do + defp raise_compare_type_error(a, b, line, source, state) do raise TypeError, value: "attempt to compare #{Value.type_name(a)} with #{Value.type_name(b)}", line: line, source: source, error_kind: :compare_incompatible_types, - value_type: value_type(a) + value_type: value_type(a), + state: state end # ── Number coercion ──────────────────────────────────────────────────────── @@ -2812,10 +2821,10 @@ defmodule Lua.VM.Executor do # init and step are integers, the loop runs with integers; otherwise, # init is promoted to float (limit stays as whatever number it parsed # to — counter/limit comparison works numerically across int/float). - defp coerce_numeric_for_controls(init, limit, step) do - init_n = coerce_for_value(init, "'for' initial value must be a number") - limit_n = coerce_for_value(limit, "'for' limit must be a number") - step_n = coerce_for_value(step, "'for' step must be a number") + defp coerce_numeric_for_controls(init, limit, step, state) do + init_n = coerce_for_value(init, "'for' initial value must be a number", state) + limit_n = coerce_for_value(limit, "'for' limit must be a number", state) + step_n = coerce_for_value(step, "'for' step must be a number", state) if is_float(init_n) or is_float(step_n) do {init_n * 1.0, limit_n, step_n * 1.0} @@ -2824,32 +2833,35 @@ defmodule Lua.VM.Executor do end end - defp coerce_for_value(v, _msg) when is_number(v), do: v + defp coerce_for_value(v, _msg, _state) when is_number(v), do: v - defp coerce_for_value(v, msg) when is_binary(v) do + defp coerce_for_value(v, msg, state) when is_binary(v) do case Value.parse_number(v) do nil -> raise TypeError, value: msg, error_kind: :for_loop_non_number, - value_type: :string + value_type: :string, + state: state n -> n end end - defp coerce_for_value(v, msg) do + defp coerce_for_value(v, msg, state) do raise TypeError, value: msg, error_kind: :for_loop_non_number, - value_type: value_type(v) + value_type: value_type(v), + state: state end - defp to_integer!(v, _line, _source, _hint) when is_integer(v), do: v - defp to_integer!(v, line, source, hint) when is_float(v), do: float_to_integer!(v, line, source, hint) + defp to_integer!(v, _line, _source, _hint, _state) when is_integer(v), do: v - defp to_integer!(v, line, source, hint) when is_binary(v) do + defp to_integer!(v, line, source, hint, state) when is_float(v), do: float_to_integer!(v, line, source, hint, state) + + defp to_integer!(v, line, source, hint, state) when is_binary(v) do case Value.parse_number(v) do nil -> raise TypeError, @@ -2859,17 +2871,18 @@ defmodule Lua.VM.Executor do line: line, source: source, error_kind: :bitwise_on_non_integer, - value_type: :string + value_type: :string, + state: state n when is_integer(n) -> n n when is_float(n) -> - float_to_integer!(n, line, source, hint) + float_to_integer!(n, line, source, hint, state) end end - defp to_integer!(v, line, source, hint) do + defp to_integer!(v, line, source, hint, state) do raise TypeError, value: "attempt to perform bitwise operation on a #{Value.type_name(v)} value" <> @@ -2877,12 +2890,13 @@ defmodule Lua.VM.Executor do line: line, source: source, error_kind: :bitwise_on_non_integer, - value_type: value_type(v) + value_type: value_type(v), + state: state end # Per Lua 5.3 §3.4.3: a float converts to integer for bitwise ops only if # it represents an integer exactly and fits in the signed 64-bit range. - defp float_to_integer!(f, line, source, hint) when is_float(f) do + defp float_to_integer!(f, line, source, hint, state) when is_float(f) do truncated = trunc(f) if f == truncated * 1.0 and Numeric.signed?(truncated) do @@ -2893,7 +2907,8 @@ defmodule Lua.VM.Executor do line: line, source: source, error_kind: :bitwise_on_non_integer, - value_type: :number + value_type: :number, + state: state end end From 0101a0960eab3fed6ee6ba18f3d82ceb812debc5 Mon Sep 17 00:00:00 2001 From: Dave Lucia Date: Thu, 4 Jun 2026 08:39:45 -0700 Subject: [PATCH 05/12] fix(vm): add frame-boundary backstop for raise-time state capture MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Frame entries in both engines (Executor.execute, the lua_closure paths of call_function/call_value, and the dispatcher's do_execute_top) annotate escaping VM exceptions with the frame's entry state when nothing deeper attached one. Converts any missed raise site from 'loses all mutations under pcall' into 'loses only in-frame mutations of the innermost unannotated frame'. One try per frame entry — the executor loop's tail recursion is untouched. --- lib/lua/vm/dispatcher.ex | 17 ++++++++++---- lib/lua/vm/executor.ex | 49 ++++++++++++++++++++++++++++++---------- 2 files changed, 50 insertions(+), 16 deletions(-) diff --git a/lib/lua/vm/dispatcher.ex b/lib/lua/vm/dispatcher.ex index a49b7ab6..6199a829 100644 --- a/lib/lua/vm/dispatcher.ex +++ b/lib/lua/vm/dispatcher.ex @@ -135,12 +135,21 @@ defmodule Lua.VM.Dispatcher do end saved_open = state.open_upvalues - state = %{state | open_upvalues: %{}} - {results, state} = dispatch(proto.bytecode, 1, regs, upvalues, proto, state, [], []) + try do + state = %{state | open_upvalues: %{}} - state = %{state | open_upvalues: saved_open} - {results, state} + {results, state} = dispatch(proto.bytecode, 1, regs, upvalues, proto, state, [], []) + + state = %{state | open_upvalues: saved_open} + {results, state} + rescue + # Backstop net: any raise site missed by the per-site state + # annotations still ferries out at least this frame's entry state, + # so protected calls keep heap effects from enclosing frames — + # see `Lua.VM.Executor.annotate_state/2`. + e -> reraise Executor.annotate_frame_state(e, state), __STACKTRACE__ + end end defp init_regs(proto, args) do diff --git a/lib/lua/vm/executor.ex b/lib/lua/vm/executor.ex index d72e3886..286fab73 100644 --- a/lib/lua/vm/executor.ex +++ b/lib/lua/vm/executor.ex @@ -89,6 +89,11 @@ defmodule Lua.VM.Executor do do_execute(instructions, registers, upvalues, proto, state, [], [], 0) {results, regs, %{state | open_upvalues: saved_open_upvalues}} + rescue + # Backstop net: any raise site missed by the per-site annotations + # still ferries out at least this frame's entry state, bounding the + # loss to in-frame mutations of the innermost unannotated frame. + e -> reraise annotate_state(e, state), __STACKTRACE__ after restore_position(prev) end @@ -103,6 +108,7 @@ defmodule Lua.VM.Executor do defp restore_position(@unset), do: Process.delete(@position_key) defp restore_position(pos), do: Process.put(@position_key, pos) + @doc false # Ferries the freshest state at an execution boundary out on VM # exceptions, so protected calls (pcall/xpcall) can keep heap effects # made before the error — see `Lua.VM.State.unwind_to/2`. @@ -111,8 +117,13 @@ defmodule Lua.VM.Executor do # deeper in the call tree already carries a fresher snapshot than any # enclosing boundary's. Non-VM exceptions (no `:state` key) pass through # untouched. Runs only on the error path — the happy path never pays. - defp annotate_state(%{state: nil} = e, %State{} = state), do: %{e | state: state} - defp annotate_state(e, _state), do: e + # Public (but undocumented) so `Lua.VM.Dispatcher`'s frame boundary can + # use the same net. + @spec annotate_frame_state(Exception.t(), State.t()) :: Exception.t() + def annotate_frame_state(%{state: nil} = e, %State{} = state), do: %{e | state: state} + def annotate_frame_state(e, _state), do: e + + defp annotate_state(e, state), do: annotate_frame_state(e, state) @doc """ Calls a Lua function value with the given arguments. @@ -140,13 +151,21 @@ defmodule Lua.VM.Executor do end saved_open_upvalues = state.open_upvalues - state = %{state | open_upvalues: %{}} - {results, _callee_regs, state} = - do_execute(callee_proto.instructions, callee_regs, callee_upvalues, callee_proto, state, [], [], 0) + try do + state = %{state | open_upvalues: %{}} + + {results, _callee_regs, state} = + do_execute(callee_proto.instructions, callee_regs, callee_upvalues, callee_proto, state, [], [], 0) - state = %{state | open_upvalues: saved_open_upvalues} - {results, state} + state = %{state | open_upvalues: saved_open_upvalues} + {results, state} + rescue + # Backstop net: a raise site missed by the per-site annotations still + # ferries out at least this frame's entry state, bounding the loss to + # in-frame mutations of the innermost unannotated frame. + e -> reraise annotate_state(e, state), __STACKTRACE__ + end end def call_function({:compiled_closure, callee_proto, callee_upvalues}, args, state) do @@ -2132,13 +2151,19 @@ defmodule Lua.VM.Executor do end saved_open_upvalues = state.open_upvalues - state = %{state | open_upvalues: %{}} - {results, _callee_regs, state} = - do_execute(callee_proto.instructions, callee_regs, callee_upvalues, callee_proto, state, [], [], 0) + try do + state = %{state | open_upvalues: %{}} - state = %{state | open_upvalues: saved_open_upvalues} - {results, state} + {results, _callee_regs, state} = + do_execute(callee_proto.instructions, callee_regs, callee_upvalues, callee_proto, state, [], [], 0) + + state = %{state | open_upvalues: saved_open_upvalues} + {results, state} + rescue + # Backstop net — same rationale as the `call_function/3` closure path. + e -> reraise annotate_state(e, state), __STACKTRACE__ + end end defp call_value({:compiled_closure, _, _} = closure, args, _proto, state, _line) do From ba08fbcd0f37b008b260f9d8b347126e184a7692 Mon Sep 17 00:00:00 2001 From: Dave Lucia Date: Thu, 4 Jun 2026 08:44:08 -0700 Subject: [PATCH 06/12] chore: changelog entry and focused benchmark for pcall state fix Also derives Inspect excluding :state on VM exceptions so inspecting a trapped error never dumps the whole VM heap into logs. --- CHANGELOG.md | 11 +++++ benchmarks/scripts/pcall_state_bench.exs | 63 ++++++++++++++++++++++++ lib/lua/vm/argument_error.ex | 1 + lib/lua/vm/assertion_error.ex | 1 + lib/lua/vm/runtime_error.ex | 1 + lib/lua/vm/type_error.ex | 1 + 6 files changed, 78 insertions(+) create mode 100644 benchmarks/scripts/pcall_state_bench.exs diff --git a/CHANGELOG.md b/CHANGELOG.md index 2af7ec0a..ff150120 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## Unreleased +### Fixed + +- **Protected calls no longer roll back heap effects** (#331). When a function + called via `pcall`/`xpcall` (or `Lua.call_function/3` from Elixir) raised an + error, mutations made before the error — global writes, table field updates, + upvalue assignments, metatable changes — were silently discarded, diverging + from reference Lua. VM exceptions now carry the raise-time state, and + protected-call boundaries recover it: heap state is kept, control state + (call stack, open upvalues) unwinds. The `xpcall` message handler now also + observes those mutations, matching PUC-Lua's handler semantics. + ## [v1.0.0-rc.1] - 2026-06-02 The second release candidate for `1.0.0`. It builds on rc.0 with a new diff --git a/benchmarks/scripts/pcall_state_bench.exs b/benchmarks/scripts/pcall_state_bench.exs new file mode 100644 index 00000000..86766ee8 --- /dev/null +++ b/benchmarks/scripts/pcall_state_bench.exs @@ -0,0 +1,63 @@ +# Focused micro-benchmark for the pcall heap-effect preservation change. +# Run on two checkouts and diff: +# MIX_ENV=benchmark mix run benchmarks/scripts/pcall_state_bench.exs +# +# Covers the paths the change touches: +# * fib(28) — arithmetic hot path (widened safe_* helper arities) +# * table writes — t[i] = i loop (table_newindex fast path) +# * concat loop — concat_checked/concat_coerce widening +# * pcall loop — protected-call overhead incl. the new try wrappers + +defmodule PcallStateBench do + def chunk(lua, code) do + {chunk, _} = Lua.load_chunk!(lua, code) + chunk + end +end + +lua = Lua.new() + +{_, lua} = + Lua.eval!(lua, """ + function fib(n) + if n < 2 then return n end + return fib(n-1) + fib(n-2) + end + """) + +fib = PcallStateBench.chunk(lua, "return fib(28)") + +table_writes = + PcallStateBench.chunk(lua, """ + local t = {} + for i = 1, 200000 do t[i] = i end + return #t + """) + +concat_loop = + PcallStateBench.chunk(lua, """ + local s = "" + for i = 1, 5000 do s = s .. "x" end + return #s + """) + +pcall_loop = + PcallStateBench.chunk(lua, """ + local n = 0 + for i = 1, 50000 do + local ok = pcall(function() n = n + 1 end) + end + return n + """) + +Benchee.run( + %{ + "fib(28)" => fn -> Lua.eval!(lua, fib) end, + "table writes 200k" => fn -> Lua.eval!(lua, table_writes) end, + "concat 5k" => fn -> Lua.eval!(lua, concat_loop) end, + "pcall loop 50k" => fn -> Lua.eval!(lua, pcall_loop) end + }, + warmup: 1, + time: 4, + memory_time: 0 +) diff --git a/lib/lua/vm/argument_error.ex b/lib/lua/vm/argument_error.ex index 28962708..bb329575 100644 --- a/lib/lua/vm/argument_error.ex +++ b/lib/lua/vm/argument_error.ex @@ -49,6 +49,7 @@ defmodule Lua.VM.ArgumentError do # (pcall/xpcall) can keep heap effects made before the error instead of # rolling back to their entry snapshot. It is out-of-band metadata: it never # participates in `message` and stays `nil` when no state was in scope. + @derive {Inspect, except: [:state]} defexception [ :function_name, :arg_num, diff --git a/lib/lua/vm/assertion_error.ex b/lib/lua/vm/assertion_error.ex index 1b590607..dc3944a3 100644 --- a/lib/lua/vm/assertion_error.ex +++ b/lib/lua/vm/assertion_error.ex @@ -15,6 +15,7 @@ defmodule Lua.VM.AssertionError do # (pcall/xpcall) can keep heap effects made before the error instead of # rolling back to their entry snapshot. It is out-of-band metadata: it never # participates in `message` and stays `nil` when no state was in scope. + @derive {Inspect, except: [:state]} defexception [:value, :source, :message, :call_stack, :line, :state] @impl true diff --git a/lib/lua/vm/runtime_error.ex b/lib/lua/vm/runtime_error.ex index 47b3594c..9615ec27 100644 --- a/lib/lua/vm/runtime_error.ex +++ b/lib/lua/vm/runtime_error.ex @@ -22,6 +22,7 @@ defmodule Lua.VM.RuntimeError do # (pcall/xpcall) can keep heap effects made before the error instead of # rolling back to their entry snapshot. It is out-of-band metadata: it never # participates in `message` and stays `nil` when no state was in scope. + @derive {Inspect, except: [:state]} defexception [:value, :source, :message, :call_stack, :line, :state] @impl true diff --git a/lib/lua/vm/type_error.ex b/lib/lua/vm/type_error.ex index 25324cd2..8069b90e 100644 --- a/lib/lua/vm/type_error.ex +++ b/lib/lua/vm/type_error.ex @@ -20,6 +20,7 @@ defmodule Lua.VM.TypeError do # (pcall/xpcall) can keep heap effects made before the error instead of # rolling back to their entry snapshot. It is out-of-band metadata: it never # participates in `message` and stays `nil` when no state was in scope. + @derive {Inspect, except: [:state]} defexception [:value, :source, :message, :call_stack, :line, :error_kind, :value_type, :state] @impl true From 63abac0539fe85f53949e33f782fa9a9d44da394 Mon Sep 17 00:00:00 2001 From: Dave Lucia Date: Thu, 4 Jun 2026 10:14:22 -0700 Subject: [PATCH 07/12] fix(vm): thread state into gsub invalid-replacement raise string.gsub with a function replacement threads state through the callback, but the invalid-return RuntimeError dropped the freshest post-callback state, so a protected unwind rolled back the callback's heap effects. Attach the live %State{} to the raise (guarded so the non-stateful gsub/4 entry, which passes nil, is unaffected). Also point the frame-boundary rescue comments at the real public Executor.annotate_frame_state/2 and collapse the redundant private annotate_state/2 alias so the name is uniform across both engines. --- lib/lua/vm/dispatcher.ex | 2 +- lib/lua/vm/executor.ex | 14 ++++++-------- lib/lua/vm/stdlib/pattern.ex | 15 ++++++++++++++- 3 files changed, 21 insertions(+), 10 deletions(-) diff --git a/lib/lua/vm/dispatcher.ex b/lib/lua/vm/dispatcher.ex index 6199a829..72eaa6f6 100644 --- a/lib/lua/vm/dispatcher.ex +++ b/lib/lua/vm/dispatcher.ex @@ -147,7 +147,7 @@ defmodule Lua.VM.Dispatcher do # Backstop net: any raise site missed by the per-site state # annotations still ferries out at least this frame's entry state, # so protected calls keep heap effects from enclosing frames — - # see `Lua.VM.Executor.annotate_state/2`. + # see `Lua.VM.Executor.annotate_frame_state/2`. e -> reraise Executor.annotate_frame_state(e, state), __STACKTRACE__ end end diff --git a/lib/lua/vm/executor.ex b/lib/lua/vm/executor.ex index 286fab73..a3298161 100644 --- a/lib/lua/vm/executor.ex +++ b/lib/lua/vm/executor.ex @@ -93,7 +93,7 @@ defmodule Lua.VM.Executor do # Backstop net: any raise site missed by the per-site annotations # still ferries out at least this frame's entry state, bounding the # loss to in-frame mutations of the innermost unannotated frame. - e -> reraise annotate_state(e, state), __STACKTRACE__ + e -> reraise annotate_frame_state(e, state), __STACKTRACE__ after restore_position(prev) end @@ -123,8 +123,6 @@ defmodule Lua.VM.Executor do def annotate_frame_state(%{state: nil} = e, %State{} = state), do: %{e | state: state} def annotate_frame_state(e, _state), do: e - defp annotate_state(e, state), do: annotate_frame_state(e, state) - @doc """ Calls a Lua function value with the given arguments. @@ -164,7 +162,7 @@ defmodule Lua.VM.Executor do # Backstop net: a raise site missed by the per-site annotations still # ferries out at least this frame's entry state, bounding the loss to # in-frame mutations of the innermost unannotated frame. - e -> reraise annotate_state(e, state), __STACKTRACE__ + e -> reraise annotate_frame_state(e, state), __STACKTRACE__ end end @@ -180,7 +178,7 @@ defmodule Lua.VM.Executor do # state (the freshest state any stdlib raise site could have seen), so # protected calls can keep heap effects made before the error without # every bad-argument check threading state into its raise. Innermost - # annotation wins — see `annotate_state/2`. + # annotation wins — see `annotate_frame_state/2`. def call_function({:native_func, fun}, args, state) do case fun.(args, state) do {results, %State{} = new_state} when is_list(results) -> @@ -190,7 +188,7 @@ defmodule Lua.VM.Executor do {List.wrap(results), new_state} end rescue - e -> reraise annotate_state(e, state), __STACKTRACE__ + e -> reraise annotate_frame_state(e, state), __STACKTRACE__ end def call_function(nil, _args, state) do @@ -1109,7 +1107,7 @@ defmodule Lua.VM.Executor do value: "native function returned invalid result: #{inspect(other)}, expected {results, state}" end rescue - e -> reraise annotate_state(e, state), __STACKTRACE__ + e -> reraise annotate_frame_state(e, state), __STACKTRACE__ after restore_position(prev_pos) end @@ -2162,7 +2160,7 @@ defmodule Lua.VM.Executor do {results, state} rescue # Backstop net — same rationale as the `call_function/3` closure path. - e -> reraise annotate_state(e, state), __STACKTRACE__ + e -> reraise annotate_frame_state(e, state), __STACKTRACE__ end end diff --git a/lib/lua/vm/stdlib/pattern.ex b/lib/lua/vm/stdlib/pattern.ex index 326f39d3..953dc13f 100644 --- a/lib/lua/vm/stdlib/pattern.ex +++ b/lib/lua/vm/stdlib/pattern.ex @@ -234,7 +234,7 @@ defmodule Lua.VM.Stdlib.Pattern do result when is_number(result) -> to_string(result) false -> whole_match nil -> whole_match - other -> raise RuntimeError, value: "invalid replacement value (a #{Util.typeof(other)})" + other -> raise_invalid_replacement(other, state) end {replacement, state} @@ -242,6 +242,19 @@ defmodule Lua.VM.Stdlib.Pattern do defp apply_replacement(_repl, whole_match, _captures, state), do: {whole_match, state} + # The callback may have made heap mutations (global/table/upvalue/metatable + # writes) that thread back through `state` before returning an invalid value. + # Ferry the freshest `state` out on the raise so a protected unwind keeps + # those effects (Lua 5.3 §2.3). The non-stateful `gsub/4` entry calls with + # `state == nil`, so only attach when a real `%State{}` is in scope. + defp raise_invalid_replacement(other, %Lua.VM.State{} = state) do + raise RuntimeError, value: "invalid replacement value (a #{Util.typeof(other)})", state: state + end + + defp raise_invalid_replacement(other, _state) do + raise RuntimeError, value: "invalid replacement value (a #{Util.typeof(other)})" + end + defp replace_captures("", _whole, _captures), do: "" defp replace_captures("%" <> <>, whole, captures) when c in ?0..?9 do From cd139064b1c46f89a54592a80fb19c3c8e4aaab1 Mon Sep 17 00:00:00 2001 From: Dave Lucia Date: Thu, 4 Jun 2026 10:14:26 -0700 Subject: [PATCH 08/12] test(vm): cover native-callback errors under pcall Add matrix cases (both engines) for heap mutations made inside a native stdlib callback that errors before returning: a gsub function replacement that returns an invalid value, a table.sort comparator that errors, and a pairs loop body that errors. These cross the native-call choke point and exercise the innermost-annotation reraise path. --- test/lua/vm/pcall_state_preservation_test.exs | 59 +++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/test/lua/vm/pcall_state_preservation_test.exs b/test/lua/vm/pcall_state_preservation_test.exs index 72115bb5..98928f5e 100644 --- a/test/lua/vm/pcall_state_preservation_test.exs +++ b/test/lua/vm/pcall_state_preservation_test.exs @@ -187,6 +187,65 @@ defmodule Lua.VM.PcallStatePreservationTest do assert [2, false] = results end + test "gsub callback heap mutation before an invalid-return error is kept" do + {results, _state} = + run( + """ + x = 1 + local ok = pcall(function() + return string.gsub("ab", ".", function(c) + x = 2 + return {} + end) + end) + return x, ok + """, + @engine + ) + + assert [2, false] = results + end + + test "table.sort comparator mutation before its error is kept" do + {results, _state} = + run( + """ + x = 1 + local t = {3, 1, 2} + local ok = pcall(function() + table.sort(t, function(a, b) + x = 2 + error("bad comparator") + end) + end) + return x, ok + """, + @engine + ) + + assert [2, false] = results + end + + test "pairs loop-body mutation before its error is kept" do + {results, _state} = + run( + """ + x = 0 + local t = {a = 1, b = 2} + local ok = pcall(function() + for _k, _v in pairs(t) do + x = x + 1 + error("loop") + end + end) + return x, ok + """, + @engine + ) + + assert [1, false] = results + end + test "mutation before error() with a table error object is kept" do {results, _state} = run( From c2716b4ac20281f552bd532ad097fcc7057fb461 Mon Sep 17 00:00:00 2001 From: Dave Lucia Date: Thu, 4 Jun 2026 10:24:33 -0700 Subject: [PATCH 09/12] fix(vm): annotate native iterator raises with call-time state MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The native-function clause of call_value/5 — the choke point for generic-for iterators reached from both engines — wrapped the native call in try/after for position restore but had no state-annotating rescue. A VM exception raised by a native iterator (utf8.codes, next via pairs) escaped with :state == nil and was only caught by the enclosing frame backstop, which annotated it with the frame's ENTRY state, rolling back heap mutations the protected function made before the loop (violating Lua 5.3 §2.3). Mirror the :call opcode native dispatch: add a rescue that reraises annotate_frame_state(e, state) so the iterator-call's entry state ferries out on the exception. Both engines route through this one clause via Executor.dispatcher_call_value/4, so no parity gap. Also thread the flushed state into lua_next's invalid-key ArgumentError so a next() invalid-key raise keeps the order_tail normalization and any prior heap mutations across the protected boundary. --- lib/lua/vm/executor.ex | 7 ++++ lib/lua/vm/stdlib.ex | 3 +- test/lua/vm/pcall_state_preservation_test.exs | 37 +++++++++++++++++++ 3 files changed, 46 insertions(+), 1 deletion(-) diff --git a/lib/lua/vm/executor.ex b/lib/lua/vm/executor.ex index a3298161..91ca5275 100644 --- a/lib/lua/vm/executor.ex +++ b/lib/lua/vm/executor.ex @@ -2184,6 +2184,13 @@ defmodule Lua.VM.Executor do {results, %State{} = new_state} -> {List.wrap(results), new_state} end + rescue + # Same native-call backstop as the `:call` opcode dispatch: ferry the + # iterator-call's entry state out on the exception so a native iterator + # raise (e.g. `utf8.codes`, `next`) keeps the current frame's pre-loop + # heap mutations. Innermost annotation wins — a state-bearing inner + # raise still takes precedence. + e -> reraise annotate_frame_state(e, state), __STACKTRACE__ after restore_position(prev_pos) end diff --git a/lib/lua/vm/stdlib.ex b/lib/lua/vm/stdlib.ex index f3eaa7a0..67a4f07a 100644 --- a/lib/lua/vm/stdlib.ex +++ b/lib/lua/vm/stdlib.ex @@ -335,7 +335,8 @@ defmodule Lua.VM.Stdlib do raise ArgumentError, function_name: "next", arg_num: 2, - details: "invalid key to 'next'" + details: "invalid key to 'next'", + state: state nil -> {[nil, nil], state} diff --git a/test/lua/vm/pcall_state_preservation_test.exs b/test/lua/vm/pcall_state_preservation_test.exs index 98928f5e..4341ac76 100644 --- a/test/lua/vm/pcall_state_preservation_test.exs +++ b/test/lua/vm/pcall_state_preservation_test.exs @@ -246,6 +246,43 @@ defmodule Lua.VM.PcallStatePreservationTest do assert [1, false] = results end + test "mutation before a native iterator raise (utf8.codes) is kept" do + {results, _state} = + run( + """ + x = 1 + local ok = pcall(function() + x = 42 + for _p, _c in utf8.codes("\\xff\\xfe") do + x = 100 + end + end) + return x, ok + """, + @engine + ) + + assert [42, false] = results + end + + test "mutation before a next() invalid-key raise is kept" do + {results, _state} = + run( + """ + x = 1 + local t = {a = 1} + local ok = pcall(function() + x = 7 + return next(t, "not-a-key") + end) + return x, ok + """, + @engine + ) + + assert [7, false] = results + end + test "mutation before error() with a table error object is kept" do {results, _state} = run( From 9d804f3bb1614c906b1ca0d3b61fb4cb3d710f65 Mon Sep 17 00:00:00 2001 From: Dave Lucia Date: Thu, 4 Jun 2026 10:24:37 -0700 Subject: [PATCH 10/12] chore(benchmarks): add @moduledoc false to pcall_state_bench Consistent with the repo's Styler plugin output; the file failed mix format --check-formatted otherwise. --- benchmarks/scripts/pcall_state_bench.exs | 1 + 1 file changed, 1 insertion(+) diff --git a/benchmarks/scripts/pcall_state_bench.exs b/benchmarks/scripts/pcall_state_bench.exs index 86766ee8..9651178d 100644 --- a/benchmarks/scripts/pcall_state_bench.exs +++ b/benchmarks/scripts/pcall_state_bench.exs @@ -9,6 +9,7 @@ # * pcall loop — protected-call overhead incl. the new try wrappers defmodule PcallStateBench do + @moduledoc false def chunk(lua, code) do {chunk, _} = Lua.load_chunk!(lua, code) chunk From 44ec4923ca4cb03ab242681517d6a7f110246425 Mon Sep 17 00:00:00 2001 From: Dave Lucia Date: Thu, 4 Jun 2026 10:31:48 -0700 Subject: [PATCH 11/12] fix(lua): ferry state out of user-function error tuples under pcall The set!/3 arity-2 and deflua execute_function wrappers raised RuntimeError without attaching the returned struct's state when a user function signaled {:error, reason, %Lua{}}. The only annotation that fired was the native-call choke point using the pre-call entry state, which predates the mutations the user function made before erroring, so pcall/xpcall rolled them back. Bind the returned struct and pass state: returned_lua.state on the raise, mirroring the gsub callback fix, so heap effects survive protected-call unwinding. Add pcall_state_preservation tests covering both wrapper sites. Closes #331 --- lib/lua.ex | 8 ++-- test/lua/vm/pcall_state_preservation_test.exs | 43 +++++++++++++++++++ 2 files changed, 47 insertions(+), 4 deletions(-) diff --git a/lib/lua.ex b/lib/lua.ex index c89db484..5e3199e5 100644 --- a/lib/lua.ex +++ b/lib/lua.ex @@ -309,8 +309,8 @@ defmodule Lua do {function_name, scope} = List.pop_at(keys, -1) case func.(args, wrap(state)) do - {:error, reason, %__MODULE__{}} -> - raise RuntimeError, value: reason + {:error, reason, %__MODULE__{} = returned_lua} -> + raise RuntimeError, value: reason, state: returned_lua.state {value, %__MODULE__{} = lua} -> value = List.wrap(value) @@ -1117,8 +1117,8 @@ defmodule Lua do {:error, reason} -> raise RuntimeError, value: reason - {:error, reason, %Lua{}} -> - raise RuntimeError, value: reason + {:error, reason, %Lua{} = returned_lua} -> + raise RuntimeError, value: reason, state: returned_lua.state {data, %Lua{} = returned_lua} -> data = List.wrap(data) diff --git a/test/lua/vm/pcall_state_preservation_test.exs b/test/lua/vm/pcall_state_preservation_test.exs index 4341ac76..83be8a5b 100644 --- a/test/lua/vm/pcall_state_preservation_test.exs +++ b/test/lua/vm/pcall_state_preservation_test.exs @@ -493,5 +493,48 @@ defmodule Lua.VM.PcallStatePreservationTest do assert reason =~ "boom" assert Lua.get!(lua, [:x]) == 2 end + + test "set!/3 user function keeps heap mutations when it returns {:error, reason, lua}" do + lua = + Lua.set!(Lua.new(), [:mutate_then_fail], fn _args, lua -> + lua = Lua.set!(lua, [:y], 99) + {:error, "boom", lua} + end) + + assert {[false, msg, 99], lua} = + Lua.eval!(lua, """ + y = 1 + local ok, err = pcall(mutate_then_fail) + return ok, err, y + """) + + assert msg =~ "boom" + assert Lua.get!(lua, [:y]) == 99 + end + + test "deflua user function keeps heap mutations when it returns {:error, reason, lua}" do + assert [{module, _}] = + Code.compile_string(""" + defmodule MutateThenFail do + use Lua.API + + deflua boom(), state do + lua = Lua.set!(state, [:y], 99) + {:error, "boom", lua} + end + end + """) + + lua = Lua.load_api(Lua.new(), module) + + assert {[false, msg, 99], _lua} = + Lua.eval!(lua, """ + y = 1 + local ok, err = pcall(boom) + return ok, err, y + """) + + assert msg =~ "boom" + end end end From d785722bd2d533da0686417013ee6338bef969d8 Mon Sep 17 00:00:00 2001 From: Dave Lucia Date: Thu, 4 Jun 2026 10:38:44 -0700 Subject: [PATCH 12/12] bench(vm): measure memory and exercise lua-closure generic_for in pcall bench Enable memory_time so the per-call allocation/GC delta of the added try frames is observable, and add a generic_for case driven by a Lua closure iterator so executor.ex call_value/5's lua_closure clause (the path that gained a new per-iteration try block) is actually exercised. --- benchmarks/scripts/pcall_state_bench.exs | 28 ++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/benchmarks/scripts/pcall_state_bench.exs b/benchmarks/scripts/pcall_state_bench.exs index 9651178d..b0e9f73a 100644 --- a/benchmarks/scripts/pcall_state_bench.exs +++ b/benchmarks/scripts/pcall_state_bench.exs @@ -7,6 +7,12 @@ # * table writes — t[i] = i loop (table_newindex fast path) # * concat loop — concat_checked/concat_coerce widening # * pcall loop — protected-call overhead incl. the new try wrappers +# * closure for — generic_for driven by a Lua-closure iterator, which is +# the path that gained a new per-iteration try block in +# executor.ex call_value/5 (lua_closure clause) +# +# memory_time is enabled so the per-call allocation/GC delta of the added try +# frames is observable, not just wall-clock time. defmodule PcallStateBench do @moduledoc false @@ -51,14 +57,32 @@ pcall_loop = return n """) +# A stateful Lua-closure iterator drives the generic_for loop, so each +# iteration routes through executor.ex call_value/5's lua_closure clause — +# the path that gained a new per-iteration try block in this change. +closure_for = + PcallStateBench.chunk(lua, """ + local function range(limit) + local i = 0 + return function() + i = i + 1 + if i <= limit then return i end + end + end + local sum = 0 + for v in range(50000) do sum = sum + v end + return sum + """) + Benchee.run( %{ "fib(28)" => fn -> Lua.eval!(lua, fib) end, "table writes 200k" => fn -> Lua.eval!(lua, table_writes) end, "concat 5k" => fn -> Lua.eval!(lua, concat_loop) end, - "pcall loop 50k" => fn -> Lua.eval!(lua, pcall_loop) end + "pcall loop 50k" => fn -> Lua.eval!(lua, pcall_loop) end, + "closure for 50k" => fn -> Lua.eval!(lua, closure_for) end }, warmup: 1, time: 4, - memory_time: 0 + memory_time: 2 )