From 53454cec9e5fb600b754037c21bf700c1a65a6d2 Mon Sep 17 00:00:00 2001 From: Benoit Germain Date: Tue, 9 Apr 2024 17:26:27 +0200 Subject: Minor fixes --- docs/index.html | 211 ++++++++++++++++++++++++++++---------------------------- src/uniquekey.h | 2 +- 2 files changed, 106 insertions(+), 107 deletions(-) diff --git a/docs/index.html b/docs/index.html index d24d3d7..3e535a6 100644 --- a/docs/index.html +++ b/docs/index.html @@ -64,13 +64,13 @@


- Copyright © 2007-23 Asko Kauppi, Benoit Germain. All rights reserved. + Copyright © 2007-24 Asko Kauppi, Benoit Germain. All rights reserved.
Lua Lanes is published under the same MIT license as Lua 5.1, 5.2, 5.3 and 5.4.

- This document was revised on 29-Mar-24, and applies to version 4.0.0. + This document was revised on 9-Apr-24, and applies to version 4.0.0.

@@ -178,14 +178,14 @@
- 
	extern void LANES_API luaopen_lanes_embedded( lua_State* L, lua_CFunction _luaopen_lanes);
+ 
	extern void LANES_API luaopen_lanes_embedded(lua_State* L, lua_CFunction _luaopen_lanes);

luaopen_lanes_embedded leaves the module table on the stack. lanes.configure() must still be called in order to use Lanes.
- If _luaopen_lanes is NULL, a default loader will simply attempt the equivalent of luaL_dofile( L, "lanes.lua"). + If _luaopen_lanes is NULL, a default loader will simply attempt the equivalent of luaL_dofile(L, "lanes.lua").

@@ -198,30 +198,30 @@ 

	#include "lanes.h"

- 
	int load_lanes_lua( lua_State* L)
+ 
	int load_lanes_lua(lua_State* L)
	{
		// retrieve lanes.lua from wherever it is stored and return the result of its execution
		// trivial example 1:
- 
		luaL_dofile( L, "lanes.lua");
+ 
		luaL_dofile(L, "lanes.lua");

		// trivial example 2:
- 
		luaL_dostring( L, bin2c_lanes_lua);
+ 
		luaL_dostring(L, bin2c_lanes_lua);
	}

- 
	void embed_lanes( lua_State* L)
+ 
	void embed_lanes(lua_State* L)
	{
		// we need base libraries for Lanes for work
- 
		luaL_openlibs( L);
+ 
		luaL_openlibs(L);
		...
- 
		// will attempt luaL_dofile( L, "lanes.lua");
- 
		luaopen_lanes_embedded( L, NULL);
- 
		lua_pop( L, 1);
+ 
		// will attempt luaL_dofile(L, "lanes.lua");
+ 
		luaopen_lanes_embedded(L, nullptr);
+ 
		lua_pop(L, 1);
		// another example with a custom loader
- 
		luaopen_lanes_embedded( L, load_lanes_lua);
- 
		lua_pop( L, 1);
+ 
		luaopen_lanes_embedded(L, load_lanes_lua);
+ 
		lua_pop(L, 1);

		// a little test to make sure things work as expected
- 
		luaL_dostring( L, "local lanes = require 'lanes'.configure{with_timers = false}; local l = lanes.linda()");
+ 
		luaL_dostring(L, "local lanes = require 'lanes'.configure{with_timers = false}; local l = lanes.linda()");
	}
@@ -266,7 +266,7 @@
- 
	lanes.configure( [opt_tbl])
+ 
	lanes.configure([opt_tbl])
@@ -454,7 +454,7 @@ 
	local m = lanes.require "modname"
- 
	lanes.register( "modname", module)
+ 
	lanes.register("modname", module)
@@ -471,11 +471,11 @@ 
	local lanes = require "lanes".configure()

- 
	f = lanes.gen( function( n) return 2 * n end)
- 
	a = f( 1)
- 
	b = f( 2)
+ 
	f = lanes.gen(function(n) return 2 * n end)
+ 
	a = f(1)
+ 
	b = f(2)

- 
	print( a[1], b[1] )     -- 2    4
+ 
	print(a[1], b[1])     -- 2    4
@@ -483,8 +483,8 @@
- 
	func = lanes.gen( [libs_str | opt_tbl [, ...],] lane_func)
- 
	lane_h = func( ...)
+ 
	func = lanes.gen([libs_str | opt_tbl [, ...],] lane_func)
