lanes.finally() handler decides whether to thow or freeze

2 files changed, 17 insertions, 14 deletions

diff --git a/docs/index.html b/docs/index.html
index 1cc007f..0cdf954 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -379,7 +379,7 @@
                         <td>
                                 Sets the duration in seconds Lanes will wait for graceful termination of running lanes at application shutdown. Default is <tt>0.25</tt>.<br />
                                 Lanes signals all lanes for cancellation with <tt>"soft"</tt>, <tt>"hard"</tt>, and <tt>"all"</tt> modes, in that order. Each attempt has <tt>shutdown_timeout</tt> seconds to succeed before the next one.<br />
-                                Then there is a last chance at cleanup with <a href="#finally"><tt>lanes.finally()</tt></a>. If some lanes are still running after that point, shutdown will freeze the application forever. It is YOUR responsibility to cleanup properly after yourself.
+                                Then there is a last chance at cleanup with <a href="#finally"><tt>lanes.finally()</tt></a>. If some lanes are still running after that point, shutdown will either freeze or throw. It is YOUR responsibility to cleanup properly after yourself.
                         </td>
                 </tr>
 
@@ -469,9 +469,10 @@
 <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 got a chance to terminate (see<a href="#shutdown_timeout"><tt>shutdown_timeout</tt></a>), but before lindas become unusable.<br />
+        The finalizer is called unprotected from inside <tt>__gc</tt> metamethod of Lane's Universe. Therefore, if your finalizer raises an error, Lua rules regarding errors in finalizers apply normally.<br />
+        The installed function is called after all free-running lanes got a chance to terminate (see <a href="#shutdown_timeout"><tt>shutdown_timeout</tt></a>), but before lindas become unusable.<br />
         The finalizer receives a single argument, a <tt>bool</tt> indicating whether some Lanes are still running or not at that point. It is possible to inspect them with <a href="#tracking">tracking</a>.<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.
+        If there are still running lanes when the finalizer returns: Lanes will throw a C++ <tt>std::logic_error</tt> if the finalizer returned <tt>"throw"</tt>. Any other value will cause Lanes to freeze forever.
 </p>
 
 <hr/>
diff --git a/src/universe.cpp b/src/universe.cpp
index 5fda29a..04db10f 100644
--- a/src/universe.cpp
+++ b/src/universe.cpp
@@ -427,22 +427,24 @@ LUAG_FUNC(universe_gc)
     kFinalizerRegKey.pushValue(L_);                                                                // L_: U finalizer|nil
     if (!lua_isnil(L_, -1)) {
         lua_pushboolean(L_, _allLanesTerminated);                                                  // L_: U finalizer bool
-        lua_pcall(L_, 1, 0, 0);                                                                    // L_: U
-        // discard any error that might have occured
-        lua_settop(L_, 1);
-    } else {
-        lua_pop(L_, 1);                                                                            // L_: U
+        // no protection. Lua rules for errors in finalizers apply normally
+        lua_call(L_, 1, 1);                                                                        // L_: U ret|error
     }
-    // in case of error, the message is pushed on the stack
-    STACK_CHECK(L_, 1);
+    STACK_CHECK(L_, 2);
+
+    // if some lanes are still running here, we have no other choice than crashing or freezing and let the client figure out what's wrong
+    bool const _throw{ luaG_tostring(L_, -1) == "throw" };
+    lua_pop(L_, 1);                                                                                // L_: U
 
-    // if some lanes are still running here, we have no other choice than crashing and let the client figure out what's wrong
     while (_U->selfdestructFirst != SELFDESTRUCT_END) {
-        throw std::logic_error{ "Some lanes are still running at shutdown" };
-        //std::this_thread::yield();
+        if (_throw) {
+            throw std::logic_error{ "Some lanes are still running at shutdown" };
+        } else {
+            std::this_thread::yield();
+        }
     }
 
-    // no need to mutex-protect this as all threads in the universe are gone at that point
+    // no need to mutex-protect this as all lanes 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) };
         LUA_ASSERT(L_, _prev_ref_count == 1); // this should be the last reference