From 022e40cc71beda874d0bad2cec227e472d5dd4af Mon Sep 17 00:00:00 2001 From: Benoit Germain Date: Fri, 18 Apr 2025 10:26:19 +0200 Subject: New feature: Linda periodical cancellation checks * lanes.linda() api change: takes all settings in a single table argument * new linda creation argument wake_period * new lanes.configure setting linda_wake_period * adjusted all unit tests (one TODO test fails on purpose) --- docs/index.html | 46 +++++++++++++++++++++++++++++++++++----------- 1 file changed, 35 insertions(+), 11 deletions(-) (limited to 'docs') diff --git a/docs/index.html b/docs/index.html index 4dd5848..116fc0a 100644 --- a/docs/index.html +++ b/docs/index.html @@ -64,13 +64,13 @@


- Copyright © 2007-24 Asko Kauppi, Benoit Germain. All rights reserved. + Copyright © 2007-25 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 17-Mar-25, and applies to version 4.0.0. + This document was revised on 18-Apr-25, and applies to version 4.0.0.

@@ -271,7 +271,7 @@

- lanes.configure accepts an optional options table as sole argument. + lanes.configure accepts an optional table as sole argument. @@ -336,6 +336,22 @@ + + + + + +
name
+ .linda_wake_period + + number > 0 + + Sets the default period in seconds a linda will wake by itself during blocked operations. Default is never.
+ When a Linda enters a blocking call (send(), receive(), receive_batched(), sleep()), it normally sleeps either until the operation completes + or the specified timeout expires. With this setting, the default behavior can be changed to wake periodically. This can help for example with timing issues where a lane is signalled + for cancellation, but a linda inside the lane was in the middle of processing an operation but did not actually start the wait. This can result in the signal to be ignored, thus + causing the Linda to wait out the full operation timeout before cancellation is processed. +
.nb_user_keepers @@ -1222,7 +1238,7 @@ 
 	local lanes = require "lanes"
 
-	local linda = lanes.linda("my linda")
+	local linda = lanes.linda{name = "my linda"}
 
 	local function loop(max)
 		for i = 1, max do
@@ -1276,16 +1292,24 @@
 

 
 
-	h = lanes.linda([name],[group],[close_handler])
+	h = lanes.linda(table|nil)
 

 
 

-	Arguments to lanes.linda()  can be provided in any order, as long as there is a single string, a single number, and a single callable value (all are optional).

-	Converting the linda to a string will yield the provided name prefixed by "Linda: ".

-	If opt_name is omitted, it will evaluate to an hexadecimal number uniquely representing that linda when the linda is converted to a string. The value is the same as returned by linda:deep().

-	If opt_name is "auto", Lanes will try to construct a name from the source location that called lanes.linda(). If that fails, the linda name will be "<unresolved>".

-	If Lanes is configured with more than one Keeper state, group is mandatory.

-	If the linda is to-be-closed (Lua 5.4+), and a close_handler is provided, it will be called with all the provided arguments. For older Lua versions, its presence will cause an error.
+	Argument to lanes.linda() is either nil or a single table. The table may contain the following entries:
+	
    
+		
  • close_handler: a callable object (function or table/userdata with __call metamethod). If provided, and the linda is to-be-closed (Lua 5.4+), it will be called with all the provided arguments. For older Lua versions, its presence is ignored.
    • 
+		
  • group: an integer between 0 and the number of Keeper states. Mandatory if Lanes is configured with more than one Keeper state. Group 0 is used by the internal timer linda.
    • 
+		
  • 
+			name: a string. Converting the linda to a string will yield the provided name prefixed by "Linda: ".
+			If omitted or empty, it will evaluate to the string representation of a hexadecimal number uniquely representing that linda when the linda is converted to a string. The numeric value is the same as returned by linda:deep().
    
+			If "auto", Lanes will try to construct a name from the source location that called lanes.linda(). If that fails, the linda name will be "<unresolved>".
+		
    • 
+		
  • 
+			wake_period: a number > 0 (unit: seconds). If provided, overrides linda_wake_period provided to lanes.configure().
+		
    • 
+	

+	Unknown fields are silently ignored.
 

 
 
-- 
cgit v1.2.3-55-g6feb