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
11 changes: 11 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
88 changes: 88 additions & 0 deletions benchmarks/scripts/pcall_state_bench.exs
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
# 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
# * 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
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
""")

# 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,
"closure for 50k" => fn -> Lua.eval!(lua, closure_for) end
},
warmup: 1,
time: 4,
memory_time: 2
)
21 changes: 14 additions & 7 deletions lib/lua.ex
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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`

Expand Down Expand Up @@ -1110,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)
Expand Down
11 changes: 9 additions & 2 deletions lib/lua/vm/argument_error.ex
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,11 @@ 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.
@derive {Inspect, except: [:state]}
defexception [
:function_name,
:arg_num,
Expand All @@ -53,7 +58,8 @@ defmodule Lua.VM.ArgumentError do
:details,
:line,
:source,
:call_stack
:call_stack,
:state
]

@impl true
Expand All @@ -70,7 +76,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

Expand Down
10 changes: 8 additions & 2 deletions lib/lua/vm/assertion_error.ex
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,12 @@ 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.
@derive {Inspect, except: [:state]}
defexception [:value, :source, :message, :call_stack, :line, :state]

@impl true
def exception(opts) do
Expand All @@ -28,7 +33,8 @@ defmodule Lua.VM.AssertionError do
source: source,
message: message,
call_stack: call_stack,
line: line
line: line,
state: Keyword.get(opts, :state)
}
end

Expand Down
22 changes: 16 additions & 6 deletions lib/lua/vm/dispatcher.ex
Original file line number Diff line number Diff line change
Expand Up @@ -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_frame_state/2`.
e -> reraise Executor.annotate_frame_state(e, state), __STACKTRACE__
end
end

defp init_regs(proto, args) do
Expand Down Expand Up @@ -842,7 +851,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)
Expand Down Expand Up @@ -1124,7 +1134,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)
Expand Down
Loading
Loading