+ 
	lane_h = func(...)
@@ -751,7 +751,7 @@
- 
	"type", "name" = lanes.nameof( o)
+ 
	"type", "name" = lanes.nameof(o)
@@ -765,7 +765,7 @@
- 
	lanes.gen( function( params) ... end ) ( ...)
+ 
	lanes.gen(function(params) ... end ) (...)
@@ -781,7 +781,7 @@
- 
	lanes.set_thread_priority( prio)
+ 
	lanes.set_thread_priority(prio)
@@ -799,7 +799,7 @@
- 
	lanes.set_thread_affinity( affinity)
+ 
	lanes.set_thread_affinity(affinity)
@@ -901,7 +901,7 @@
- 
	{{name = "name", status = "status", ...}|nil = lanes.threads()
+ 
	{name = "name", status = "status", ...}|nil = lanes.threads()
@@ -918,7 +918,7 @@

Results and errors

-	set_error_reporting( "basic"|"extended")
+	set_error_reporting("basic"|"extended")

@@ -940,7 +940,7 @@ 

-	[...]|[nil,err,stack_tbl]= lane_h:join( [timeout_secs] )
+	[...]|[nil,err,stack_tbl]= lane_h:join([timeout_secs])

@@ -965,14 +965,14 @@ 
 	require "lanes".configure()
 
-	f = lanes.gen( function() error "!!!" end)
-	a = f( 1)
+	f = lanes.gen(function() error "!!!" end)
+	a = f(1)
 
-	--print( a[1])   -- propagates error
+	--print(a[1])   -- propagates error
 
 	v, err = a:join()   -- no propagation
 	if v == nil then
-		error( "'a' faced error"..tostring(err))   -- manual propagation
+		error("'a' faced error"..tostring(err))   -- manual propagation
 	end
@@ -984,12 +984,12 @@ require "lanes".configure() local sync_linda = lanes.linda() - f = lanes.gen( function() dostuff() sync_linda:send( "done", true) end) + f = lanes.gen(function() dostuff() sync_linda:send("done", true) end) a = f() b = f() c = f() - sync_linda:receive( nil, sync_linda.batched, "done", 3) -- wait for 3 lanes to write something in "done" slot of sync_linda + sync_linda:receive(nil, sync_linda.batched, "done", 3) -- wait for 3 lanes to write something in "done" slot of sync_linda @@ -997,9 +997,9 @@

Cancelling

-	bool[,reason] = lane_h:cancel( "soft" [, timeout] [, wake_lane])
-	bool[,reason] = lane_h:cancel( "hard" [, timeout] [, wake_lane])
-	bool[,reason] = lane_h:cancel( [mode, hookcount] [, timeout] [, wake_lane])
+	bool[,reason] = lane_h:cancel("soft" [, timeout] [, wake_lane])
+	bool[,reason] = lane_h:cancel("hard" [, timeout] [, wake_lane])
+	bool[,reason] = lane_h:cancel([mode, hookcount] [, timeout] [, wake_lane])

@@ -1041,9 +1041,9 @@

Finalizers

-	set_finalizer( finalizer_func)
+	set_finalizer(finalizer_func)
 
-	void = finalizer_func( [err, stack_tbl])
+	void = finalizer_func([err, stack_tbl])

@@ -1063,16 +1063,16 @@ 
 	local lane_body = function()
-		set_finalizer( function( err, stk)
-			if err and type( err) ~= "userdata" then
+		set_finalizer(function(err, stk)
+			if err and type(err) ~= "userdata" then
 				-- no special error: true error
-				print( " error: "..tostring(err))
-			elseif type( err) == "userdata" then
+				print(" error: "..tostring(err))
+			elseif type(err) == "userdata" then
 				-- lane cancellation is performed by throwing a special userdata as error
-				print( "after cancel")
+				print("after cancel")
 			else
 				-- no error: we just got finalized
-				print( "finalized")
+				print("finalized")
 			end
 		end)
 	end
@@ -1098,22 +1098,22 @@
 
 	local linda = lanes.linda()
 
-	local function loop( max)
+	local function loop(max)
 		for i = 1, max do
-			print( "sending: " .. i)
-			linda:send( "x", i)    -- linda as upvalue
+			print("sending: " .. i)
+			linda:send("x", i)    -- linda as upvalue
 		end
 	end
 
-	a = lanes.gen( "", loop)( 10000)
+	a = lanes.gen("", loop)(10000)
 
 	while true do
-		local key, val = linda:receive( 3.0, "x")    -- timeout in seconds
+		local key, val = linda:receive(3.0, "x")    -- timeout in seconds
 		if val == nil then
-			print( "timed out")
+			print("timed out")
 			break
 		end
-		print( tostring( linda) .. " received: " .. val)
+		print(tostring(linda) .. " received: " .. val)
 	end
@@ -1128,23 +1128,23 @@

  • two producer-side methods: :send and :set (not out).
  • send allows for sending multiple values -atomically- to a given key.
  • receive can wait for multiple keys at once.
    • -
  • receive has a batched mode to consume more than one value from a single key, as in linda:receive( 1.0, linda.batched, "key", 3, 6).
    • +
  • receive has a batched mode to consume more than one value from a single key, as in linda:receive(1.0, linda.batched, "key", 3, 6).
  • individual keys' queue length can be limited, balancing speed differences in a producer/consumer scenario (making :send wait).
    • -
  • tostring( linda) returns a string of the form "Linda: <opt_name>"
    • +
  • tostring(linda) returns a string of the form "Linda: <opt_name>"
  • several lindas may share the same keeper state. State assignation can be controlled with the linda's group (an integer). All lindas belonging to the same group will share the same keeper state. One keeper state may be shared by several groups.

    • -	h = lanes.linda( [opt_name, [opt_group]])
+	h = lanes.linda([opt_name, [opt_group]])
 
-	[true|lanes.cancel_error] = h:send( [timeout_secs,] [h.null,] key, ...)
+	[true|lanes.cancel_error] = h:send([timeout_secs,] [h.null,] key, ...)
 
-	[key, val]|[lanes.cancel_error] = h:receive( [timeout_secs,] key [, ...])
+	[key, val]|[lanes.cancel_error] = h:receive([timeout_secs,] key [, ...])
 
-	[key, val [, ...]]|[lanes.cancel_error] = h:receive( timeout, h.batched, key, n_uint_min[, n_uint_max])
+	[key, val [, ...]]|[lanes.cancel_error] = h:receive(timeout, h.batched, key, n_uint_min[, n_uint_max])
 
-	[true|lanes.cancel_error] = h:limit( key, n_uint)
+	[true|lanes.cancel_error] = h:limit(key, n_uint)

    @@ -1193,9 +1193,9 @@ 

    -	bool|lanes.cancel_error = linda_h:set( key [, val [, ...]])
+	bool|lanes.cancel_error = linda_h:set(key [, val [, ...]])
 
-	[[val [, ...]]|lanes.cancel_error] = linda_h:get( key [, count = 1])
+	[[val [, ...]]|lanes.cancel_error] = linda_h:get(key [, count = 1])

    @@ -1225,7 +1225,7 @@ 

    -	[val] = linda_h:count( [key[,...]])
+	[val] = linda_h:count([key[,...]])

    @@ -1315,7 +1315,7 @@ events to a common Linda, but... :).

    Timers

    -	void = lanes.timer( linda_h, key, date_tbl|first_secs [,period_secs])
+	void = lanes.timer(linda_h, key, date_tbl|first_secs [,period_secs])

    @@ -1342,18 +1342,18 @@ events to a common Linda, but... :). -- First timer once a second, not synchronized to wall clock -- - lanes.timer( linda, "sec", 1, 1) + lanes.timer(linda, "sec", 1, 1) -- Timer to a future event (next even minute); wall clock synchronized -- - local t = os.date( "*t", os.time() + 60) -- now + 1min + local t = os.date("*t", os.time() + 60) -- now + 1min t.sec = 0 - lanes.timer( linda, "min", t, 60) -- reoccur every minute (sharp) + lanes.timer(linda, "min", t, 60) -- reoccur every minute (sharp) while true do - local key, v = linda:receive( "sec", "min") - print( "Timer "..key..": "..v) + local key, v = linda:receive("sec", "min") + print("Timer "..key..": "..v) end @@ -1367,7 +1367,7 @@ events to a common Linda, but... :). Having the API as lanes.timer() is intentional. Another alternative would be linda_h:timer() but timers are not traditionally seen to be part of Lindas. Also, it would mean any lane getting a Linda handle would be able to modify timers on it. - A third choice could be abstracting the timers out of Linda realm altogether (timer_h= lanes.timer( date|first_secs, period_secs )) but that would mean separate waiting functions for timers, and lindas. + A third choice could be abstracting the timers out of Linda realm altogether (timer_h= lanes.timer(date|first_secs, period_secs )) but that would mean separate waiting functions for timers, and lindas. Even if a linda object and key was returned, that key couldn't be waited upon simultaneously with one's general linda events. The current system gives maximum capabilities with minimum API, and any smoothenings can easily be crafted in Lua at the application level. @@ -1386,7 +1386,7 @@ events to a common Linda, but... :). 

    -	void = lanes.sleep( [seconds|false])
