Thread priority reworkHEADmaster

* thread priorities can now be set using the native range of values, if desired.
* thread API errors cause a Lua error instead of aborting the program.
* new function lanes.thread_priority_range(), to query the valid range of priorities.
* unit tests for all of the above

11 files changed, 347 insertions, 171 deletions

diff --git a/CHANGES b/CHANGES
index 4dc9d2d..65077f7 100644
--- a/CHANGES
+++ b/CHANGES
@@ -16,6 +16,7 @@ CHANGE 2: BGe 27-Nov-24
             - new function lanes.finally(). Installs a function that gets called at Lanes shutdown after attempting to terminate all lanes.
               If some lanes still run after the finalizer, Universe::__gc with raise an error or freeze, depending on its return value.
             - new function lanes.collectgarbage(), to force a full GC cycle in the keeper states.
+            - new function lanes.thread_priority_range(), to query the valid range of priorities.
             - Configuration settings:
                 - Boolean parameters only accept boolean values.
                 - allocator provider function is called with a string hint to distinguish internal allocations, lane and keeper states.
@@ -26,6 +27,8 @@ CHANGE 2: BGe 27-Nov-24
                 - verbose_errors removed. Use lane error_trace_level instead.
                 - with_timers is false by default.
             - Non-deep full userdata are processed during module registration just like ordinary module C functions, making them valid transferable (up)values (for example: io.stdin).
+            - thread API errors cause a Lua error instead of aborting the program.
+            - thread priorities can now be set using the native range of values, if desired.
         - Lanes:
             - Can no longer be "killed" by hard-stopping their thread without any resource cleanup (see lane:cancel()).
             - lanes.gen() settings:
diff --git a/Makefile b/Makefile
index 98fa1ac..ea4f1d3 100644
--- a/Makefile
+++ b/Makefile
@@ -80,7 +80,7 @@ build_DUE:
 run_unit_tests: build_lanes build_unit_tests build_DUE
         @echo =========================================================================================
         $(_PREFIX) $(_UNITTEST_TARGET) --list-tests
-        $(_PREFIX) $(_UNITTEST_TARGET) --rng-seed 0 -s scripted_tests.lane.tasking_cancelling
+        $(_PREFIX) $(_UNITTEST_TARGET) --rng-seed 0
 
 debug_unit_tests: build_lanes build_unit_tests build_DUE
         @echo =========================================================================================
diff --git a/docs/index.html b/docs/index.html
index e3fbd0b..be8ad7f 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -71,7 +71,7 @@
                         </p>
 
                         <p>
-                                This document was revised on 23-Apr-25, and applies to version <tt>4.0.0</tt>.
+                                This document was revised on 07-May-25, and applies to version <tt>4.0.0</tt>.
                         </p>
                 </font>
         </center>
@@ -106,7 +106,7 @@
                 <li>Threads can be given priorities.</li>
                 <li>Lanes are cancellable, with proper cleanup.</li>
                 <li>No Lua-side application level locking - ever!</li>
-                <li>Several totally independant Lanes universes may coexist in an application, one per "master" Lua state.</li>
+                <li>Several totally independent Lanes universes may coexist in an application, one per "master" Lua state.</li>
         </ul>
 
 
@@ -117,7 +117,7 @@
                 <li>Sharing full userdata between states needs special C side preparations (-&gt; <A HREF="#deep_userdata">deep userdata</A> and -&gt; <A HREF="#clonable_userdata">clonable userdata</A>).</li>
                 <li>Network level parallelism not included.</li>
                 <li>Multi-CPU is done with OS threads, not processes. A lane is a Lua full userdata, therefore it will exist only as long as the Lua state that created it still exists. Therefore, a lane won't continue execution after the main program's termination.</li>
-                <li>Just like independant Lua states, Lanes universes cannot communicate together.</li>
+                <li>Just like independent Lua states, Lanes universes cannot communicate together.</li>
         </ul>
 </p>
 
@@ -190,6 +190,7 @@
                         <li><tt>lanes.genlock()</tt>: obtain an atomic-like data stack</li>
                         <li><tt>lanes.linda()</tt>: create a Linda</li>
                         <li><tt>lanes.nameof()</tt>: find where a value exists</li>
+                        <li><tt>lanes.thread_priority_range()</tt>: obtain the valid range of thread priorities</li>
                         <li><tt>lanes.now_secs()</tt>: obtain the current clock value</li>
                         <li><tt>lanes.register()</tt>: scan modules so that functions using them can be transferred</li>
                         <li><tt>lanes.set_thread_priority()</tt>: change thread priority</li>
@@ -863,12 +864,13 @@
                 </tr>
                 <tr valign=top>
                         <td>
-                                <code>.priority</code>
+                                <code>.priority</code><br />
+                                <code>.native_priority</code>
                         </td>
                         <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 />
+                                <tt>priority</tt>: The priority of lanes in the range <tt>[-3,+3]</tt> (default is 0). These values are a mapping over the actual priority range of the underlying implementation.<br />
+                                <tt>native_priority</tt>: The priority of lanes in a platform-dependent the range. Use <a href="#priority"><tt>lanes.thread_priority_range()</tt></a> to query said range.
                                 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>
@@ -957,14 +959,17 @@
         <table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%">
                 <tr>
                         <td>
-                                <pre>   lanes.set_thread_priority(prio)</pre>
+                                <pre>   prio_min, prio_max = lanes.thread_priority_range(prio [,"native"])</pre>
+                                <pre>   lanes.set_thread_priority(prio [,"native"])</pre>
                         </td>
                 </tr>
         </table>
 <p>
         Besides setting a default priority in the generator <a href="#generator_settings">settings</a>, each thread can change its own priority at will. This is also true for the main Lua state.
         <br />
