benilla-octo/third_party/mlua-sys/BENILLA.md

benilla's mlua-sys fork: what differs from upstream, and how to check

Upstream: mlua-rs/mlua, MIT, crate mlua-sys version 0.10.0, the version mlua 0.11.6 resolves to. Wired in through [patch.crates-io] in the workspace root.

Why a fork exists at all

src/lua51/compat.rs is mlua-sys' back-port of the Lua 5.2/5.3 auxiliary library onto Lua 5.1, derived from lua-compat-5.3. One of the functions it back-ports is luaL_traceback, and 5.3's luaL_traceback names each stack frame by searching for the frame's function by value: the globals table, then one level into every table in it, comparing every value with lua_rawequal until it finds a match (compat53_findfield / compat53_pushglobalfuncname). That is run once per stack level, per traceback.

mlua builds exactly that traceback for every Err a Rust binding returns — callback_error_ext in mlua's src/state/util.rs wraps the error as Error::CallbackError { traceback, cause } before re-raising it — and benilla's Lua surface is ~2,400 Rust bindings that raise by returning Err (Usage: UnitName("unit"), Unknown unit name: …, the addon instruction budget).

The search's cost is the size of _G, and a loaded 1.12 interface's _G is not small. Measured by benilla-app's addon_harness::tick_bench on the shipped FrameXML plus the 23 addons under benilla-config/AddOns:

[raise] what mlua's handler would walk: 27114 globals, 83372 keys one level in, biggest _G (27114)
[raise] a binding's own `Usage:` raise, caught by Lua: 6949.2 us     ← before this fork
[raise] the same raise in a bare VM (1169 globals):      83.2 us

6.9 ms for one raise (7.0–7.5 ms across runs), and a raise an addon wraps in pcall pays all of it and reaches no log: pcall catches the error before the host ever sees it, so the only symptom is a frame that took too long. Five such raises a frame is an entire frame budget, with a clean error log — 44.7 ms of VM tick, measured below.

benilla already had to route around the same search once: handler and C_Timer dispatch go through Lua's own xpcall rather than mlua's protected call, for this reason (benilla_ui::script::event::PROTECTED_CALL, whose doc comment carries the measurement). That route cannot reach callback_error_ext, which is inside the lua_CFunction mlua wraps every binding in. A fork is the only place the cost can be removed from.

What is not being done

benilla is not forking mlua, and not changing the error contract. The raise's message is untouched: it is built by the binding, carried as the cause, and printed first. The traceback still has its stack traceback: header, its \n\t-indented frame list, its <file>:<line>: prefixes and its (...tail calls...) and (skipping %d levels) lines. Only how a frame's function is named changes, and only for frames whose call site gives no name.

The other five Lua dialects and the whole of Luau are upstream's, untouched, including their own copies of compat53_findfield (src/lua52/compat.rs, src/lua53/compat.rs, src/luau/compat.rs). benilla builds lua51 and only lua51; a hunk in the others would be a hunk nobody compiles.

The delta, and the command that proves it

One file, src/lua51/compat.rs. Two deletions and one changed line, all under a BENILLA DELTA banner that carries the reasoning at the site:

hunk	why
compat53_findfield and compat53_pushglobalfuncname deleted, and the std::ffi::CStr import with them (its only use was the _G. prefix strip in compat53_pushglobalfuncname)	the globals-table search, 6.9 ms a raise on this interface
compat53_pushfuncname's first arm is now *ar.namewhat != '\0' → function '<ar.name>', i.e. the name from the call site	this is Lua 5.1's own naming: db_errorfb in third_party/lua-src/lua-5.1.5/ldblib.c:357 writes " in function " LUA_QS off ar.name under exactly that test, and searches nothing

Upstream's remaining arms (main chunk, function <%s:%d>, ?) are unchanged and in the same order, so a frame the search would not have named is named exactly as before.

Why the logged text does not move

lua_getinfo's name/namewhat come from the call site: a binding called as a global carries namewhat = "global", name = "UnitName", which is the same name the _G search would have found. Upstream printed function 'UnitName' from the search and global 'UnitName' from the call site; this fork prints function 'UnitName' from the call site, which is byte-identical to what the log carried before. That matters: benilla-app's addon_harness reads in function 'loadaddon' out of a traceback to decide whose raise a demand-load's error is (raised_inside_a_demand_load), and the Usage:/Unknown unit name:/instruction-budget messages have tests pinning them.

What does change is a frame whose function is a global and whose call site gives no name — a tail call, or a function handed to pcall by value. Those drop from function 'Name' to function <file:line> (Lua frame) or ? (C function), which is what Lua 5.1 and the 1.12 client's own debugstack (0x703760, reimplemented in benilla_ui::script::stdlib::debugstack) both print there, and what benilla's handler-dispatch traceback already printed.

Verifying against upstream

# 0.10.0 is the pinned version; adjust the path if cargo's registry hash differs.
diff -r --exclude=BENILLA.md --exclude=LICENSE --exclude=Cargo.toml \
  --exclude=Cargo.lock --exclude=Cargo.toml.orig --exclude='.cargo*' \
  third_party/mlua-sys ~/.cargo/registry/src/*/mlua-sys-0.10.0

That must name exactly src/lua51/compat.rs and nothing else. The excludes are all bookkeeping: Cargo.toml because the fork prepends a header comment to cargo's generated manifest; LICENSE because the registry copy ships none and the fork carries mlua's MIT text beside the source; and Cargo.lock, Cargo.toml.orig and .cargo-ok/.cargo_vcs_info.json because they are the registry's own packaging artefacts, which a path dependency ignores.

What this bought, measured

Same bench, same command (cargo test --release -p benilla-app --lib -- --ignored --nocapture tick_bench), same interface:

row	before	after
a binding's own Usage: raise, caught by Lua	6949.2 us	2.8 us
the same raise in a bare VM (1169 globals)	83.2 us	2.6 us
UiScript::run of a raising chunk, through mlua	6434.3 us	2.3 us
five pcall'd binding raises a frame, over the whole VM tick	45.104 ms/frame	0.507 ms/frame
the same frame with the raises disarmed (the control)	0.412 ms/frame	0.446 ms/frame

Two rows carry the argument. The bare-VM row is the control that names the cause: 1,169 globals cost 83 us where 27,114 cost 6,949, a ratio of 84 against a _G ratio of 23 — the search is quadratic-ish because it also walks one level in. And the five-raises row is the shape a player actually hits: an interface that swallows five binding raises a frame spent 44.7 ms of every frame inside the VM tick and wrote nothing to any error log, which is a frame budget gone with no symptom an instrument was looking for.

The test that fails if the search returns is benilla_ui::script::tests::caught_raise_cost::a_caught_binding_raise_does_not_cost_the_size_of_the_global_table: it measures the identical caught raise in a bare VM and in a 21,171-global one and refuses a ratio over 4×. Reverting this fork takes it to 37.3× (3607.2 us against 96.8 us).