+	void = lanes.sleep([seconds|false])

    @@ -1411,11 +1411,11 @@ events to a common Linda, but... :). 

    -	lock_func|lanes.cancel_error = lanes.genlock( linda_h, key [,N_uint=1])
+	lock_func|lanes.cancel_error = lanes.genlock(linda_h, key [,N_uint=1])
 
-	bool|lanes.cancel_error = lock_func( M_uint [, "try"] )     -- acquire
+	bool|lanes.cancel_error = lock_func(M_uint [, "try"] )     -- acquire
 	..
-	bool|lanes.cancel_error = lock_func( -M_uint)    -- release
+	bool|lanes.cancel_error = lock_func(-M_uint)    -- release

    @@ -1437,9 +1437,9 @@ events to a common Linda, but... :). 

    -	atomic_func|lanes.cancel_error = lanes.genatomic( linda_h, key [,initial_num=0.0])
+	atomic_func|lanes.cancel_error = lanes.genatomic(linda_h, key [,initial_num=0.0])
 
-	new_num|lanes.cancel_error = atomic_func( [diff_num=+1.0])
+	new_num|lanes.cancel_error = atomic_func([diff_num=+1.0])

    @@ -1505,14 +1505,14 @@ events to a common Linda, but... :). 
     	// expects a C function on top of the source Lua stack
