New Lanes finalizer API lanes.finally()

8 files changed, 126 insertions, 54 deletions

diff --git a/docs/index.html b/docs/index.html
index f5a074f..20dccfa 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -336,8 +336,8 @@
                                 <tt>nil</tt>/<tt>"protected"</tt>/function
                         </td>
                         <td>
-                                If <tt>nil</tt>, Lua states are created with <tt>lua_newstate()</tt> and reuse the allocator from the master state.<br />
-                                If <tt>"protected"</tt>, The default allocator obtained from <tt>lua_getallocf()</tt> in the master state is wrapped inside a critical section and used in all newly created states.<br />
+                                If <tt>nil</tt>, Lua states are created with <tt>lua_newstate()</tt> and reuse the allocator from the master state.<br/>
+                                If <tt>"protected"</tt>, The default allocator obtained from <tt>lua_getallocf()</tt> in the master state is wrapped inside a critical section and used in all newly created states.<br/>
                                 If a <tt>function</tt>, this function is called prior to creating the state. It should return a full userdata containing the following structure:
                                 <table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%">
                                         <tr>
@@ -360,8 +360,8 @@
                         </td>
                         <td>
                                 Controls which allocator is used for Lanes internal allocations (for keeper, linda and lane management).
-                                If <tt>"libc"</tt>, Lanes uses <tt>realloc</tt> and <tt>free</tt>.<br />
-                                If <tt>"allocator"</tt>, Lanes uses whatever was obtained from the <tt>"allocator"</tt> setting.<br />
+                                If <tt>"libc"</tt>, Lanes uses <tt>realloc</tt> and <tt>free</tt>.<br/>
+                                If <tt>"allocator"</tt>, Lanes uses whatever was obtained from the <tt>"allocator"</tt> setting.<br/>
                                 This option is mostly useful for embedders that want control all memory allocations, but have issues when Lanes tries to use the Lua State allocator for internal purposes (especially with LuaJIT).
                         </td>
                 </tr>
@@ -455,6 +455,27 @@
         </tr>
 </table>
 
+<p>
+        It is also possible to install a function that will be called when Lanes is shutdown (that is, when the first state that required Lanes is closed).
+</p>
+
+<p>
+        <table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%">
+                <tr>
+                        <td>
+                                <pre>   lanes.finally(&lt;some function&gt;|nil)</pre>
+                        </td>
+                </tr>
+        </table>
+</p>
+
+<p>
+        An error will be raised if you attempt to do this from inside a lane, or on bad arguments (non-function, or too many arguments).<br/>
+        Only the last registered finalizer is kept. It can be cleared by passing <tt>nil</tt> or nothing.<br/>
+        The installed function is called after all free-running lanes are terminated, but before lindas become unusable.<br/>
+        If an error occurs inside this finalizer, it is silently swallowed, since it happens only during state shutdown, and you can't do anything about it.
+</p>
+
 <hr/>
 <h2 id="creation">Creation</h2>
 
@@ -682,8 +703,7 @@
                         </td>
                         <td>table</td>
                         <td>
-                                Sets the globals table for the launched threads. This can be used for giving them constants. The key/value pairs of <tt>table</tt> are transfered in the lane globals after the libraries have been loaded and the modules required.
-                                <br />
+                                Sets the globals table for the launched threads. This can be used for giving them constants. The key/value pairs of <tt>table</tt> are transfered in the lane globals after the libraries have been loaded and the modules required.<br/>
                                 The global values of different lanes are in no manner connected; modifying one will only affect the particular lane.
                         </td>
                 </tr>
@@ -696,8 +716,7 @@
                                 Lists modules that have to be required in order to be able to transfer functions they exposed. Starting with Lanes 3.0-beta, non-Lua functions are no longer copied by recreating a C closure from a C pointer, but are <a href="#function_notes">searched in lookup tables</a>.
                                 These tables are built from the modules listed here. <tt>required</tt> must be a list of strings, each one being the name of a module to be required. Each module is required with <tt>require()</tt> before the lanes function is invoked.
                                 So, from the required module's point of view, requiring it manually from inside the lane body or having it required this way doesn't change anything. From the lane body's point of view, the only difference is that a module not creating a global won't be accessible.