-        The priority must be in the range <tt>[-3,+3]</tt>.
+        <tt>lanes.thread_priority_range()</tt> returns the range of acceptable mapped values. If nothing is specified, should be <tt>[-3,3]</tt> or <tt>[0,3]</tt>, depending on the threading implementation.
+        <br />
+        <tt>lanes.thread_priority_range('native')</tt> returns the range of acceptable native values. The actual values are threading implementation dependent. And some implementations can only accept some values inside that range. YMMV.
 </p>
 
 
diff --git a/src/lane.cpp b/src/lane.cpp
index 26ddebd..65a776e 100644
--- a/src/lane.cpp
+++ b/src/lane.cpp
@@ -1169,11 +1169,11 @@ void Lane::securizeDebugName(lua_State* const L_)
 
 // #################################################################################################
 
-void Lane::startThread(int const priority_)
+void Lane::startThread(lua_State* const L_, int const priority_, NativePrioFlag native_)
 {
     thread = std::thread([this]() { lane_main(this); });
     if (priority_ != kThreadPrioDefault) {
-        THREAD_SET_PRIORITY(thread, priority_, U->sudo);
+        THREAD_SET_PRIORITY(L_, thread, priority_, native_, U->sudo);
     }
 }
 
diff --git a/src/lane.hpp b/src/lane.hpp
index 5fe36b6..917606f 100644
--- a/src/lane.hpp
+++ b/src/lane.hpp
@@ -204,7 +204,7 @@ class Lane final
     [[nodiscard]]
     bool selfdestructRemove();
     void securizeDebugName(lua_State* L_);
-    void startThread(int priority_);
+    void startThread(lua_State* L_, int priority_, NativePrioFlag native_);
     void storeDebugName( std::string_view const& name_);
     [[nodiscard]]
     int storeResults(lua_State* L_);
diff --git a/src/lanes.cpp b/src/lanes.cpp
index d1a353b..0eaeb3e 100644
--- a/src/lanes.cpp
+++ b/src/lanes.cpp
@@ -137,13 +137,15 @@ LUAG_FUNC(set_singlethreaded)
 LUAG_FUNC(set_thread_priority)
 {
     lua_Integer const _prio{ luaL_checkinteger(L_, 1) };
+    NativePrioFlag const _native{ std::string_view{ "native" } == luaL_optstring(L_, 2, "mapped") };
     // public Lanes API accepts a generic range -3/+3
     // that will be remapped into the platform-specific scheduler priority scheme
     // On some platforms, -3 is equivalent to -2 and +3 to +2
-    if (_prio < kThreadPrioMin || _prio > kThreadPrioMax) {
+    if (!_native && (_prio < kThreadPrioMin || _prio > kThreadPrioMax)) {
         raise_luaL_error(L_, "priority out of range: %d..+%d (%d)", kThreadPrioMin, kThreadPrioMax, _prio);
     }
-    THREAD_SET_PRIORITY(static_cast<int>(_prio), Universe::Get(L_)->sudo);
+
+    THREAD_SET_PRIORITY(L_, static_cast<int>(_prio), _native, Universe::Get(L_)->sudo);
     return 0;
 }
 
@@ -155,7 +157,8 @@ LUAG_FUNC(set_thread_affinity)
     if (_affinity <= 0) {
         raise_luaL_error(L_, "invalid affinity (%d)", _affinity);
     }
-    THREAD_SET_AFFINITY(static_cast<unsigned int>(_affinity));
+
+    THREAD_SET_AFFINITY(L_, static_cast<unsigned int>(_affinity));
     return 0;
 }
 
@@ -236,9 +239,26 @@ int lanes_register(lua_State* const L_)
 
 // #################################################################################################
 
+LUAG_FUNC(thread_priority_range)
+{
+    NativePrioFlag const _native{ std::string_view{ "native" } == luaL_optstring(L_, 1, "mapped") };
+    if (_native) {
+        auto const [_prio_min, _prio_max] = THREAD_NATIVE_PRIOS();
+        lua_pushinteger(L_, _prio_min);
+        lua_pushinteger(L_, _prio_max);
+    } else {
+        lua_pushinteger(L_, kThreadPrioMin);
+        lua_pushinteger(L_, kThreadPrioMax);
+    }
+    return 2;
+}
+
+// #################################################################################################
+
 //--- [] means can be nil
 // lane_ud = lane_new( function
 //                   , [libs_str]
+//                   , [prio_is_native_bool]
 //                   , [priority_int]
 //                   , [globals_tbl]
 //                   , [package_tbl]
