Files
ClassicAPI/src/baselib/XPCall.cpp
T
Brues c26afcc050 feat(baselib): forward trailing arguments through xpcall
Ports Lua 5.2's `xpcall(f, msgh, ...)` shape. This client's xpcall takes only
(f, msgh), and its implementation is explicit about the rest: `lua_settop(L, 2)`
discards any further arguments, then `lua_pcall(L, 0, ...)` calls f with none.
So the argument-forwarding form did not fail loudly -- it called f with nothing,
and a function that read its parameters saw nil. (Not a 5.0-vs-5.1 difference:
both take (f, msgh). Forwarding arrived in 5.2.)

Replacing the base-library function rather than wrapping it in Lua, for the
same two reasons `select` and `unpack` are C in this directory. A Lua wrapper
would allocate a closure AND an `arg` table per call, putting an allocation on
every error-guarded path including per-frame ones; and HookSecureFunc's
kUnhookableNames lists xpcall precisely because shadowing a core primitive with
a Lua closure diverges from what C-side callers see.

lua_pcall wants the callee and its arguments contiguous on top with the handler
at a fixed index, but the incoming order puts the handler between them, so:

  PushValue(2) -> f, msgh, a1..aN, msgh
  Insert(1)    -> msgh, f, msgh, a1..aN
  Remove(3)    -> msgh, f, a1..aN

then PCall(top - 2, MULTRET, errfunc = 1), push the status boolean, Insert(2),
and return GetTop - 1 so the handler drops out of the result set. 5.2 does the
same reshuffle with one lua_rotate, which this Lua has no equivalent of.

Purely additive: a two-argument call forwards zero arguments and is the old
behavior exactly, so the capturing-closure idiom in ExecuteFrameScript and the
plain two-argument call in ItemUtil both keep working untouched.

Verified with 25 assertions across both halves. Backward: exact return counts,
embedded and trailing nil returns keeping their slots, reference identity, the
handler running once and receiving the message, a non-function handler tolerated
on the success path, nil f caught, an erroring handler still yielding false, and
the load-bearing one -- a two-argument call still passing f zero arguments.
Forward: false and embedded/trailing nil arguments surviving, twelve arguments
intact, forwarding composing with multiple returns, arguments still arriving on
the error path, and the two cases that target the shuffle -- the handler not
leaking in as argument 1, and the handler also being passable as an argument.

Two incidental confirmations: C-side lua_error does longjmp (the missing-handler
case is caught by an enclosing pcall), which the notes had flagged as uncertain;
and Lua-level error() still does not unwind, so f runs past it and xpcall
reports success with the handler never consulted.

Closes #45
2026-09-08 13:23:04 -05:00

95 lines
3.8 KiB
C++

// This file is part of ClassicAPI.
//
// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
// of the GNU General Public License as published by the Free Software Foundation, either
// version 3 of the License, or (at your option) any later version.
//
// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
// PURPOSE. See the GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License along with
// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
// `success, ... = xpcall(f, msgh [, arg1, ...])` — call `f` under `msgh`,
// forwarding the trailing arguments to it.
//
// 1.12's Lua takes only `xpcall(f, msgh)`. Its implementation is explicit
// about it: `lua_settop(L, 2)` throws any further arguments away, then
// `lua_pcall(L, 0, ...)` calls `f` with none. So the argument-forwarding form
// doesn't merely fail — it silently calls `f` with nothing, and a function
// that reads its parameters sees nil. (Note this is NOT a 5.0-vs-5.1
// difference: both take `(f, msgh)`. Forwarding arrived later.)
//
// Callers work around it with a capturing closure —
// `xpcall(function() return f(a, b) end, msgh)` — which is what
// `ExecuteFrameScript` in the embedded addon does. That stays correct; this
// just removes the need for it.
//
// Why a C function and not a Lua wrapper over the original: a Lua wrapper
// would allocate a closure AND an `arg` table on every call (see the vararg
// note in FunctionUtil.lua), putting an allocation on any error-guarded path,
// including per-frame ones. `HookSecureFunc`'s `kUnhookableNames` also lists
// `xpcall` precisely because shadowing a core primitive with a Lua closure
// diverges from what C-side callers get. Replacing it with a real C function
// has neither problem, and matches how `select` and `unpack` are backported
// in this directory.
//
// A two-argument call is bit-for-bit the old behavior (zero forwarded args),
// so this is purely additive for existing code.
#include "Game.h"
namespace BaseLib::XPCall {
namespace {
int __fastcall Script_xpcall(void *L) {
const int top = Game::Lua::GetTop(L);
if (top < 2) {
Game::Lua::Error(L, "bad argument #2 to 'xpcall' (value expected)");
return 0; // unreachable
}
// `lua_pcall` wants the callee and its arguments contiguous on top, and
// the handler at a fixed index. Incoming order is
// `f(1), msgh(2), a1(3)..aN(top)`, so the handler sits between the two —
// shuffle it below `f`:
//
// PushValue(2) → f, msgh, a1..aN, msgh
// Insert(1) → msgh, f, msgh, a1..aN (top moved down to index 1)
// Remove(3) → msgh, f, a1..aN
//
// 5.2 does the same reshuffle with a single `lua_rotate`, which this Lua
// has no equivalent of.
Game::Lua::PushValue(L, 2);
Game::Lua::Insert(L, 1);
Game::Lua::Remove(L, 3);
const int status =
Game::Lua::PCall(L, /*nargs*/ top - 2, Game::Lua::MULTRET, /*errfunc*/ 1);
// The stack now holds the handler plus either f's results or the handler's
// return. Both cases want the status boolean in front of them, and the
// handler itself dropped from the return set — which returning
// `GetTop - 1` does, since results are taken from the top.
Game::Lua::PushBool(L, status == 0);
Game::Lua::Insert(L, 2);
return Game::Lua::GetTop(L) - 1;
}
void RegisterInGame() {
Game::Lua::RegisterGlobalFunction("xpcall", &Script_xpcall);
}
void RegisterGlue() {
Game::Lua::RegisterGlueFunction("xpcall", &Script_xpcall);
}
const Game::ModuleAutoRegister _autoreg{&RegisterInGame};
const Game::GlueModuleAutoRegister _autoregGlue{&RegisterGlue};
} // namespace
} // namespace BaseLib::XPCall