From 14c8fc3768d978205bf17ffc1905c2772afbd434 Mon Sep 17 00:00:00 2001
From: Nat Goodspeed <nat@lindenlab.com>
Date: Wed, 28 Aug 2024 16:47:38 -0400
Subject: Add `LL.setdtor()` function to add a "destructor" to any Lua object.

`setdtor('description', object, function)` returns a proxy userdata object
referencing object and function. When the proxy is garbage-collected, or at
the end of the script, its destructor calls `function(object)`.

The original object may be retrieved as `proxy._target`, e.g. to pass it to
the `table` library. The proxy also has a metatable with metamethods
supporting arithmetic operations, string concatenation, length and table
indexing. For other operations, retrieve `proxy._target`. (But don't assign to
`proxy._target`. It will appear to work, in that subsequent references to
`proxy._target` will retrieve the replacement object -- however, the
destructor will still call `function(original object)`.)

Fix bugs in `lua_setfieldv()`, `lua_rawgetfield()` and `lua_rawsetfield()`.

Add C++ functions `lua_destroyuserdata()` to explicitly destroy a
`lua_emplace<T>()` userdata object, plus `lua_destroybounduserdata()`. The
latter can bind such a userdata object as an upvalue to pass to `LL.atexit()`.

Make `LL.help()` and `LL.leaphelp()` help text include the `LL.` prefix.
---
 indra/llcommon/lua_function.h | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

(limited to 'indra/llcommon/lua_function.h')

diff --git a/indra/llcommon/lua_function.h b/indra/llcommon/lua_function.h
index 6965e206ab..83abe8d71e 100644
--- a/indra/llcommon/lua_function.h
+++ b/indra/llcommon/lua_function.h
@@ -339,6 +339,7 @@ auto lua_getfieldv(lua_State* L, int index, const char* k)
 template <typename T>
 auto lua_setfieldv(lua_State* L, int index, const char* k, const T& value)
 {
+    index = lua_absindex(L, index);
     lua_checkdelta(L);
     lluau_checkstack(L, 1);
     lua_push(L, value);
@@ -349,6 +350,7 @@ auto lua_setfieldv(lua_State* L, int index, const char* k, const T& value)
 template <typename T>
 auto lua_rawgetfield(lua_State* L, int index, const std::string_view& k)
 {
+    index = lua_absindex(L, index);
     lua_checkdelta(L);
     lluau_checkstack(L, 1);
     lua_pushlstring(L, k.data(), k.length());
@@ -361,6 +363,7 @@ auto lua_rawgetfield(lua_State* L, int index, const std::string_view& k)
 template <typename T>
 void lua_rawsetfield(lua_State* L, int index, const std::string_view& k, const T& value)
 {
+    index = lua_absindex(L, index);
     lua_checkdelta(L);
     lluau_checkstack(L, 2);
     lua_pushlstring(L, k.data(), k.length());
@@ -459,7 +462,7 @@ DistinctInt TypeTag<T>::value;
  * containing a newly-constructed C++ object T(args...). The userdata has a
  * Luau destructor guaranteeing that the new T instance is destroyed when the
  * userdata is garbage-collected, no later than when the LuaState is
- * destroyed.
+ * destroyed. It may be destroyed explicitly by calling lua_destroyuserdata().
  *
  * Usage:
  * lua_emplace<T>(L, T constructor args...);
@@ -511,6 +514,19 @@ T* lua_toclass(lua_State* L, int index)
     return static_cast<T*>(ptr);
 }
 
+/**
+ * Call lua_destroyuserdata() with the doomed userdata on the stack top.
+ * It must have been created by lua_emplace().
+ */
+int lua_destroyuserdata(lua_State* L);
+
+/**
+ * Call lua_pushcclosure(L, lua_destroybounduserdata, 1) with the target
+ * userdata on the stack top. When the resulting C closure is called with no
+ * arguments, the bound userdata is destroyed by lua_destroyuserdata().
+ */
+int lua_destroybounduserdata(lua_State *L);
+
 /*****************************************************************************
 *   lua_what()
 *****************************************************************************/
-- 
cgit v1.2.3