-	copy_func( lua_State *dest, lua_State* source)
+	copy_func(lua_State *dest, lua_State* source)
 	{
 		// extract C function pointer from source
-		lua_CFunction func = lua_tocfunction( source, -1);
+		lua_CFunction func = lua_tocfunction(source, -1);
 		// transfer upvalues
-		int nup = transfer_upvalues( dest, source);
+		int nup = transfer_upvalues(dest, source);
 		// dest Lua stack contains a copy of all upvalues
-		lua_pushcfunction( dest, func, nup);
+		lua_pushcfunction(dest, func, nup);
 	}
    @@ -1524,12 +1524,12 @@ events to a common Linda, but... :). 
     	// expects a C function on top of the source Lua stack
-	copy_func( lua_State *dest, lua_State* source)
+	copy_func(lua_State *dest, lua_State* source)
 	{
 		// fetch function 'name' from source lookup database
-		char const* funcname = lookup_func_name( source, -1);
+		char const* funcname = lookup_func_name(source, -1);
 		// lookup a function bound to this name in the destination state, and push it on the stack
-		push_resolved_func( dest, funcname);
+		push_resolved_func(dest, funcname);
 	}
    @@ -1590,7 +1590,7 @@ events to a common Linda, but... :). 

    -	int luaopen_module( lua_State *L )
+	int luaopen_module(lua_State *L )
 	{
 		static char been_here;  /* 0 by ANSI C */
 
@@ -1607,26 +1607,26 @@ events to a common Linda, but... :).
 
    Clonable full userdata in your own apps
    
 
    
 	An alternative way of passing full userdata across lanes uses a new __lanesclone metamethod.
-	When a deep userdata is cloned, Lanes calls __lanesclone once, in the context of the source lane.
    
-	The call receives the clone and original as light userdata, plus the actual userdata size, as in clone:__lanesclone(original,size), and should perform the actual cloning.
    
+	When a deep userdata is cloned, Lanes calls __lanesclone once, in the context of the source lane.
    
+	The call receives the clone and original as light userdata, plus the actual userdata size, as in clone:__lanesclone(original,size), and should perform the actual cloning.
    
 	A typical implementation would look like:
 
    -static int clonable_lanesclone( lua_State* L)
