Keeper management modernisation and improvements

* use a std::variant to manage the distinction between one or more keeper states. Use std::unique_ptr<Keeper[]> to manage the multiple keeper case.
* setting "nb_keepers" renamed "nb_user_keepers", to indicate these are in addition to internal keeper #0 used for timers.
* stricter lanes.linda() argument checking. group is imposed if more than one keeper is used.
* more tests

10 files changed, 361 insertions, 230 deletions

diff --git a/src/keeper.cpp b/src/keeper.cpp
index ff5fe26..ea924e8 100644
--- a/src/keeper.cpp
+++ b/src/keeper.cpp
@@ -40,6 +40,7 @@
 #include "keeper.h"
 
 #include "intercopycontext.h"
+#include "lane.h"
 #include "linda.h"
 #include "state.h"
 
@@ -548,22 +549,20 @@ int keepercall_count(lua_State* L_)
 
 Keeper* Linda::acquireKeeper() const
 {
-    int const _nbKeepers{ U->keepers->nb_keepers };
-    // can be 0 if this happens during main state shutdown (lanes is being GC'ed -> no keepers)
-    if (_nbKeepers) {
-        Keeper* const _K{ &U->keepers->keeper_array[keeperIndex] };
+    // can be nullptr if this happens during main state shutdown (lanes is being GC'ed -> no keepers)
+    Keeper* const _K{ whichKeeper() };
+    if (_K) {
         _K->mutex.lock();
-        return _K;
     }
-    return nullptr;
+    return _K;
 }
 
 // #################################################################################################
 
-void Linda::releaseKeeper(Keeper* K_) const
+void Linda::releaseKeeper(Keeper* const K_) const
 {
     if (K_) { // can be nullptr if we tried to acquire during shutdown
-        assert(K_ == &U->keepers->keeper_array[keeperIndex]);
+        assert(K_ == whichKeeper());
         K_->mutex.unlock();
     }
 }
@@ -595,16 +594,16 @@ KeeperCallResult keeper_call(KeeperState K_, keeper_api_t func_, lua_State* L_,
         (InterCopyContext{ linda_->U, DestState{ K_ }, SourceState{ L_ }, {}, {}, {}, LookupMode::ToKeeper, {} }.inter_copy(_args) == InterCopyResult::Success)
     ) {                                                                                            // L: ... args...                                  K_: func_ linda args...
         lua_call(K_, 1 + _args, LUA_MULTRET);                                                      // L: ... args...                                  K_: result...
-        int const retvals{ lua_gettop(K_) - _top_K };
+        int const _retvals{ lua_gettop(K_) - _top_K };
         // note that this can raise a lua error while the keeper state (and its mutex) is acquired
         // this may interrupt a lane, causing the destruction of the underlying OS thread
         // after this, another lane making use of this keeper can get an error code from the mutex-locking function
         // when attempting to grab the mutex again (WINVER <= 0x400 does this, but locks just fine, I don't know about pthread)
         if (
-            (retvals == 0) ||
-            (InterCopyContext{ linda_->U, DestState{ L_ }, SourceState{ K_ }, {}, {}, {}, LookupMode::FromKeeper, {} }.inter_move(retvals) == InterCopyResult::Success)
+            (_retvals == 0) ||
+            (InterCopyContext{ linda_->U, DestState{ L_ }, SourceState{ K_ }, {}, {}, {}, LookupMode::FromKeeper, {} }.inter_move(_retvals) == InterCopyResult::Success)
         ) {                                                                                        // L: ... args... result...                        K_: result...
-            _result.emplace(retvals);
+            _result.emplace(_retvals);
         }
     }
     // whatever happens, restore the stack to where it was at the origin
@@ -613,7 +612,7 @@ KeeperCallResult keeper_call(KeeperState K_, keeper_api_t func_, lua_State* L_,
     // don't do this for this particular function, as it is only called during Linda destruction, and we don't want to raise an error, ever
     if (func_ != KEEPER_API(clear)) [[unlikely]] {
         // since keeper state GC is stopped, let's run a step once in a while if required
-        int const _gc_threshold{ linda_->U->keepers->gc_threshold };
+        int const _gc_threshold{ linda_->U->keepers.gc_threshold };
         if (_gc_threshold == 0) [[unlikely]] {
             lua_gc(K_, LUA_GCSTEP, 0);
         } else if (_gc_threshold > 0) [[likely]] {
@@ -632,8 +631,215 @@ KeeperCallResult keeper_call(KeeperState K_, keeper_api_t func_, lua_State* L_,
 }
 
 // #################################################################################################
+// #################################################################################################
+// Keeper
+// #################################################################################################
+// #################################################################################################
 
-void Keepers::CreateFifosTable(lua_State* L_)
+void* Keeper::operator new[](size_t size_, Universe* U_) noexcept
 {
-    kFifosRegKey.setValue(L_, [](lua_State* L_) { lua_newtable(L_); });
+    // size_ is the memory for the element count followed by the elements themselves
+    return U_->internalAllocator.alloc(size_);
+}
+
+// #################################################################################################
+
+// can't actually delete the operator because the compiler generates stack unwinding code that could call it in case of exception
+void Keeper::operator delete[](void* p_, Universe* U_)
+{
+    U_->internalAllocator.free(p_, *static_cast<size_t*>(p_) * sizeof(Keeper) + sizeof(size_t));
+}
+
+// #################################################################################################
+// #################################################################################################
+// Keepers
+// #################################################################################################
+// #################################################################################################
+
+void Keepers::DeleteKV::operator()(Keeper* k_) const
+{
+    for (Keeper& _k : std::views::counted(k_, count)) {
+        _k.~Keeper();
+    }
+    // operator[] returns the result of the allocation shifted by a size_t (the hidden element count)
+    U->internalAllocator.free(reinterpret_cast<size_t*>(k_) - 1, count * sizeof(Keeper));
+}
+
+// #################################################################################################
+/*
+ * Initialize keeper states
+ *
+ * If there is a problem, returns nullptr and pushes the error message on the stack
+ * else returns the keepers bookkeeping structure.
+ *
+ * Note: Any problems would be design flaws; the created Lua state is left
+ *       unclosed, because it does not really matter. In production code, this
+ *       function never fails.
+ * settings table is expected at position 1 on the stack
+ */
+
+void Keepers::initialize(Universe& U_, lua_State* L_, int const nbKeepers_, int const gc_threshold_)
+{
+    gc_threshold = gc_threshold_;
+
+    auto _initOneKeeper = [U = &U_, L = L_, gc_threshold = gc_threshold](Keeper& keeper_, int const i_) {
+        STACK_CHECK_START_REL(L, 0);
+        // note that we will leak K if we raise an error later
+        KeeperState const _K{ state::CreateState(U, L) };                                          // L: settings                                    K:
+        if (_K == nullptr) {
+            raise_luaL_error(L, "out of memory while creating keeper states");
+        }
+
+        keeper_.L = _K;
+
+        // Give a name to the state
+        lua_pushfstring(_K, "Keeper #%d", i_ + 1);                                                 // L: settings                                    K: "Keeper #n"
+        if constexpr (HAVE_DECODA_SUPPORT()) {
+            lua_pushvalue(_K, -1);                                                                 //                                                K: "Keeper #n" Keeper #n"
+            lua_setglobal(_K, "decoda_name");                                                      // L: settings                                    K: "Keeper #n"
+        }
+        kLaneNameRegKey.setValue(_K, [](lua_State* L_) { lua_insert(L_, -2); });                   //                                                K:
+
+        STACK_CHECK_START_ABS(_K, 0);
+
+        // copy the universe pointer in the keeper itself
+        Universe::Store(_K, U);
+        STACK_CHECK(_K, 0);
+
+        // make sure 'package' is initialized in keeper states, so that we have require()
+        // this because this is needed when transferring deep userdata object
+        luaL_requiref(_K, LUA_LOADLIBNAME, luaopen_package, 1);                                    // L: settings                                    K: package
+        lua_pop(_K, 1);                                                                            // L: settings                                    K:
+        STACK_CHECK(_K, 0);
+        tools::SerializeRequire(_K);
+        STACK_CHECK(_K, 0);
+
+        // copy package.path and package.cpath from the source state
+        if (luaG_getmodule(L, LUA_LOADLIBNAME) != LuaType::NIL) {                                  // L: settings package                            K:
+            // when copying with mode LookupMode::ToKeeper, error message is pushed at the top of the stack, not raised immediately
+            InterCopyContext _c{ U, DestState{ _K }, SourceState{ L }, {}, SourceIndex{ lua_absindex(L, -1) }, {}, LookupMode::ToKeeper, {} };
+            if (_c.inter_copy_package() != InterCopyResult::Success) {                             // L: settings ... error_msg                      K:
+                // if something went wrong, the error message is at the top of the stack
+                lua_remove(L, -2);                                                                 // L: settings error_msg
+                raise_lua_error(L);
+            }
+        }
+        lua_pop(L, 1);                                                                             // L: settings                                    K:
+        STACK_CHECK(L, 0);
+        STACK_CHECK(_K, 0);
+
+        // attempt to call on_state_create(), if we have one and it is a C function
+        // (only support a C function because we can't transfer executable Lua code in keepers)
+        // will raise an error in L_ in case of problem
+        state::CallOnStateCreate(U, _K, L, LookupMode::ToKeeper);
+
+        // create the fifos table in the keeper state
+        kFifosRegKey.setValue(_K, [](lua_State* L_) { lua_newtable(L_); });
+        STACK_CHECK(_K, 0);
+
+        // configure GC last
+        if (gc_threshold >= 0) {
+            lua_gc(_K, LUA_GCSTOP, 0);
+        }
+    };
+
+    switch (nbKeepers_) {
+    case 0:
+        break;
+
+    case 1:
+        keeper_array.emplace<Keeper>();
+        _initOneKeeper(std::get<Keeper>(keeper_array), 0);
+        break;
+
+    default:
+        KV& _kv = keeper_array.emplace<KV>(
+            std::unique_ptr<Keeper[], DeleteKV>{ new(&U_) Keeper[nbKeepers_], DeleteKV{ &U_, nbKeepers_ } },
+            nbKeepers_
+        );
+        for (int const _i : std::ranges::iota_view{ 0, nbKeepers_ }) {
+            _initOneKeeper(_kv.keepers[_i], _i);
+        }
+    }
+}
+
+// #################################################################################################
+
+void Keepers::close()
+{
+    if (isClosing.test_and_set(std::memory_order_release)) {
+        assert(false); // should never close more than once in practice
+        return;
+    }
+
+    if (std::holds_alternative<std::monostate>(keeper_array)) {
+        return;
+    }
+
+    auto _closeOneKeeper = [](Keeper& keeper_)
+    {
+        lua_State* const _K{ std::exchange(keeper_.L, KeeperState{ nullptr }) };
+        if (_K) {
+            lua_close(_K);
+        }
+        return _K ? true : false;
+    };
+
+    if (std::holds_alternative<Keeper>(keeper_array)) {
+        _closeOneKeeper(std::get<Keeper>(keeper_array));
+    } else {
+        KV& _kv = std::get<KV>(keeper_array);
+
+        // NOTE: imagine some keeper state N+1 currently holds a linda that uses another keeper N, and a _gc that will make use of it
+        // when keeper N+1 is closed, object is GCed, linda operation is called, which attempts to acquire keeper N, whose Lua state no longer exists
+        // in that case, the linda operation should do nothing. which means that these operations must check for keeper acquisition success
+        // which is early-outed with a keepers->nbKeepers null-check
+        size_t const _nbKeepers{ std::exchange(_kv.nbKeepers, 0) };
+        for (size_t const _i : std::ranges::iota_view{ size_t{ 0 }, _nbKeepers }) {
+            if (!_closeOneKeeper(_kv.keepers[_i])) {
+                // detected partial init: destroy only the mutexes that got initialized properly
+                break;
+            }
+        }
+    }
+
+    keeper_array.emplace<std::monostate>();
+}
+
+// #################################################################################################
+
+[[nodiscard]] Keeper* Keepers::getKeeper(int idx_)
+{
+    if (isClosing.test(std::memory_order_acquire)) {
+        return nullptr;
+    }
+
+    if (std::holds_alternative<std::monostate>(keeper_array)) {
+        return nullptr;
+    }
+
+    if (std::holds_alternative<Keeper>(keeper_array)) {
+        return &std::get<Keeper>(keeper_array);
+    }
+
+    return &std::get<KV>(keeper_array).keepers.get()[idx_];
+}
+
+// #################################################################################################
+
+[[nodiscard]] int Keepers::getNbKeepers() const
+{
+    if (isClosing.test(std::memory_order_acquire)) {
+        return 0;
+    }
+
+    if (std::holds_alternative<std::monostate>(keeper_array)) {
+        return 0;
+    }
+
+    if (std::holds_alternative<Keeper>(keeper_array)) {
+        return 1;
+    }
+
+    return static_cast<int>(std::get<KV>(keeper_array).nbKeepers);
 }
diff --git a/src/keeper.h b/src/keeper.h
index a902caa..682c710 100644
--- a/src/keeper.h
+++ b/src/keeper.h
@@ -11,8 +11,10 @@ extern "C"
 
 #include "uniquekey.h"
 
-#include <optional>
+#include <atomic>
 #include <mutex>
+#include <optional>
+#include <variant>
 
 // forwards
 class Linda;
@@ -21,22 +23,63 @@ class Universe;
 
 using KeeperState = Unique<lua_State*>;
 
+// #################################################################################################
+
 struct Keeper
 {
     std::mutex mutex;
     KeeperState L{ nullptr };
-    // int count;
+
+    [[nodiscard]] static void* operator new[](size_t size_, Universe* U_) noexcept;
+    // can't actually delete the operator because the compiler generates stack unwinding code that could call it in case of exception
+    static void operator delete[](void* p_, Universe* U_);
+
+
+    ~Keeper() = default;
+    Keeper() = default;
+    // non-copyable, non-movable
+    Keeper(Keeper const&) = delete;
+    Keeper(Keeper const&&) = delete;
+    Keeper& operator=(Keeper const&) = delete;
+    Keeper& operator=(Keeper const&&) = delete;
 };
 
+// #################################################################################################
+
 struct Keepers
 {
+    private:
+    struct DeleteKV
+    {
+        Universe* U{};
+        int count{};
+        void operator()(Keeper* k_) const;
+    };
+    // can't use std::vector<Keeper> because Keeper contains a mutex, so we need a raw memory buffer
+    struct KV
+    {
+        std::unique_ptr<Keeper[], DeleteKV> keepers{};
+        size_t nbKeepers{};
+    };
+    std::variant<std::monostate, Keeper, KV> keeper_array;
+    std::atomic_flag isClosing;
+
+    public:
     int gc_threshold{ 0 };
-    int nb_keepers{ 0 };
-    Keeper keeper_array[1];
 
-    static void CreateFifosTable(lua_State* L_);
+    public:
+    // can only be instanced as a data member
+    static void* operator new(size_t size_) = delete;
+
+    Keepers() = default;
+    void close();
+    [[nodiscard]] Keeper* getKeeper(int idx_);
+    [[nodiscard]] int getNbKeepers() const;
+    void initialize(Universe& U_, lua_State* L_, int nbKeepers_, int gc_threshold_);
 };
 
+// #################################################################################################
+
 // xxh64 of string "kNilSentinel" generated at https://www.pelock.com/products/hash-calculator
 static constexpr UniqueKey kNilSentinel{ 0xC457D4EDDB05B5E4ull, "lanes.null" };
 
diff --git a/src/lane.cpp b/src/lane.cpp
index 22147f1..029efdb 100644
--- a/src/lane.cpp
+++ b/src/lane.cpp
@@ -811,7 +811,7 @@ void Lane::changeDebugName(int const nameIdx_)
     kLaneNameRegKey.setValue(L, [idx = _nameIdx](lua_State* L_) { lua_pushvalue(L_, idx); });      // L: ... "name" ...
     // keep a direct pointer on the string
     debugName = lua_tostringview(L, _nameIdx);
-    if constexpr (HAVE_DECODA_NAME()) {
+    if constexpr (HAVE_DECODA_SUPPORT()) {
         // to see VM name in Decoda debugger Virtual Machine window
         lua_pushvalue(L, _nameIdx);                                                                // L: ... "name" ... "name"
         lua_setglobal(L, "decoda_name");                                                           // L: ... "name" ...
diff --git a/src/lanes.cpp b/src/lanes.cpp
index b74e9ec..4b4f9a8 100644
--- a/src/lanes.cpp
+++ b/src/lanes.cpp
@@ -637,50 +637,11 @@ LUAG_FUNC(configure)
     DEBUGSPEW_CODE(DebugSpewIndentScope _scope{ _U });
 
     if (_U == nullptr) {
-        _U = Universe::Create(L_);                                                                 // L_: settings universe
-        DEBUGSPEW_CODE(DebugSpewIndentScope _scope2{ _U });
-        lua_createtable(L_, 0, 1);                                                                 // L_: settings universe {mt}
-        std::ignore = luaG_getfield(L_, 1, "shutdown_timeout");                                    // L_: settings universe {mt} shutdown_timeout
-        std::ignore = luaG_getfield(L_, 1, "shutdown_mode");                                       // L_: settings universe {mt} shutdown_timeout shutdown_mode
-        lua_pushcclosure(L_, LG_universe_gc, 2);                                                   // L_: settings universe {mt} LG_universe_gc
-        lua_setfield(L_, -2, "__gc");                                                              // L_: settings universe {mt}
-        lua_setmetatable(L_, -2);                                                                  // L_: settings universe
-        lua_pop(L_, 1);                                                                            // L_: settings
-        std::ignore = luaG_getfield(L_, 1, "verbose_errors");                                      // L_: settings verbose_errors
-        _U->verboseErrors = lua_toboolean(L_, -1) ? true : false;
-        lua_pop(L_, 1);                                                                            // L_: settings
-        std::ignore = luaG_getfield(L_, 1, "demote_full_userdata");                                // L_: settings demote_full_userdata
-        _U->demoteFullUserdata = lua_toboolean(L_, -1) ? true : false;
-        lua_pop(L_, 1);                                                                            // L_: settings
-
-        // tracking
-        std::ignore = luaG_getfield(L_, 1, "track_lanes");                                         // L_: settings track_lanes
-        if (lua_toboolean(L_, -1)) {
-            _U->tracker.activate();
-        }
-        lua_pop(L_, 1);                                                                            // L_: settings
-
-        // Linked chains handling
-        _U->selfdestructFirst = SELFDESTRUCT_END;
-        _U->initializeAllocatorFunction(L_);
-        state::InitializeOnStateCreate(_U, L_);
-        _U->initializeKeepers(L_);
-        STACK_CHECK(L_, 1);
-
-        // Initialize 'timerLinda'; a common Linda object shared by all states
-        lua_pushcfunction(L_, LG_linda);                                                           // L_: settings lanes.linda
-        lua_pushliteral(L_, "lanes-timer");                                                        // L_: settings lanes.linda "lanes-timer"
-        lua_call(L_, 1, 1);                                                                        // L_: settings linda
-        STACK_CHECK(L_, 2);
-
-        // Proxy userdata contents is only a 'DeepPrelude*' pointer
-        _U->timerLinda = *lua_tofulluserdata<DeepPrelude*>(L_, -1);
-        // increment refcount so that this linda remains alive as long as the universe exists.
-        _U->timerLinda->refcount.fetch_add(1, std::memory_order_relaxed);
-        lua_pop(L_, 1);                                                                            // L_: settings
         // store a hidden reference in the registry to make sure the string is kept around even if a lane decides to manually change the "decoda_name" global...
         kLaneNameRegKey.setValue(L_, [](lua_State* L_) { std::ignore = lua_pushstringview(L_, "main"); });
 
+        // create the universe
+        _U = Universe::Create(L_);                                                                 // L_: settings universe
     }
     STACK_CHECK(L_, 1);
 
diff --git a/src/lanes.lua b/src/lanes.lua
index e7763b1..1c36b46 100644
--- a/src/lanes.lua
+++ b/src/lanes.lua
@@ -90,7 +90,7 @@ local isLuaJIT = (package and package.loaded.jit and jit.version) and true or fa
 
 local default_params =
 {
-    nb_keepers = 1,
+    nb_user_keepers = 0,
     keepers_gc_threshold = -1,
     on_state_create = nil,
     shutdown_timeout = 0.25,
@@ -114,9 +114,9 @@ end
 
 local param_checkers =
 {
-    nb_keepers = function(val_)
-        -- nb_keepers should be a number in [1,100] (so that nobody tries to run OOM by specifying a huge amount)
-        return type(val_) == "number" and val_ > 0 and val_ <= 100
+    nb_user_keepers = function(val_)
+        -- nb_user_keepers should be a number in [0,100] (so that nobody tries to run OOM by specifying a huge amount)
+        return type(val_) == "number" and val_ >= 0 and val_ <= 100
     end,
     keepers_gc_threshold = function(val_)
         -- keepers_gc_threshold should be a number
@@ -176,7 +176,7 @@ local params_checker = function(settings_)
             param = default_params[key]
         end
         if not checker(param) then
-            error("Bad " .. key .. ": " .. tostring(param), 2)
+            error("Bad parameter " .. key .. ": " .. tostring(param), 2)
         end
         settings[key] = param
     end
diff --git a/src/lanesconf.h b/src/lanesconf.h
index 2df7a71..938d743 100644
--- a/src/lanesconf.h
+++ b/src/lanesconf.h
@@ -42,4 +42,4 @@
 #endif // (defined PLATFORM_WIN32) || (defined PLATFORM_POCKETPC)
 
 #define USE_DEBUG_SPEW() 0
-#define HAVE_DECODA_NAME() 0
+#define HAVE_DECODA_SUPPORT() 0
diff --git a/src/linda.cpp b/src/linda.cpp
index 76cd347..f8d6cdc 100644
--- a/src/linda.cpp
+++ b/src/linda.cpp
@@ -109,15 +109,10 @@ template <bool OPT>
 // #################################### Linda implementation #######################################
 // #################################################################################################
 
-// Any hashing will do that maps pointers to [0..Universe::nb_keepers[ consistently.
-// Pointers are often aligned by 8 or so - ignore the low order bits
-// have to cast to unsigned long to avoid compilation warnings about loss of data when converting pointer-to-integer
-static constexpr uintptr_t kPointerMagicShift{ 3 };
-
 Linda::Linda(Universe* U_, LindaGroup group_, std::string_view const& name_)
 : DeepPrelude{ LindaFactory::Instance }
 , U{ U_ }
-, keeperIndex{ (group_ ? group_ : static_cast<int>(std::bit_cast<uintptr_t>(this) >> kPointerMagicShift)) % U_->keepers->nb_keepers }
+, keeperIndex{ group_ % U_->keepers.getNbKeepers() }
 {
     setName(name_);
 }
@@ -733,6 +728,7 @@ LUAG_FUNC(linda_tostring)
 
 // #################################################################################################
 
+#if HAVE_DECODA_SUPPORT()
 /*
  * table/string = linda:__towatch()
  * return a table listing all pending data inside the linda, or the stringified linda if empty
@@ -748,6 +744,8 @@ LUAG_FUNC(linda_towatch)
     return _pushed;
 }
 
+#endif // HAVE_DECODA_SUPPORT()
+
 // #################################################################################################
 
 namespace {
@@ -755,7 +753,9 @@ namespace {
         static luaL_Reg const sLindaMT[] = {
             { "__concat", LG_linda_concat },
             { "__tostring", LG_linda_tostring },
+#if HAVE_DECODA_SUPPORT()
             { "__towatch", LG_linda_towatch }, // Decoda __towatch support
+#endif // HAVE_DECODA_SUPPORT()
             { "cancel", LG_linda_cancel },
             { "count", LG_linda_count },
             { "deep", LG_linda_deep },
@@ -784,13 +784,24 @@ namespace {
 LUAG_FUNC(linda)
 {
     int const _top{ lua_gettop(L_) };
+    int _groupIdx{};
     luaL_argcheck(L_, _top <= 2, _top, "too many arguments");
     if (_top == 1) {
         LuaType const _t{ lua_type_as_enum(L_, 1) };
-        luaL_argcheck(L_, _t == LuaType::STRING || _t == LuaType::NUMBER, 1, "wrong parameter (should be a string or a number)");
+        int const _nameIdx{ (_t == LuaType::STRING) ? 1 : 0 };
+        _groupIdx = (_t == LuaType::NUMBER) ? 1 : 0;
+        luaL_argcheck(L_, _nameIdx || _groupIdx, 1, "wrong parameter (should be a string or a number)");
     } else if (_top == 2) {
         luaL_checktype(L_, 1, LUA_TSTRING);
         luaL_checktype(L_, 2, LUA_TNUMBER);
+        _groupIdx = 2;
+    }
+    int const _nbKeepers{ Universe::Get(L_)->keepers.getNbKeepers() };
+    if (!_groupIdx) {
+        luaL_argcheck(L_, _nbKeepers < 2, 0, "there are multiple keepers, you must specify a group");
+    } else {
+        int const _group{ static_cast<int>(lua_tointeger(L_, _groupIdx)) };
+        luaL_argcheck(L_, _group >= 0 && _group < _nbKeepers, _groupIdx, "group out of range");
     }
     return LindaFactory::Instance.pushDeepUserdata(DestState{ L_ }, 0);
 }
diff --git a/src/linda.h b/src/linda.h
index 3545544..5753258 100644
--- a/src/linda.h
+++ b/src/linda.h
@@ -38,7 +38,6 @@ class Linda
     CancelRequest cancelRequest{ CancelRequest::None };
 
     public:
-    // a fifo full userdata has one uservalue, the table that holds the actual fifo contents
     [[nodiscard]] static void* operator new(size_t size_, Universe* U_) noexcept { return U_->internalAllocator.alloc(size_); }
     // always embedded somewhere else or "in-place constructed" as a full userdata
     // can't actually delete the operator because the compiler generates stack unwinding code that could call it in case of exception
@@ -64,5 +63,5 @@ class Linda
     [[nodiscard]] std::string_view getName() const;
     void releaseKeeper(Keeper* keeper_) const;
     [[nodiscard]] static int ProtectedCall(lua_State* L_, lua_CFunction f_);
-    [[nodiscard]] Keeper* whichKeeper() const { return U->keepers->nb_keepers ? &U->keepers->keeper_array[keeperIndex] : nullptr; }
+    [[nodiscard]] Keeper* whichKeeper() const { return U->keepers.getKeeper(keeperIndex); }
 };
diff --git a/src/universe.cpp b/src/universe.cpp
index 55c3e69..2e7fd55 100644
--- a/src/universe.cpp
+++ b/src/universe.cpp
@@ -38,6 +38,8 @@ THE SOFTWARE.
 
 #include <ranges>
 
+extern LUAG_FUNC(linda);
+
 // #################################################################################################
 
 // xxh64 of string "kUniverseFullRegKey" generated at https://www.pelock.com/products/hash-calculator
@@ -77,12 +79,68 @@ Universe::Universe()
 [[nodiscard]] Universe* Universe::Create(lua_State* const L_)
 {
     LUA_ASSERT(L_, Universe::Get(L_) == nullptr);
-    STACK_CHECK_START_REL(L_, 0);
-    Universe* const _U{ new (L_) Universe{} };                                                     // L_: universe
+    LUA_ASSERT(L_, lua_gettop(L_) == 1 && lua_istable(L_, 1));
+    STACK_CHECK_START_REL(L_, 0);                                                                  // L_: settings
+    std::ignore = luaG_getfield(L_, 1, "nb_user_keepers");                                         // L_: settings nb_user_keepers
+    int const _nbUserKeepers{ static_cast<int>(lua_tointeger(L_, -1)) + 1};
+    lua_pop(L_, 1);                                                                                // L_: settings
+    if (_nbUserKeepers < 1) {
+        raise_luaL_error(L_, "Bad number of additional keepers (%d)", _nbUserKeepers);
+    }
+    STACK_CHECK(L_, 0);
+    std::ignore = luaG_getfield(L_, 1, "keepers_gc_threshold");                                    // L_: settings keepers_gc_threshold
+    int const _keepers_gc_threshold{ static_cast<int>(lua_tointeger(L_, -1)) };
+    lua_pop(L_, 1);                                                                                // L_: settings
+    STACK_CHECK(L_, 0);
+
+    Universe* const _U{ new (L_) Universe{} };                                                     // L_: settings universe
     STACK_CHECK(L_, 1);
     kUniverseFullRegKey.setValue(L_, [](lua_State* L_) { lua_pushvalue(L_, -2); });
     kUniverseLightRegKey.setValue(L_, [U = _U](lua_State* L_) { lua_pushlightuserdata(L_, U); });
+    STACK_CHECK(L_, 1);                                                                            // L_: settings
+
+    DEBUGSPEW_CODE(DebugSpewIndentScope _scope{ _U });
+    lua_createtable(L_, 0, 1);                                                                     // L_: settings universe {mt}
+    std::ignore = luaG_getfield(L_, 1, "shutdown_timeout");                                        // L_: settings universe {mt} shutdown_timeout
+    std::ignore = luaG_getfield(L_, 1, "shutdown_mode");                                           // L_: settings universe {mt} shutdown_timeout shutdown_mode
+    lua_pushcclosure(L_, LG_universe_gc, 2);                                                       // L_: settings universe {mt} LG_universe_gc
+    lua_setfield(L_, -2, "__gc");                                                                  // L_: settings universe {mt}
+    lua_setmetatable(L_, -2);                                                                      // L_: settings universe
+    lua_pop(L_, 1);                                                                                // L_: settings
+    std::ignore = luaG_getfield(L_, 1, "verbose_errors");                                          // L_: settings verbose_errors
+    _U->verboseErrors = lua_toboolean(L_, -1) ? true : false;
+    lua_pop(L_, 1);                                                                                // L_: settings
+    std::ignore = luaG_getfield(L_, 1, "demote_full_userdata");                                    // L_: settings demote_full_userdata
+    _U->demoteFullUserdata = lua_toboolean(L_, -1) ? true : false;
+    lua_pop(L_, 1);                                                                                // L_: settings
+
+    // tracking
+    std::ignore = luaG_getfield(L_, 1, "track_lanes");                                             // L_: settings track_lanes
+    if (lua_toboolean(L_, -1)) {
+        _U->tracker.activate();
+    }
+    lua_pop(L_, 1);                                                                                // L_: settings
+
+    // Linked chains handling
+    _U->selfdestructFirst = SELFDESTRUCT_END;
+    _U->initializeAllocatorFunction(L_);
+    state::InitializeOnStateCreate(_U, L_);
+    _U->keepers.initialize(*_U, L_, _nbUserKeepers, _keepers_gc_threshold);
+    STACK_CHECK(L_, 0);
+
+    // Initialize 'timerLinda'; a common Linda object shared by all states
+    lua_pushcfunction(L_, LG_linda);                                                               // L_: settings lanes.linda
+    std::ignore = lua_pushstringview(L_, "lanes-timer");                                           // L_: settings lanes.linda "lanes-timer"
+    lua_pushinteger(L_, 0);                                                                        // L_: settings lanes.linda "lanes-timer" 0
+    lua_call(L_, 2, 1);                                                                            // L_: settings linda
     STACK_CHECK(L_, 1);
+
+    // Proxy userdata contents is only a 'DeepPrelude*' pointer
+    _U->timerLinda = *lua_tofulluserdata<DeepPrelude*>(L_, -1);
+    // increment refcount so that this linda remains alive as long as the universe exists.
+    _U->timerLinda->refcount.fetch_add(1, std::memory_order_relaxed);
+    lua_pop(L_, 1);                                                                                // L_: settings
+    STACK_CHECK(L_, 0);
     return _U;
 }
 
@@ -113,45 +171,6 @@ Universe::Universe()
 
 // #################################################################################################
 
-/*
- * Pool of keeper states
- *
- * Access to keeper states is locked (only one OS thread at a time) so the
- * bigger the pool, the less chances of unnecessary waits. Lindas map to the
- * keepers randomly, by a hash.
- */
-
-// called as __gc for the keepers array userdata
-void Universe::closeKeepers()
-{
-    if (keepers != nullptr) {
-        int _nbKeepers{ keepers->nb_keepers };
-        // NOTE: imagine some keeper state N+1 currently holds a linda that uses another keeper N, and a _gc that will make use of it
-        // when keeper N+1 is closed, object is GCed, linda operation is called, which attempts to acquire keeper N, whose Lua state no longer exists
-        // in that case, the linda operation should do nothing. which means that these operations must check for keeper acquisition success
-        // which is early-outed with a keepers->nbKeepers null-check
-        keepers->nb_keepers = 0;
-        for (int const _i : std::ranges::iota_view{ 0, _nbKeepers }) {
-            lua_State* const _K{ keepers->keeper_array[_i].L };
-            keepers->keeper_array[_i].L = KeeperState{ nullptr };
-            if (_K != nullptr) {
-                lua_close(_K);
-            } else {
-                // detected partial init: destroy only the mutexes that got initialized properly
-                _nbKeepers = _i;
-            }
-        }
-        for (int const _i : std::ranges::iota_view{ 0, _nbKeepers }) {
-            keepers->keeper_array[_i].~Keeper();
-        }
-        // free the keeper bookkeeping structure
-        internalAllocator.free(keepers, sizeof(Keepers) + (_nbKeepers - 1) * sizeof(Keeper));
-        keepers = nullptr;
-    }
-}
-
-// #################################################################################################
-
 // called once at the creation of the universe (therefore L_ is the master Lua state everything originates from)
 // Do I need to disable this when compiling for LuaJIT to prevent issues?
 void Universe::initializeAllocatorFunction(lua_State* const L_)
@@ -224,113 +243,6 @@ int Universe::InitializeFinalizer(lua_State* const L_)
 
 // #################################################################################################
 
-/*
- * Initialize keeper states
- *
- * If there is a problem, returns nullptr and pushes the error message on the stack
- * else returns the keepers bookkeeping structure.
- *
- * Note: Any problems would be design flaws; the created Lua state is left
- *       unclosed, because it does not really matter. In production code, this
- *       function never fails.
- * settings table is expected at position 1 on the stack
- */
-void Universe::initializeKeepers(lua_State* const L_)
-{
-    LUA_ASSERT(L_, lua_gettop(L_) == 1 && lua_istable(L_, 1));
-    STACK_CHECK_START_REL(L_, 0);                                                                  // L_: settings
-    std::ignore = luaG_getfield(L_, 1, "nb_keepers");                                              // L_: settings nb_keepers
-    int const _nb_keepers{ static_cast<int>(lua_tointeger(L_, -1)) };
-    lua_pop(L_, 1);                                                                                // L_: settings
-    if (_nb_keepers < 1) {
-        raise_luaL_error(L_, "Bad number of keepers (%d)", _nb_keepers);
-    }
-    STACK_CHECK(L_, 0);
-
-    std::ignore = luaG_getfield(L_, 1, "keepers_gc_threshold");                                    // L_: settings keepers_gc_threshold
-    int const keepers_gc_threshold{ static_cast<int>(lua_tointeger(L_, -1)) };
-    lua_pop(L_, 1);                                                                                // L_: settings
-    STACK_CHECK(L_, 0);
-
-    // Keepers contains an array of 1 Keeper, adjust for the actual number of keeper states
-    {
-        size_t const _bytes{ sizeof(Keepers) + (_nb_keepers - 1) * sizeof(Keeper) };
-        keepers = static_cast<Keepers*>(internalAllocator.alloc(_bytes));
-        if (keepers == nullptr) {
-            raise_luaL_error(L_, "out of memory while creating keepers");
-        }
-        keepers->Keepers::Keepers();
-        keepers->gc_threshold = keepers_gc_threshold;
-        keepers->nb_keepers = _nb_keepers;
-
-        // we have to manually call the Keeper constructor on the additional array slots
-        for (int const _i : std::ranges::iota_view{ 1, _nb_keepers }) {
-            new (&keepers->keeper_array[_i]) Keeper{}; // placement new
-        }
-    }
-
-    for (int const _i : std::ranges::iota_view{ 0, _nb_keepers }) {
-        // note that we will leak K if we raise an error later
-        KeeperState const _K{ state::CreateState(this, L_) };                                      // L_: settings                                    K:
-        if (_K == nullptr) {
-            raise_luaL_error(L_, "out of memory while creating keeper states");
-        }
-
-        keepers->keeper_array[_i].L = _K;
-
-        if (keepers->gc_threshold >= 0) {
-            lua_gc(_K, LUA_GCSTOP, 0);
-        }
-
-        STACK_CHECK_START_ABS(_K, 0);
-
-        // copy the universe pointer in the keeper itself
-        Universe::Store(_K, this);
-        STACK_CHECK(_K, 0);
-
-        // make sure 'package' is initialized in keeper states, so that we have require()
-        // this because this is needed when transferring deep userdata object
-        luaL_requiref(_K, LUA_LOADLIBNAME, luaopen_package, 1);                                    // L_: settings                                    K: package
-        lua_pop(_K, 1);                                                                            // L_: settings                                    K:
-        STACK_CHECK(_K, 0);
-        tools::SerializeRequire(_K);
-        STACK_CHECK(_K, 0);
-
-        // copy package.path and package.cpath from the source state
-        if (luaG_getmodule(L_, LUA_LOADLIBNAME) != LuaType::NIL) {                                 // L_: settings package                            K:
-            // when copying with mode LookupMode::ToKeeper, error message is pushed at the top of the stack, not raised immediately
-            InterCopyContext _c{ this, DestState{ _K }, SourceState{ L_ }, {}, SourceIndex{ lua_absindex(L_, -1) }, {}, LookupMode::ToKeeper, {} };
-            if (_c.inter_copy_package() != InterCopyResult::Success) {                             // L_: settings ... error_msg                      K:
-                // if something went wrong, the error message is at the top of the stack
-                lua_remove(L_, -2);                                                                // L_: settings error_msg
-                raise_lua_error(L_);
-            }
-        }
-        lua_pop(L_, 1);                                                                            // L_: settings                                    K:
-        STACK_CHECK(L_, 0);
-        STACK_CHECK(_K, 0);
-
-        // attempt to call on_state_create(), if we have one and it is a C function
-        // (only support a C function because we can't transfer executable Lua code in keepers)
-        // will raise an error in L_ in case of problem
-        state::CallOnStateCreate(this, _K, L_, LookupMode::ToKeeper);
-
-        // to see VM name in Decoda debugger
-        lua_pushfstring(_K, "Keeper #%d", _i + 1);                                                 // L_: settings                                    K: "Keeper #n"
-        if constexpr (HAVE_DECODA_NAME()) {
-            lua_pushvalue(_K, -1);                                                                 //                                                 K: "Keeper #n" Keeper #n"
-            lua_setglobal(_K, "decoda_name");                                                      // L_: settings                                    K: "Keeper #n"
-        }
-        kLaneNameRegKey.setValue(_K, [](lua_State* L_) { lua_insert(L_, -2); });                   //                                                 K:
-        // create the fifos table in the keeper state
-        Keepers::CreateFifosTable(_K);
-        STACK_CHECK(_K, 0);
-    }
-    STACK_CHECK(L_, 0);
-}
-
-// #################################################################################################
-
 void Universe::terminateFreeRunningLanes(lua_State* const L_, lua_Duration const shutdownTimeout_, CancelOp const op_)
 {
     if (selfdestructFirst != SELFDESTRUCT_END) {
@@ -425,7 +337,7 @@ LUAG_FUNC(universe_gc)
         _U->timerLinda = nullptr;
     }
 
-    _U->closeKeepers();
+    _U->keepers.close();
 
     // remove the protected allocator, if any
     _U->protectedAllocator.removeFrom(L_);
diff --git a/src/universe.h b/src/universe.h
index 7624fed..7b9f309 100644
--- a/src/universe.h
+++ b/src/universe.h
@@ -9,10 +9,12 @@ extern "C"
 }
 #endif // __cplusplus
 
+#include "keeper.h"
 #include "lanesconf.h"
 #include "tracker.h"
 #include "uniquekey.h"
 
+#include <atomic>
 #include <mutex>
 
 // #################################################################################################
@@ -20,7 +22,6 @@ extern "C"
 // forwards
 enum class CancelOp;
 struct DeepPrelude;
-struct Keepers;
 class Lane;
 
 // #################################################################################################
@@ -144,7 +145,7 @@ class Universe
 
     AllocatorDefinition internalAllocator;
 
-    Keepers* keepers{ nullptr };
+    Keepers keepers;
 
     // Initialized by 'init_once_LOCKED()': the deep userdata Linda object
     // used for timers (each lane will get a proxy to this)
@@ -183,12 +184,10 @@ class Universe
     Universe& operator=(Universe const&) = delete;
     Universe& operator=(Universe&&) = delete;
 
-    void closeKeepers();
     [[nodiscard]] static Universe* Create(lua_State* L_);
     [[nodiscard]] static inline Universe* Get(lua_State* L_);
     void initializeAllocatorFunction(lua_State* L_);
     static int InitializeFinalizer(lua_State* L_);
-    void initializeKeepers(lua_State* L_);
     static inline void Store(lua_State* L_, Universe* U_);
     void terminateFreeRunningLanes(lua_State* L_, lua_Duration shutdownTimeout_, CancelOp op_);
 };