-                                Therefore, a lane body will also have to require a module manually, but this won't do anything more (see Lua's <tt>require</tt> documentation).
-                                <br />
+                                Therefore, a lane body will also have to require a module manually, but this won't do anything more (see Lua's <tt>require</tt> documentation). <br/>
                                 ATTEMPTING TO TRANSFER A FUNCTION REGISTERED BY A MODULE NOT LISTED HERE WILL RAISE AN ERROR.
                         </td>
                 </tr>
@@ -707,8 +726,8 @@
                         </td>
                         <td>string</td>
                         <td>
-                                Sets the error reporting mode. One of <tt>"minimal"</tt> (the default), <tt>"basic"</tt>, <tt>"extended"</tt>.<br />
-                                <tt>"minimal"</tt> yields only the location of the error.<br />
+                                Sets the error reporting mode. One of <tt>"minimal"</tt> (the default), <tt>"basic"</tt>, <tt>"extended"</tt>.<br/>
+                                <tt>"minimal"</tt> yields only the location of the error.<br/>
                                 The other 2 yield a full stack trace, with different amounts of data extracted from the debug infos. See <a href="#results">Results</a>.
                         </td>
                 </tr>
@@ -737,10 +756,8 @@
                         <td>integer</td>
                         <td>
                                 The priority of lanes generated in the range -3..+3 (default is 0).
-                                These values are a mapping over the actual priority range of the underlying implementation.
-                                <br />
-                                Implementation and dependability of priorities varies by platform. Especially Linux kernel 2.6 is not supporting priorities in user mode.
-                                <br />
+                                These values are a mapping over the actual priority range of the underlying implementation.<br/>
+                                Implementation and dependability of priorities varies by platform. Especially Linux kernel 2.6 is not supporting priorities in user mode.<br/>
                                 A lane can also change its own thread priority dynamically with <a href="#priority"><tt>lanes.set_thread_priority()</tt></a>.
                         </td>
                 </tr>
@@ -750,8 +767,7 @@
                         </td>
                         <td> table</td>
                         <td>
-                                Specifying it when <code>libs_str</code> doesn't cause the <code>package</code> library to be loaded will generate an error.
-                                <br />
+                                Specifying it when <code>libs_str</code> doesn't cause the <code>package</code> library to be loaded will generate an error.<br/>
                                 If not specified, the created lane will receive the current values of <tt>package</tt>. Only <tt>path</tt>, <tt>cpath</tt>, <tt>preload</tt> and <tt>loaders</tt> (Lua 5.1)/<tt>searchers</tt> (Lua 5.2) are transfered.
                         </td>
                 </tr>
@@ -1754,12 +1770,9 @@ static MyDeepFactory g_MyDeepFactory;
 </p>
 
 <p>
-        Deep userdata in transit inside keeper states (sent in a linda but not yet consumed) don't call <tt>deleteDeepObjectInternal</tt> and aren't considered by reference counting. The rationale is the following:
-        <br />
-        If some non-keeper state holds a deep userdata for some deep object, then even if the keeper collects its own deep userdata, it shouldn't be cleaned up since the refcount is not 0.
-        <br />
-        OTOH, if a keeper state holds the last deep userdata for some deep object, then no lane can do actual work with it. Deep userdata's <tt>factory()</tt> interface is never accessed from a keeper state.
-        <br />
+        Deep userdata in transit inside keeper states (sent in a linda but not yet consumed) don't call <tt>deleteDeepObjectInternal</tt> and aren't considered by reference counting. The rationale is the following:<br/>
+        If some non-keeper state holds a deep userdata for some deep object, then even if the keeper collects its own deep userdata, it shouldn't be cleaned up since the refcount is not 0.<br/>
+        OTOH, if a keeper state holds the last deep userdata for some deep object, then no lane can do actual work with it. Deep userdata's <tt>factory()</tt> interface is never accessed from a keeper state.<br/>
         Therefore, Lanes can just call <tt>deleteDeepObjectInternal</tt> when the last non-keeper-held deep userdata is collected, as long as it doesn't do the same in a keeper state after that, since any remaining deep userdata in keeper states now hold stale pointers.
 </p>
 