+static int clonable_lanesclone(lua_State* L)
 {
-	switch( lua_gettop( L))
+	switch(lua_gettop(L))
 	{
 		case 3:
 		{
-			struct s_MyClonableUserdata* self = lua_touserdata( L, 1);
-			struct s_MyClonableUserdata* from = lua_touserdata( L, 2);
-			size_t len = lua_tointeger( L, 3);
-			assert( len == sizeof(struct s_MyClonableUserdata));
+			struct s_MyClonableUserdata* self = lua_touserdata(L, 1);
+			struct s_MyClonableUserdata* from = lua_touserdata(L, 2);
+			size_t len = lua_tointeger(L, 3);
+			assert(len == sizeof(struct s_MyClonableUserdata));
 			*self = *from;
 		}
 		return 0;
 
 		default:
-		(void) luaL_error( L, "Lanes called clonable_lanesclone with unexpected parameters");
+		std::ignore = luaL_error(L, "Lanes called clonable_lanesclone with unexpected parameters");
 	}
 	return 0;
 }
@@ -1639,20 +1639,20 @@ static int clonable_lanesclone( lua_State* L)
 
     int luaopen_deep_test(lua_State* L)
 {
-	luaL_newlib( L, deep_module);
+	luaL_newlib(L, deep_module);
 
 	// preregister the metatables for the types we can instanciate so that Lanes can know about them
-	if( luaL_newmetatable( L, "clonable"))
+	if (luaL_newmetatable(L, "clonable"))
 	{
-		luaL_setfuncs( L, clonable_mt, 0);
+		luaL_setfuncs(L, clonable_mt, 0);
 		lua_pushvalue(L, -1);
 		lua_setfield(L, -2, "__index");
 	}
 	lua_setfield(L, -2, "__clonableMT"); // actual name is not important
 
-	if( luaL_newmetatable( L, "deep"))
+	if (luaL_newmetatable(L, "deep"))
 	{
-		luaL_setfuncs( L, deep_mt, 0);
+		luaL_setfuncs(L, deep_mt, 0);
 		lua_pushvalue(L, -1);
 		lua_setfield(L, -2, "__index");
 	}
@@ -1666,10 +1666,10 @@ int luaopen_deep_test(lua_State* L)
 
    
 	Then a new clonable userdata instance can just do like any non-Lanes aware userdata, as long as its metatable contains the aforementionned __lanesclone method.
 
    -int luaD_new_clonable( lua_State* L)
+int luaD_new_clonable(lua_State* L)
 {
-	lua_newuserdata( L, sizeof( struct s_MyClonableUserdata));
-	luaL_setmetatable( L, "clonable");
+	lua_newuserdata(L, sizeof(struct s_MyClonableUserdata));
+	luaL_setmetatable(L, "clonable");
 	return 1;
 }
 
    
@@ -1684,7 +1684,7 @@ int luaD_new_clonable( lua_State* L)
 
      
 	
    1. 
 		Provide an identity function for your userdata, in C. This function is used for creation and deletion of your deep userdata (the shared resource), and for making metatables for the state-specific proxies for accessing it. The prototype is
-		
      	void* idfunc( lua_State* L, DeepOp op_);
      
+		
      	void* idfunc(lua_State* L, DeepOp op_);
      
 		op_ can be one of:
 		
        
 			
      • DeepOp::New: requests the creation of a new object, whose pointer is returned. Said object must derive from DeepPrelude.
        • 
@@ -1735,8 +1735,8 @@ int luaD_new_clonable( lua_State* L)
 	In multithreaded scenarios, giving multiple parameters to print() or file:write() may cause them to be overlapped in the output, something like this:
 
 
        -	A:  print( 1, 2, 3, 4 )
-	B:  print( 'a', 'b', 'c', 'd' )
+	A:  print(1, 2, 3, 4 )
+	B:  print('a', 'b', 'c', 'd' )
 
 	1   a   b   2   3   c   d   4
 
        
@@ -1803,4 +1803,3 @@ int luaD_new_clonable( lua_State* L)
 
 
 
-
    
\ No newline at end of file
diff --git a/src/uniquekey.h b/src/uniquekey.h
index e592f0a..a89ecd3 100644
--- a/src/uniquekey.h
+++ b/src/uniquekey.h
@@ -13,7 +13,7 @@ class UniqueKey
 
     public:
 
-    constexpr UniqueKey(uint64_t val_)
+    constexpr explicit UniqueKey(uint64_t val_)
 #if LUAJIT_FLAVOR() == 64 // building against LuaJIT headers for 64 bits, light userdata is restricted to 47 significant bits, because LuaJIT uses the other bits for internal optimizations
     : m_storage{ static_cast(val_ & 0x7fffffffffffull) }
 #else // LUAJIT_FLAVOR()
-- 
cgit v1.2.3-55-g6feb