@@ -255,15 +275,16 @@ LUAG_FUNC(lane_new)
 {
     static constexpr StackIndex kFuncIdx{ 1 };
     static constexpr StackIndex kLibsIdx{ 2 };
-    static constexpr StackIndex kPrioIdx{ 3 };
-    static constexpr StackIndex kGlobIdx{ 4 };
-    static constexpr StackIndex kPackIdx{ 5 };
-    static constexpr StackIndex kRequIdx{ 6 };
-    static constexpr StackIndex kGcCbIdx{ 7 };
-    static constexpr StackIndex kNameIdx{ 8 };
-    static constexpr StackIndex kErTlIdx{ 9 };
-    static constexpr StackIndex kAsCoro{ 10 };
-    static constexpr StackIndex kFixedArgsIdx{ 10 };
+    static constexpr StackIndex kPrinIdx{ 3 };
+    static constexpr StackIndex kPrioIdx{ 4 };
+    static constexpr StackIndex kGlobIdx{ 5 };
+    static constexpr StackIndex kPackIdx{ 6 };
+    static constexpr StackIndex kRequIdx{ 7 };
+    static constexpr StackIndex kGcCbIdx{ 8 };
+    static constexpr StackIndex kNameIdx{ 9 };
+    static constexpr StackIndex kErTlIdx{ 10 };
+    static constexpr StackIndex kAsCoro{ 11 };
+    static constexpr StackIndex kFixedArgsIdx{ 11 };
 
     int const _nargs{ lua_gettop(L_) - kFixedArgsIdx };
     LUA_ASSERT(L_, _nargs >= 0);
@@ -400,21 +421,22 @@ LUAG_FUNC(lane_new)
     // public Lanes API accepts a generic range -3/+3
     // that will be remapped into the platform-specific scheduler priority scheme
     // On some platforms, -3 is equivalent to -2 and +3 to +2
-    int const _priority{
+    auto const [_priority, _native] {
         std::invoke([L = L_]() {
+            NativePrioFlag const _native{ static_cast<bool>(lua_toboolean(L, kPrinIdx)) };
             StackIndex const _prio_idx{ lua_isnoneornil(L, kPrioIdx) ? kIdxNone : kPrioIdx };
-            if (_prio_idx == 0) {
-                return kThreadPrioDefault;
+            if (_prio_idx == kIdxNone) {
+                return std::make_pair(kThreadPrioDefault, _native);
             }
             int const _priority{ static_cast<int>(lua_tointeger(L, _prio_idx)) };
-            if ((_priority < kThreadPrioMin || _priority > kThreadPrioMax)) {
+            if (!_native && (_priority < kThreadPrioMin || _priority > kThreadPrioMax)) {
                 raise_luaL_error(L, "Priority out of range: %d..+%d (%d)", kThreadPrioMin, kThreadPrioMax, _priority);
             }
-            return _priority;
+            return std::make_pair(_priority, _native);
         })
     };
 
-    _lane->startThread(_priority);
+    _lane->startThread(L_, _priority, _native);
 
     STACK_GROW(_L2, _nargs + 3);
     STACK_GROW(L_, 3);
@@ -658,6 +680,7 @@ namespace {
             { Universe::kFinally, Universe::InitializeFinalizer },
             { "linda", LG_linda },
             { "nameof", LG_nameof },
+            { "thread_priority_range", LG_thread_priority_range },
             { "now_secs", LG_now_secs },
             { "register", lanes_register },
             { "set_singlethreaded", LG_set_singlethreaded },
@@ -753,9 +776,6 @@ LUAG_FUNC(configure)
     );                                                                                             // L_: settings M VERSION
     lua_setfield(L_, -2, "version");                                                               // L_: settings M
 
-    lua_pushinteger(L_, kThreadPrioMax);                                                           // L_: settings M kThreadPrioMax
-    lua_setfield(L_, -2, "max_prio");                                                              // L_: settings M
-
     kCancelError.pushKey(L_);                                                                      // L_: settings M kCancelError
     lua_setfield(L_, -2, "cancel_error");                                                          // L_: settings M
 
diff --git a/src/lanes.lua b/src/lanes.lua
index 3ee959c..c5b3315 100644
--- a/src/lanes.lua
+++ b/src/lanes.lua
@@ -280,6 +280,10 @@ local opt_validators =
         local tv = type(v_)
         return (tv == "string") and v_ or raise_option_error("name", tv, v_)
     end,
+    native_priority = function(v_)
+        local tv = type(v_)
+        return (tv == "number") and v_ or raise_option_error("native_priority", tv, v_)
+    end,
     package = function(v_)
         local tv = type(v_)
         return (tv == "table") and v_ or raise_option_error("package", tv, v_)
@@ -295,7 +299,7 @@ local opt_validators =
 }
 
 -- #############################################################################################
--- ##################################### lanes.gen() ###########################################
+-- ################################### lanes.gen/coro() ########################################
 -- #############################################################################################
 
 local process_gen_opt = function(...)
@@ -367,9 +371,16 @@ local process_gen_opt = function(...)
             opt[k] = validator(v)
         end
     end
+
+    -- special case: can't have priority and native_priority at the same time
+    if opt.priority and opt.native_priority then
+        error "priority and native_priority cannot be specified together"
+    end
     return func, libs, opt
 end -- process_gen_opt
 
+-- #################################################################################################
+
 -- lane_h[1..n]: lane results, same as via 'lane_h:join()'
 -- lane_h[0]:    can be read to make sure a thread has finished (gives the number of available results)
 -- lane_h[negative]:   error message, without propagating the error
@@ -408,25 +419,28 @@ end -- process_gen_opt
 -- Calling with a function argument ('lane_func') ends the string/table
 -- modifiers, and prepares a lane generator.
 
--- receives a sequence of strings and tables, plus a function
-local gen = function(...)
+local make_generator = function(is_coro_, ...)
     local func, libs, opt = process_gen_opt(...)
     local core_lane_new = assert(core.lane_new)
-    local priority, globals, package, required, gc_cb, name, error_trace_level = opt.priority, opt.globals, opt.package or package, opt.required, opt.gc_cb, opt.name, error_trace_levels[opt.error_trace_level]
+    local prio_is_native = opt.native_priority and true or false
+    local priority, globals, package, required, gc_cb, name, error_trace_level = opt.priority or opt.native_priority, opt.globals, opt.package or package, opt.required, opt.gc_cb, opt.name, error_trace_levels[opt.error_trace_level]
     return function(...)
         -- must pass functions args last else they will be truncated to the first one
-        return core_lane_new(func, libs, priority, globals, package, required, gc_cb, name, error_trace_level, false, ...)
+        return core_lane_new(func, libs, prio_is_native, priority, globals, package, required, gc_cb, name, error_trace_level, is_coro_, ...)
     end
+end -- make_generator
+
+-- #################################################################################################
+
+-- receives a sequence of strings and tables, plus a function
+local gen = function(...)
+    return make_generator(false, ...)
 end -- gen()
 
+-- #################################################################################################
+
 local coro = function(...)
-    local func, libs, opt = process_gen_opt(...)
-    local core_lane_new = assert(core.lane_new)
-    local priority, globals, package, required, gc_cb, name, error_trace_level = opt.priority, opt.globals, opt.package or package, opt.required, opt.gc_cb, opt.name, error_trace_levels[opt.error_trace_level]
-    return function(...)
-        -- must pass functions args last else they will be truncated to the first one
-        return core_lane_new(func, libs, priority, globals, package, required, gc_cb, name, error_trace_level, true, ...)
-    end
+    return make_generator(true, ...)
 end -- coro()
 
 -- #################################################################################################
@@ -656,7 +670,8 @@ local configure_timers = function()
                 end
             end
         end -- timer_body()
-        timer_lane = gen("lanes_core,table", { name = "LanesTimer", package = {}, priority = core.max_prio }, timer_body)()
+        local min_prio, max_prio = core.thread_priority_range()
+        timer_lane = gen("lanes_core,table", { name = "LanesTimer", package = {}, priority = max_prio }, timer_body)()
     end -- first_time
 
     -----
@@ -876,6 +891,7 @@ local configure = function(settings_)
     lanes.set_thread_affinity = core.set_thread_affinity
     lanes.set_thread_priority = core.set_thread_priority
     lanes.sleep = core.sleep
+    lanes.thread_priority_range = core.thread_priority_range
     lanes.threads = core.threads or function() error "lane tracking is not available" end -- core.threads isn't registered if settings.track_lanes is false
 
     lanes.gen = gen
diff --git a/src/threading.cpp b/src/threading.cpp
index 483a228..efca7eb 100644
--- a/src/threading.cpp
+++ b/src/threading.cpp
@@ -49,6 +49,7 @@ THE SOFTWARE.
 
 #endif // __linux__
 
+#include "compat.hpp"
 #include "threading.hpp"
 
 #if !defined(PLATFORM_XBOX) && !defined(PLATFORM_WIN32) && !defined(PLATFORM_POCKETPC)
@@ -82,25 +83,42 @@ THE SOFTWARE.
 #pragma warning(disable : 4054)
 #endif
 
+static constexpr std::string_view StripFuncName(std::string_view const& where_)
+{
+    std::string_view funcname_{ where_ };
+
+    auto _args_pos{ funcname_.find_first_of('(') };
+    funcname_ = funcname_.substr(0, _args_pos);
+    auto _name_pos{ funcname_.find_last_of(' ') };
+    funcname_.remove_prefix(_name_pos + 1);
+    return funcname_;
+}
+
 /*
  * FAIL is for unexpected API return values - essentially programming
  * error in _this_ code.
  */
 #if HAVE_WIN32
-static void FAIL(char const* funcname_, DWORD const rc_)
+
+template <typename F, typename... ARGS>
+void Win32Invoke(lua_State* const L_, std::string_view const& where_, F& f_, ARGS... args_)
 {
+    auto const _ret{ std::invoke(f_, std::forward<ARGS>(args_)...) };
+    if (!_ret) {
+        auto const _rc{ GetLastError() };
+        std::string_view const _funcname{ StripFuncName(where_) };
+
 #if defined(PLATFORM_XBOX)
-    fprintf(stderr, "%s() failed! (%d)\n", funcname_, rc_);
-#else  // PLATFORM_XBOX
-    char buf[256];
-    FormatMessageA(FORMAT_MESSAGE_FROM_SYSTEM, nullptr, rc_, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), buf, 256, nullptr);
-    fprintf(stderr, "%s() failed! [GetLastError() -> %lu] '%s'", funcname_, rc_, buf);
+        luaG_pushstring(L_, "%s() failed with code %d", _funcname.data(), _rc);
+#else // PLATFORM_XBOX
+        char _buf[256];
+        FormatMessageA(FORMAT_MESSAGE_FROM_SYSTEM, nullptr, _rc, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), _buf, 256, nullptr);
+        luaG_pushstring(L_, "%s() failed with code %d '%s'", _funcname.data(), _rc, _buf);
 #endif // PLATFORM_XBOX
-#ifdef _MSC_VER
-    __debugbreak(); // give a chance to the debugger!
-#endif              // _MSC_VER
-    abort();
+        raise_lua_error(L_);
+    }
 }
+
 #endif // HAVE_WIN32
 
 /*---=== Threading ===---*/
@@ -121,33 +139,35 @@ static int const gs_prio_remap[] = {
 
 // #################################################################################################
 
-void THREAD_SET_PRIORITY(int prio_, [[maybe_unused]] bool sudo_)
+std::pair<int, int> THREAD_NATIVE_PRIOS()
 {
-    // prio range [-3,+3] was checked by the caller
-    if (!SetThreadPriority(GetCurrentThread(), gs_prio_remap[prio_ + 3])) {
-        FAIL("THREAD_SET_PRIORITY", GetLastError());
-    }
+    return std::make_pair(THREAD_PRIORITY_IDLE, THREAD_PRIORITY_TIME_CRITICAL);
 }
 
 // #################################################################################################
 
-void THREAD_SET_PRIORITY(std::thread& thread_, int prio_, [[maybe_unused]] bool sudo_)
+[[nodiscard]]
+void THREAD_SET_PRIORITY(lua_State* const L_, int const prio_, NativePrioFlag const native_, [[maybe_unused]] SudoFlag const sudo_)
 {
-    // prio range [-3,+3] was checked by the caller
-    // for some reason when building for mingw, native_handle() is an unsigned long long, but HANDLE is a void*
-    // -> need a strong cast to make g++ happy
-    if (!SetThreadPriority(thread_.native_handle(), gs_prio_remap[prio_ + 3])) {
-        FAIL("THREAD_SET_PRIORITY", GetLastError());
-    }
+    // mapped prio range [-3,+3] was checked by the caller
+    return Win32Invoke(L_, std::source_location::current().function_name(), SetThreadPriority, GetCurrentThread(), native_ ? prio_ : gs_prio_remap[prio_ + 3]);
 }
 
 // #################################################################################################
 
-void THREAD_SET_AFFINITY(unsigned int aff_)
+[[nodiscard]]
+void THREAD_SET_PRIORITY(lua_State* const L_, std::thread& thread_, int const prio_, NativePrioFlag const native_, [[maybe_unused]] SudoFlag const sudo_)
 {
-    if (!SetThreadAffinityMask(GetCurrentThread(), aff_)) {
-        FAIL("THREAD_SET_AFFINITY", GetLastError());
-    }
+    // mapped prio range [-3,+3] was checked by the caller
+    return Win32Invoke(L_, std::source_location::current().function_name(), SetThreadPriority, thread_.native_handle(), native_ ? prio_ : gs_prio_remap[prio_ + 3]);
+}
+
+// #################################################################################################
+
+[[nodiscard]]
+void THREAD_SET_AFFINITY(lua_State* const L_, unsigned int aff_)
+{
+    return Win32Invoke(L_, std::source_location::current().function_name(), SetThreadAffinityMask, GetCurrentThread(), aff_);
 }
 
 // #################################################################################################
@@ -215,24 +235,24 @@ static int pthread_attr_setschedpolicy(pthread_attr_t* attr, int policy)
 #endif // pthread_attr_setschedpolicy()
 #endif // defined(__MINGW32__) || defined(__MINGW64__)
 
-static void _PT_FAIL(int rc, const char* name, const char* file, int line)
+template <typename F, typename... ARGS>
+void PthreadInvoke(lua_State* const L_, std::string_view const& where_, F& f_, ARGS... args_)
 {
-    const char* why = (rc == EINVAL) ? "EINVAL" 
-        : (rc == EBUSY)              ? "EBUSY"
-        : (rc == EPERM)              ? "EPERM"
-        : (rc == ENOMEM)             ? "ENOMEM"
-        : (rc == ESRCH)              ? "ESRCH"
-        : (rc == ENOTSUP)            ? "ENOTSUP"
-                                     : "<UNKNOWN>";
-    fprintf(stderr, "%s %d: %s failed, %d %s\n", file, line, name, rc, why);
-    abort();
-}
-#define PT_CALL(call) \
-    { \
-        int rc = call; \
-        if (rc != 0) \
-            _PT_FAIL(rc, #call, __FILE__, __LINE__); \
+    auto const _rc{ std::invoke(f_, std::forward<ARGS>(args_)...) };
+    if (_rc) {
+        std::string_view const _funcname{ StripFuncName(where_) };
+
+        char const* _why = (_rc == EINVAL) ? "EINVAL"
+            : (_rc == EBUSY)              ? "EBUSY"
+            : (_rc == EPERM)              ? "EPERM"
+            : (_rc == ENOMEM)             ? "ENOMEM"
+            : (_rc == ESRCH)              ? "ESRCH"
+            : (_rc == ENOTSUP)            ? "ENOTSUP"
+                                          : "<UNKNOWN>";
+
+        raise_luaL_error(L_, "%s() failed with code %s", _funcname.data(), _why);
     }
+}
 
 // array of 7 thread priority values, hand-tuned by platform so that we offer a uniform [-3,+3] public priority range
 static int const gs_prio_remap[] = {
@@ -357,7 +377,18 @@ static int const gs_prio_remap[] = {
 #endif // _PRIO_0
 };
 
-void THREAD_SET_PRIORITY(int prio_, [[maybe_unused]] bool sudo_)
+// #################################################################################################
+
+std::pair<int, int> THREAD_NATIVE_PRIOS()
+{
+    int const _prio_min{ sched_get_priority_min(_PRIO_MODE) };
+    int const _prio_max{ sched_get_priority_max(_PRIO_MODE) };
+    return std::make_pair(_prio_min, _prio_max);
+}
+
+// #################################################################################################
+
+void THREAD_SET_PRIORITY(lua_State* const L_, int const prio_, NativePrioFlag const native_, [[maybe_unused]] SudoFlag const sudo_)
 {
 #ifdef PLATFORM_LINUX
     if (!sudo_) // only root-privileged process can change priorities
@@ -366,13 +397,13 @@ void THREAD_SET_PRIORITY(int prio_, [[maybe_unused]] bool sudo_)
 
     struct sched_param sp;
     // prio range [-3,+3] was checked by the caller
-    sp.sched_priority = gs_prio_remap[prio_ + 3];
-    PT_CALL(pthread_setschedparam(pthread_self(), _PRIO_MODE, &sp));
+    sp.sched_priority = native_ ? prio_ : gs_prio_remap[prio_ + 3];
+    PthreadInvoke(L_, std::source_location::current().function_name(), pthread_setschedparam, pthread_self(), _PRIO_MODE, &sp);
 }
 
 // #################################################################################################
 
-void THREAD_SET_PRIORITY(std::thread& thread_, int prio_, [[maybe_unused]] bool sudo_)
+void THREAD_SET_PRIORITY(lua_State* const L_, std::thread& thread_, int const prio_, NativePrioFlag const native_, [[maybe_unused]] SudoFlag const sudo_)
 {
 #ifdef PLATFORM_LINUX
     if (!sudo_) // only root-privileged process can change priorities
@@ -381,28 +412,26 @@ void THREAD_SET_PRIORITY(std::thread& thread_, int prio_, [[maybe_unused]] bool
 
     struct sched_param sp;
     // prio range [-3,+3] was checked by the caller
-    sp.sched_priority = gs_prio_remap[prio_ + 3];
-    PT_CALL(pthread_setschedparam(thread_.native_handle(), _PRIO_MODE, &sp));
+    sp.sched_priority = native_ ? prio_ : gs_prio_remap[prio_ + 3];
+    PthreadInvoke(L_, std::source_location::current().function_name(), pthread_setschedparam, thread_.native_handle(), _PRIO_MODE, &sp);
 }
 
 // #################################################################################################
 
 #ifdef __PROSPERO__
 
-void THREAD_SET_AFFINITY(unsigned int aff_)
+void THREAD_SET_AFFINITY(lua_State* const L_, unsigned int aff_)
 {
-    scePthreadSetaffinity(scePthreadSelf(), aff_);
+    PthreadInvoke(L_, std::source_location::current().function_name(), scePthreadSetaffinity, scePthreadSelf(), aff_);
 }
 
 #else // __PROSPERO__
 
-void THREAD_SET_AFFINITY(unsigned int aff_)
+void THREAD_SET_AFFINITY(lua_State* const L_, unsigned int aff_)
 {
 #if HAVE_WIN32 // "hybrid": Win32 API is available, and pthread too
     // since pthread_setaffinity_np can be missing (for example mingw), use win32 api instead
-    if (!SetThreadAffinityMask(GetCurrentThread(), aff_)) {
-        FAIL("THREAD_SET_AFFINITY", GetLastError());
-    }
+    Win32Invoke(L_, std::source_location::current().function_name(), SetThreadAffinityMask, GetCurrentThread(), aff_);
 #else // pure pthread
     int bit = 0;
 #ifdef __NetBSD__
@@ -422,12 +451,13 @@ void THREAD_SET_AFFINITY(unsigned int aff_)
         aff_ >>= 1;
     }
 #ifdef __ANDROID__
-    PT_CALL(sched_setaffinity(pthread_self(), sizeof(cpu_set_t), &cpuset));
+    
+    PthreadInvoke(L_, std::source_location::current().function_name(), sched_setaffinity, pthread_self(), sizeof(cpu_set_t), &cpuset);
 #elif defined(__NetBSD__)
-    PT_CALL(pthread_setaffinity_np(pthread_self(), cpuset_size(cpuset), cpuset));
+    PthreadInvoke(L_, std::source_location::current().function_name(), pthread_setaffinity_np, pthread_self(), cpuset_size(cpuset), cpuset);
     cpuset_destroy(cpuset);
 #else
-    PT_CALL(pthread_setaffinity_np(pthread_self(), sizeof(cpu_set_t), &cpuset));
+    PthreadInvoke(L_, std::source_location::current().function_name(), pthread_setaffinity_np, pthread_self(), sizeof(cpu_set_t), &cpuset);
 #endif
 #endif // PLATFORM_MINGW
 }
@@ -447,7 +477,7 @@ void THREAD_SETNAME(std::string_view const& name_)
 
 void THREAD_SETNAME(std::string_view const& name_)
 {
-    // exact API to set the thread name is platform-dependant
+    // exact API to set the thread name is platform-dependent
     // if you need to fix the build, or if you know how to fill a hole, tell me (bnt.germain@gmail.com) so that I can submit the fix in github.
 #if defined PLATFORM_MINGW
     pthread_setname_np(pthread_self(), name_.data());
diff --git a/src/threading.hpp b/src/threading.hpp
index 912c28f..07c1ab3 100644
--- a/src/threading.hpp
+++ b/src/threading.hpp
@@ -1,6 +1,7 @@
 #pragma once
 
 #include "platform.h"
+#include "unique.hpp"
 
 #define THREADAPI_WINDOWS 1
 #define THREADAPI_PTHREAD 2
@@ -73,8 +74,15 @@ static constexpr int kThreadPrioMax{ +3 };
 // #################################################################################################
 // #################################################################################################
 
+DECLARE_UNIQUE_TYPE(SudoFlag, bool);
+DECLARE_UNIQUE_TYPE(NativePrioFlag, bool);
+
+std::pair<int, int> THREAD_NATIVE_PRIOS();
+
 void THREAD_SETNAME(std::string_view const& name_);
-void THREAD_SET_PRIORITY(int prio_, bool sudo_);
-void THREAD_SET_AFFINITY(unsigned int aff_);
 
-void THREAD_SET_PRIORITY(std::thread& thread_, int prio_, bool sudo_);
+void THREAD_SET_PRIORITY(lua_State* L_, int prio_, NativePrioFlag native_, SudoFlag sudo_);
+
+void THREAD_SET_AFFINITY(lua_State* L_, unsigned int aff_);
+
+void THREAD_SET_PRIORITY(lua_State* L_, std::thread& thread_, int prio_, NativePrioFlag native_, SudoFlag sudo_);
diff --git a/src/universe.hpp b/src/universe.hpp
index fac5f50..ab49f86 100644
--- a/src/universe.hpp
+++ b/src/universe.hpp
@@ -4,6 +4,7 @@
 #include "cancel.hpp"
 #include "keeper.hpp"
 #include "lanesconf.h"
+#include "threading.hpp"
 #include "tracker.hpp"
 #include "uniquekey.hpp"
 
@@ -70,9 +71,9 @@ class Universe final
 
 #ifdef PLATFORM_LINUX
     // Linux needs to check, whether it's been run as root
-    bool const sudo{ geteuid() == 0 };
+    SudoFlag const sudo{ geteuid() == 0 };
 #else
-    bool const sudo{ false };
+    SudoFlag const sudo{ false };
 #endif // PLATFORM_LINUX
 
     // for verbose errors
diff --git a/unit_tests/lane_tests.cpp b/unit_tests/lane_tests.cpp
index 1367ae5..3e5da2b 100644
--- a/unit_tests/lane_tests.cpp
+++ b/unit_tests/lane_tests.cpp
@@ -1,5 +1,7 @@
 #include "_pch.hpp"
+
 #include "shared.h"
+#include "lanes/src/threading.hpp"
 
 // #################################################################################################
 // #################################################################################################
@@ -33,6 +35,76 @@ TEST_CASE("lanes.nameof")
 // #################################################################################################
 // #################################################################################################
 
+TEST_CASE("lanes.thread_priority_range")
+{
+    LuaState S{ LuaState::WithBaseLibs{ true }, LuaState::WithFixture{ false } };
+    S.requireSuccess("lanes = require 'lanes'.configure()");
+
+    S.requireSuccess("a, b = lanes.thread_priority_range(); print(a, b)");
+    S.requireSuccess("assert(type(a) == 'number' and type(b) == 'number' and b > a)");
+    S.requireSuccess("c, d = lanes.thread_priority_range('native'); print(c, d)");
+    S.requireSuccess("assert(type(c) == 'number' and type(d) == 'number' and d > c)");
+
+    // can't really test the range of values from pthread as they are platform-dependent
+    if constexpr (THREADAPI == THREADAPI_WINDOWS) {
+        // windows constants THREAD_PRIORITY_IDLE and THREAD_PRIORITY_TIME_CRITICAL
+        S.requireSuccess("assert(c == -15 and d == 15)");
+    }
+}
+
+// #################################################################################################
+// #################################################################################################
+
+TEST_CASE("lanes.set_thread_priority")
+{
+    LuaState S{ LuaState::WithBaseLibs{ true }, LuaState::WithFixture{ false } };
+    S.requireSuccess("lanes = require 'lanes'.configure()");
+
+    SECTION("mapped priorities")
+    {
+        std::string_view const _script{
+            " min_prio, max_prio = lanes.thread_priority_range()"
+            " for prio = min_prio, max_prio do"
+            "     lanes.set_thread_priority(prio)"
+            " end"
+        };
+        S.requireSuccess(_script);
+
+        S.requireFailure("lanes.set_thread_priority(min_prio - 1)");
+        S.requireFailure("lanes.set_thread_priority(max_prio + 1)");
+    }
+
+    SECTION("native priorities")
+    {
+        S.requireSuccess("min_prio, max_prio = lanes.thread_priority_range('native')");
+        if constexpr (THREADAPI == THREADAPI_WINDOWS) {
+            // Win32 range is -15 to 15, but only some values are accepted
+            S.requireSuccess("lanes.set_thread_priority(-15, 'native')"); // THREAD_PRIORITY_IDLE
+            S.requireFailure("lanes.set_thread_priority(-3, 'native')");
+            S.requireSuccess("lanes.set_thread_priority(-2, 'native')"); // THREAD_PRIORITY_LOWEST
+            S.requireSuccess("lanes.set_thread_priority(-1, 'native')"); // THREAD_PRIORITY_BELOW_NORMAL
+            S.requireSuccess("lanes.set_thread_priority(0, 'native')"); // THREAD_PRIORITY_NORMAL
+            S.requireSuccess("lanes.set_thread_priority(1, 'native')"); // THREAD_PRIORITY_ABOVE_NORMAL
+            S.requireSuccess("lanes.set_thread_priority(2, 'native')"); // THREAD_PRIORITY_HIGHEST
+            S.requireFailure("lanes.set_thread_priority(3, 'native')");
+            S.requireSuccess("lanes.set_thread_priority(-15, 'native')"); // THREAD_PRIORITY_TIME_CRITICAL
+        } else {
+            // until proven otherwise, the full set of values is supported by pthread
+            std::string_view const _script{
+                " for prio = min_prio, max_prio do"
+                "     lanes.set_thread_priority(prio, 'native')"
+                " end"
+            };
+            S.requireSuccess(_script);
+        }
+        S.requireFailure("lanes.set_thread_priority(min_prio - 1)");
+        S.requireFailure("lanes.set_thread_priority(max_prio + 1)");
+    }
+}
+
+// #################################################################################################
+// #################################################################################################
+
 TEST_CASE("lanes.sleep.argument validation")
 {
     LuaState S{ LuaState::WithBaseLibs{ true }, LuaState::WithFixture{ false } };
@@ -97,88 +169,109 @@ TEST_CASE("lanes.sleep.interactions with timers")
 // #################################################################################################
 // #################################################################################################
 
-TEST_CASE("lanes.gen")
+TEST_CASE("lanes.gen.argument_checks")
 {
     LuaState S{ LuaState::WithBaseLibs{ true }, LuaState::WithFixture{ false } };
     S.requireSuccess("lanes = require 'lanes'.configure()");
 
     // ---------------------------------------------------------------------------------------------
 
-    SECTION("argument checks")
-    {
-        // no parameter is bad
-        S.requireFailure("lanes.gen()");
-
-        // minimal generator needs a function
-        S.requireSuccess("lanes.gen(function() end)");
-
-        // acceptable parameters for the generator are strings, tables, nil, followed by the function body
-        S.requireSuccess("lanes.gen(nil, function() end)");
-        S.requireSuccess("lanes.gen('', function() end)");
-        S.requireSuccess("lanes.gen({}, function() end)");
-        S.requireSuccess("lanes.gen('', {}, function() end)");
-        S.requireSuccess("lanes.gen({}, '', function() end)");
-        S.requireSuccess("lanes.gen('', '', function() end)");
-        S.requireSuccess("lanes.gen({}, {}, function() end)");
-
-        // anything different should fail: booleans, numbers, any userdata
-        S.requireFailure("lanes.gen(false, function() end)");
-        S.requireFailure("lanes.gen(true, function() end)");
-        S.requireFailure("lanes.gen(42, function() end)");
-        S.requireFailure("lanes.gen(io.stdin, function() end)");
-        S.requireFailure("lanes.gen(lanes.linda(), function() end)");
-        S.requireFailure("lanes.gen(lanes.linda():deep(), function() end)");
-
-        // even if parameter types are correct, the function must come last
-        S.requireFailure("lanes.gen(function() end, '')");
-
-        // the strings should only list "known base libraries", in any order, or "*"
-        // if the particular Lua flavor we build for doesn't support them, they raise an error unless postfixed by '?'
-        S.requireSuccess("lanes.gen('base', function() end)");
-
-        // bit, ffi, jit are LuaJIT-specific
+    // no argument is bad
+    S.requireFailure("lanes.gen()");
+
+    // minimal generator needs a function
+    S.requireSuccess("lanes.gen(function() end)");
+
+    // acceptable arguments for the generator are strings, tables, nil, followed by the function body
+    S.requireSuccess("lanes.gen(nil, function() end)");
+    S.requireSuccess("lanes.gen('', function() end)");
+    S.requireSuccess("lanes.gen({}, function() end)");
+    S.requireSuccess("lanes.gen('', {}, function() end)");
+    S.requireSuccess("lanes.gen({}, '', function() end)");
+    S.requireSuccess("lanes.gen('', '', function() end)");
+    S.requireSuccess("lanes.gen({}, {}, function() end)");
+
+    // anything different should fail: booleans, numbers, any userdata
+    S.requireFailure("lanes.gen(false, function() end)");
+    S.requireFailure("lanes.gen(true, function() end)");
+    S.requireFailure("lanes.gen(42, function() end)");
+    S.requireFailure("lanes.gen(io.stdin, function() end)");
+    S.requireFailure("lanes.gen(lanes.linda(), function() end)");
+    S.requireFailure("lanes.gen(lanes.linda():deep(), function() end)");
+
+    // even if argument types are correct, the function must come last
+    S.requireFailure("lanes.gen(function() end, '')");
+
+    // the strings should only list "known base libraries", in any order, or "*"
+    // if the particular Lua flavor we build for doesn't support them, they raise an error unless postfixed by '?'
+    S.requireSuccess("lanes.gen('base', function() end)");
+
+    // bit, ffi, jit are LuaJIT-specific
 #if LUAJIT_FLAVOR() == 0
-        S.requireFailure("lanes.gen('bit,ffi,jit', function() end)");
-        S.requireSuccess("lanes.gen('bit?,ffi?,jit?', function() end)");
+    S.requireFailure("lanes.gen('bit,ffi,jit', function() end)");
+    S.requireSuccess("lanes.gen('bit?,ffi?,jit?', function() end)");
 #endif // LUAJIT_FLAVOR()
 
-        // bit32 library existed only in Lua 5.2, there is still a loader that will raise an error in Lua 5.3
+    // bit32 library existed only in Lua 5.2, there is still a loader that will raise an error in Lua 5.3
 #if LUA_VERSION_NUM == 502 || LUA_VERSION_NUM == 503
-        S.requireSuccess("lanes.gen('bit32', function() end)");
+    S.requireSuccess("lanes.gen('bit32', function() end)");
 #else // LUA_VERSION_NUM == 502 || LUA_VERSION_NUM == 503
-        S.requireFailure("lanes.gen('bit32', function() end)");
-        S.requireSuccess("lanes.gen('bit32?', function() end)");
+    S.requireFailure("lanes.gen('bit32', function() end)");
+    S.requireSuccess("lanes.gen('bit32?', function() end)");
 #endif // LUA_VERSION_NUM == 502 || LUA_VERSION_NUM == 503
 
-        // coroutine library appeared with Lua 5.2
+    // coroutine library appeared with Lua 5.2
 #if LUA_VERSION_NUM == 501
-        S.requireFailure("lanes.gen('coroutine', function() end)");
-        S.requireSuccess("lanes.gen('coroutine?', function() end)");
+    S.requireFailure("lanes.gen('coroutine', function() end)");
+    S.requireSuccess("lanes.gen('coroutine?', function() end)");
 #endif // LUA_VERSION_NUM == 501
 
-        S.requireSuccess("lanes.gen('debug', function() end)");
-        S.requireSuccess("lanes.gen('io', function() end)");
-        S.requireSuccess("lanes.gen('math', function() end)");
-        S.requireSuccess("lanes.gen('os', function() end)");
-        S.requireSuccess("lanes.gen('package', function() end)");
-        S.requireSuccess("lanes.gen('string', function() end)");
-        S.requireSuccess("lanes.gen('table', function() end)");
+    S.requireSuccess("lanes.gen('debug', function() end)");
+    S.requireSuccess("lanes.gen('io', function() end)");
+    S.requireSuccess("lanes.gen('math', function() end)");
+    S.requireSuccess("lanes.gen('os', function() end)");
+    S.requireSuccess("lanes.gen('package', function() end)");
+    S.requireSuccess("lanes.gen('string', function() end)");
+    S.requireSuccess("lanes.gen('table', function() end)");
 
-        // utf8 library appeared with Lua 5.3
+    // utf8 library appeared with Lua 5.3
 #if LUA_VERSION_NUM < 503
-        S.requireFailure("lanes.gen('utf8', function() end)");
-        S.requireSuccess("lanes.gen('utf8?', function() end)");
+    S.requireFailure("lanes.gen('utf8', function() end)");
+    S.requireSuccess("lanes.gen('utf8?', function() end)");
 #endif // LUA_VERSION_NUM < 503
 
-        S.requireSuccess("lanes.gen('lanes_core', function() end)");
-        // "*" repeated or combined with anything else is forbidden
-        S.requireFailure("lanes.gen('*', '*', function() end)");
-        S.requireFailure("lanes.gen('base', '*', function() end)");
-        // unknown names are forbidden
-        S.requireFailure("lanes.gen('Base', function() end)");
-        // repeating the same library more than once is forbidden
-        S.requireFailure("lanes.gen('base,base', function() end)");
-    }
+    S.requireSuccess("lanes.gen('lanes_core', function() end)");
+    // "*" repeated or combined with anything else is forbidden
+    S.requireFailure("lanes.gen('*', '*', function() end)");
+    S.requireFailure("lanes.gen('base', '*', function() end)");
+    // unknown names are forbidden
+    S.requireFailure("lanes.gen('Base', function() end)");
+    // repeating the same library more than once is forbidden
+    S.requireFailure("lanes.gen('base,base', function() end)");
+}
+
+// #################################################################################################
+// #################################################################################################
+
+TEST_CASE("lanes.gen.priority")
+{
+    LuaState S{ LuaState::WithBaseLibs{ true }, LuaState::WithFixture{ false } };
+    S.requireSuccess("lanes = require 'lanes'.configure()");
+
+    S.requireSuccess("lanes.gen({priority=1}, function() end)");
+    // AFAICT, 1 is accepted by all pthread flavors and win32 API
+    S.requireSuccess("lanes.gen({native_priority=1}, function() end)");
+    // shouldn't be able to provide 2 priority settings
+    S.requireFailure("lanes.gen({priority=1, native_priority=1}, function() end)");
+}
+
+// #################################################################################################
+// #################################################################################################
+
+TEST_CASE("lanes.gen.thread_naming")
+{
+    LuaState S{ LuaState::WithBaseLibs{ true }, LuaState::WithFixture{ false } };
+    S.requireSuccess("lanes = require 'lanes'.configure()");
 
     // ---------------------------------------------------------------------------------------------