diff --git a/src/lanes.cpp b/src/lanes.cpp
index 0ea0900..109fba4 100644
--- a/src/lanes.cpp
+++ b/src/lanes.cpp
@@ -598,6 +598,7 @@ namespace {
             { "set_thread_affinity", LG_set_thread_affinity },
             { "nameof", luaG_nameof },
             { "register", LG_register },
+            { Universe::kFinally, Universe::InitializeFinalizer },
             { "set_singlethreaded", LG_set_singlethreaded },
             { nullptr, nullptr }
         };
diff --git a/src/lanes.lua b/src/lanes.lua
index e75e840..6616667 100644
--- a/src/lanes.lua
+++ b/src/lanes.lua
@@ -799,6 +799,7 @@ local configure = function(settings_)
     lanes.null = core.null
     lanes.require = core.require
     lanes.register = core.register
+    lanes.finally = core.finally
     lanes.set_singlethreaded = core.set_singlethreaded
     lanes.set_thread_affinity = core.set_thread_affinity
     lanes.set_thread_priority = core.set_thread_priority
diff --git a/src/state.cpp b/src/state.cpp
index 5a1d2fb..d9f5499 100644
--- a/src/state.cpp
+++ b/src/state.cpp
@@ -209,7 +209,7 @@ static void copy_one_time_settings(Universe* U_, SourceState L1_, DestState L2_)
 
 // #################################################################################################
 
