From 726aee3fbb909946e69866cc6c4497c5ec365fe8 Mon Sep 17 00:00:00 2001 From: Benoit Germain Date: Thu, 27 Jun 2024 12:40:36 +0200 Subject: linda:limit() and linda:set() return a second value, a string representing the fill status --- docs/index.html | 37 +++++++++++++++++++------------------ 1 file changed, 19 insertions(+), 18 deletions(-) (limited to 'docs') diff --git a/docs/index.html b/docs/index.html index 8e84fcb..148b5ab 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1222,15 +1222,16 @@ 

-	bool|(nil,[lanes.cancel_error|"timeout"]) = h:limit(key, <limit>)
-	>limit< = h:limit(key)
+	bool,string|(nil,[lanes.cancel_error|"timeout"]) = h:limit(key, <limit>)
+	(number|string),string = h:limit(key)

By default, queue sizes are unlimited but limits can be enforced using the limit() method. This can be useful to balance execution speeds in a producer/consumer scenario.
A limit of 0 is allowed to block everything. "unlimited" removes the limit.
- If the key was full but the limit change added some room, limit() returns true and the Linda is signalled so that send()-blocked threads are awakened, else the return value is false. - If no limit is provided, limit() returns a single value, the current limit for the specified key.
+ If the key was full but the limit change added some room, limit() first return value is true and the Linda is signalled so that send()-blocked threads are awakened, else the return value is false. + If no limit is provided, limit() first return value is the current limit for the specified key.
+ The second returned value is a string representing the fill status relatively to the key's current limit (one of "over", "under", "exact"). Whether reading or writing, if the Linda is cancelled, limit() returns nil, lanes.cancel_error.

@@ -1292,30 +1293,30 @@ 

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

- The table access methods are for accessing a slot without queuing or consuming. They can be used for making shared tables of storage among the lanes.
- Writing to a slot never blocks because it ignores the limit. It overwrites existing value and clears any possible queued entries.
- Reading doesn't block either because get() returns: + get()/set() and send()/receive() can be used together; reading a slot essentially peeks the next outcoming value of a queue.
+ get()/set() are for accessing a key without queuing or consuming. They can be used for making shared tables of storage among the lanes.
+ Writing to a key never blocks because it ignores the limit. It overwrites existing values and clears any possible queued entries.
+

+

+ get() can read several values at once, and does not block. Return values ares:

- Table access and send()/receive() can be used together; reading a slot essentially peeks the next outcoming value of a queue. -

- -

- set() signals the Linda for write if a value is stored. If nothing special happens, set() returns nothing.
- If the key was full but the new data count of the key after set() is below its limit, set() returns true and the Linda is also signaled for read so that send()-blocked threads are awakened.

-

- set() can write several values at the specified key, writing nil values is now possible, and clearing the contents at the specified key is done by not providing any value.
- Also, get() can read several values at once. If the key contains no data, get() returns no value. This can be used to separate the case when reading stored nil values. + set() can write several values at the specified key. Writing nil values is possible, and clearing the contents at the specified key is done by not providing any value.
+ If set() actually stores data, the Linda is signalled for write, so that receive()-blocked Lanes are awakened.
+ Clearing the contents of a non-existent key does not create it!
+ If the key was full but the new data count of the key after set() is below its limit, set() first return value is true and the Linda is also signaled for read, so that send()-blocked Lanes are awakened.
+ If the key was not already full, nothing additional happens, and set() first return value is false.
+ The second return value is a string representing the fill status relatively to the key's current limit (one of "over", "under", "exact").

-- cgit v1.2.3-55-g6feb