-static constexpr char const* kOnStateCreate{ "on_state_create" };
+static constexpr char const* kOnStateCreate{ "on_state_create" }; // update lanes.lua if the name changes!
 
 void InitializeOnStateCreate(Universe* U_, lua_State* L_)
 {
diff --git a/src/universe.cpp b/src/universe.cpp
index 5794048..3271e70 100644
--- a/src/universe.cpp
+++ b/src/universe.cpp
@@ -197,6 +197,28 @@ void Universe::initializeAllocatorFunction(lua_State* L_)
 
 // #################################################################################################
 
+// should be called ONLY from the state that created the universe
+int Universe::InitializeFinalizer(lua_State* L_)
+{
+    luaL_argcheck(L_, lua_gettop(L_) <= 1, 1, "too many arguments");                               // L_: f?
+    lua_settop(L_, 1);                                                                             // L_: f|nil
+    luaL_argcheck(L_, lua_isnoneornil(L_, 1) || lua_isfunction(L_, 1), 1, "finalizer should be a function");
+
+    // make sure we are only called from the Master Lua State!
+    kUniverseFullRegKey.pushValue(L_);                                                             // L_: f U
+    if (lua_type_as_enum(L_, -1) != LuaType::USERDATA) {
+        raise_luaL_error(L_, "lanes.%s called from inside a lane", kFinally);
+    }
+    lua_pop(L_, 1);                                                                                // L_: f
+    STACK_GROW(L_, 3);
+    // _R[kFinalizerRegKey] = f
+    kFinalizerRegKey.setValue(L_, [](lua_State* L_) { lua_insert(L_, -2); });                      // L_:
+    // no need to adjust the stack, Lua does this for us
+    return 0;
+}
+
+// #################################################################################################
+
 /*
  * Initialize keeper states
  *
@@ -373,9 +395,22 @@ int universe_gc(lua_State* L_)
 {
     lua_Duration const _shutdown_timeout{ lua_tonumber(L_, lua_upvalueindex(1)) };
     std::string_view const _op_string{ lua_tostringview(L_, lua_upvalueindex(2)) };
-    Universe* const _U{ lua_tofulluserdata<Universe>(L_, 1) };
+    STACK_CHECK_START_ABS(L_, 1);
+    Universe* const _U{ lua_tofulluserdata<Universe>(L_, 1) };                                     // L_: U
     _U->terminateFreeRunningLanes(L_, _shutdown_timeout, which_cancel_op(_op_string));
 
+    // invoke the function installed by lanes.finally()
+    kFinalizerRegKey.pushValue(L_);                                                                // L_: U finalizer|nil
+    if (!lua_isnil(L_, -1)) {
+        lua_pcall(L_, 0, 0, 0);                                                                    // L_: U
+        // discard any error that might have occured
+        lua_settop(L_, 1);
+    } else {
+        lua_pop(L_, 1);                                                                            // L_: U
+    }
+    // in case of error, the message is pushed on the stack
+    STACK_CHECK(L_, 1);
+
     // no need to mutex-protect this as all threads in the universe are gone at that point
     if (_U->timerLinda != nullptr) { // test in case some early internal error prevented Lanes from creating the deep timer
         [[maybe_unused]] int const _prev_ref_count{ _U->timerLinda->refcount.fetch_sub(1, std::memory_order_relaxed) };
@@ -389,6 +424,9 @@ int universe_gc(lua_State* L_)
     // remove the protected allocator, if any
     _U->protectedAllocator.removeFrom(L_);
 
+    // no longer found in the registry
+    kUniverseFullRegKey.setValue(L_, [](lua_State* L_) { lua_pushnil(L_); });
+    kUniverseLightRegKey.setValue(L_, [](lua_State* L_) { lua_pushnil(L_); });
     _U->Universe::~Universe();
 
     return 0;
diff --git a/src/universe.h b/src/universe.h
index f5b31a3..4be6a9a 100644
--- a/src/universe.h
+++ b/src/universe.h
@@ -120,6 +120,8 @@ static constexpr RegistryUniqueKey kUniverseLightRegKey{ 0x48BBE9CEAB0BA04Full }
 class Universe
 {
     public:
+    static constexpr char const* kFinally{ "finally" }; // update lanes.lua if the name changes!
+
 #ifdef PLATFORM_LINUX
     // Linux needs to check, whether it's been run as root
     bool const sudo{ geteuid() == 0 };
@@ -180,6 +182,7 @@ class Universe
 
     void closeKeepers();
     void initializeAllocatorFunction(lua_State* L_);
+    static int InitializeFinalizer(lua_State* L_);
     void initializeKeepers(lua_State* L_);
     void terminateFreeRunningLanes(lua_State* L_, lua_Duration shutdownTimeout_, CancelOp op_);
 };
diff --git a/tests/basic.lua b/tests/basic.lua
index cfe6fd5..ab8a080 100644
--- a/tests/basic.lua
+++ b/tests/basic.lua
@@ -485,6 +485,6 @@ end
 
 local nameof_type, nameof_name = lanes.nameof(print)
 PRINT("name of " .. nameof_type .. " print = '" .. nameof_name .. "'")
-
---
-io.stderr:write "Done! :)\n"
+-- install a finalizer that gets called upon Lanes's internal Universe is GCed.
+-- that way, we print our message after anything that can be output by lanes that are still running at that point
+lanes.finally(function() io.stderr:write "\n=======================================\nTEST OK\n" end)
diff --git a/tests/finalizer.lua b/tests/finalizer.lua
index 060e0a6..2acc39d 100644
--- a/tests/finalizer.lua
+++ b/tests/finalizer.lua
@@ -10,20 +10,22 @@
 

 local lanes = require "lanes"

 lanes.configure{with_timers=false}

+local finally = lanes.finally

 

-local FN= "finalizer-test.tmp"

+local FN = "finalizer-test.tmp"

 

 local cleanup

 

-local which= os.time() % 2  -- 0/1

-

-local function lane()

-

+local function lane(error_)

     set_finalizer(cleanup)

 

-    local f,err= io.open(FN,"w")

+    local st,err = pcall(finally, cleanup) -- should cause an error because called from a lane

+    assert(not st, "finally() should have thrown an error")

+    io.stderr:write("finally() raised error '", err, "'\n")

+

+    local f,err = io.open(FN,"w")

     if not f then

-        error( "Could not create "..FN..": "..err )

+        error( "Could not create "..FN..": "..err)

     end

 

     f:write( "Test file that should get removed." )

@@ -32,11 +34,10 @@ local function lane()
     -- don't forget to close the file immediately, else we won't be able to delete it until f is collected

     f:close()

 

-    if which==0 then

-        print "you loose"

-        error("aa")    -- exception here; the value needs NOT be a string

+    if error_ then

+        io.stderr:write("Raising ", tostring(error_), "\n")

+        error(error_, 0)    -- exception here; the value needs NOT be a string

     end

-

     -- no exception

 end

 

@@ -44,8 +45,8 @@ end
 -- This is called at the end of the lane; whether succesful or not.

 -- Gets the 'error()' parameter as parameter ('nil' if normal return).

 --

-cleanup= function(err)

-

+cleanup = function(err)

+    io.stderr:write "------------------------ In Worker Finalizer -----------------------\n"

     -- An error in finalizer will override an error (or success) in the main

     -- chunk.

     --

@@ -57,30 +58,45 @@ cleanup= function(err)
         io.stderr:write( "Cleanup after normal return\n" )

     end

         

-    local _,err2= os.remove(FN)

-    print( "file removal result: ", tostring( err2))

+    local _,err2 = os.remove(FN)

+    io.stderr:write( "file removal result: ", tostring(err2), "\n")

     assert(not err2)    -- if this fails, it will be shown in the calling script

                         -- as an error from the lane itself

     

     io.stderr:write( "Removed file "..FN.."\n" )

 end

 

-local lgen = lanes.gen("*", lane)

+-- we need error_trace_level above "minimal" to get a stack trace out of h:join()

+local lgen = lanes.gen("*", {error_trace_level = "basic"}, lane)

+

+local do_test = function(error_)

 

-io.stderr:write "Launching the lane!\n"

+    io.stderr:write "======================== Launching the lane! =======================\n"

 

-local h= lgen()

+    local h = lgen(error_)

 

-local _,err,stack= h:join()   -- wait for the lane (no automatic error propagation)

-if err then

-    assert(stack)

-    io.stderr:write( "Lane error: "..tostring(err).."\n" )

-    io.stderr:write( "\t", table.concat(stack,"\t\n"), "\n" )

+    local _,err,stack = h:join()   -- wait for the lane (no automatic error propagation)

+    if err then

+        assert(stack, "no stack trace on error, check 'error_trace_level'")

+        io.stderr:write( "Lane error: "..tostring(err).."\n" )

+        io.stderr:write( "\t", table.concat(stack,"\t\n"), "\n" )

+    end

 end

 

-local f= io.open(FN,"r")

-if f then

-    error( "CLEANUP DID NOT WORK: "..FN.." still exists!" )

+do_test(nil)

+do_test("An error")

+

+local on_exit = function()

+    finally(nil)

+    io.stderr:write "=========================In Lanes Finalizer! =======================\n"

+    local f = io.open(FN,"r")

+    if f then

+        error( "CLEANUP DID NOT WORK: "..FN.." still exists!" )

+    else

+        io.stderr:write(FN .. " was successfully removed\n")

+    end

+    io.stderr:write "Finished!\n"

 end

 

-io.stderr:write "Finished!\n"

+-- this function is called after script exit, when the state is closed

+lanes.finally(on_exit)