From 4e109a0c12d245b155bf03cb561c01b242666395 Mon Sep 17 00:00:00 2001 From: Benoit Germain Date: Mon, 29 Sep 2025 16:02:45 +0200 Subject: Many small doc tweaks --- docs/index.html | 81 ++++++++++++++++++++++++++++++--------------------------- 1 file changed, 42 insertions(+), 39 deletions(-) (limited to 'docs') diff --git a/docs/index.html b/docs/index.html index 9270ce6..eba39bb 100644 --- a/docs/index.html +++ b/docs/index.html @@ -71,7 +71,7 @@

- This document was revised on 22-Sep-2025, and applies to version 4.0.0. + This document was revised on 29-Sep-2025, and applies to version 4.0.0.

@@ -186,10 +186,11 @@
  • lanes.coro(): start a coroutine-like lane
  • lanes.finally(): install a function called on Lanes shutdown
  • lanes.gen(): start a lane as a regular function
    • -
  • lanes.genactomic(): obtain an atomic counter
    • +
  • lanes.genatomic(): obtain an atomic counter
  • lanes.genlock(): obtain an atomic-like data stack
    • -
  • lanes.linda(): create a Linda
    • +
  • lanes.linda(): create a linda
  • lanes.nameof(): find where a value exists
    • +
  • lanes.null: a light userdata used to represent nil in data transfers
  • lanes.thread_priority_range(): obtain the valid range of thread priorities
  • lanes.now_secs(): obtain the current clock value
  • lanes.register(): scan modules so that functions using them can be transferred
    • @@ -198,6 +199,7 @@
  • lanes.threads(): obtain a list of all lanes
  • lanes.sleep(): sleep for a given duration
  • lanes.timer(): start a timer
    • +
  • lanes.timer_lane: the lane that manages timers
  • lanes.timers(): list active timers
    • @@ -222,11 +224,11 @@
  • - Given some Linda l + Given some linda l @@ -447,11 +449,11 @@ 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 + 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. + 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. @@ -612,7 +614,7 @@

    -

    Creation

    +

    Lane Creation

    The following sample shows preparing a function for parallel calling, and calling it with varying arguments. Each of the two results is calculated in a separate OS thread, parallel to the calling one. Reading the results joins the threads, waiting for any results not already there. @@ -851,7 +853,7 @@ table Lists modules that have to be required in order to be able to transfer functions/userdata they exposed. Non-Lua functions are searched in lookup tables. - These tables are built from the modules listed here. required must be an array of strings, each one being the name of a module to be required. Each module is required with require() before the lanes function is invoked. + These tables are built from the modules listed here. required must be an array of strings, each one being the name of a module to be required. Each module is required with require() before the lane function is invoked. So, from the required module's point of view, requiring it manually from inside the lane body or having it required this way doesn't change anything. From the lane body's point of view, the only difference is that a module not creating a global won't be accessible. Therefore, a lane body will also have to require a module manually, but this won't do anything more (see Lua's require documentation).
    ATTEMPTING TO TRANSFER A FUNCTION REGISTERED BY A MODULE NOT LISTED HERE WILL RAISE AN ERROR. @@ -865,7 +867,7 @@ Sets the error reporting mode. One of "minimal" (the default), "basic", "extended".
    "minimal" yields only the location of the error.
    - The other 2 yield a full stack trace, with different amounts of data extracted from the debug infos. See Results. + The other two options yield a full stack trace, with different amounts of data extracted from the debug infos. See Results. @@ -946,7 +948,7 @@ - Coroutine lanes function mostly like regular coroutines. They can use coroutine.yield() normally.
    + Coroutine lanes operate mostly like regular coroutines. They can use coroutine.yield() normally.
    A yielded coroutine lane has a "suspended" status. It can be resumed with lane_h:resume(values...), which returns the yielded values. The latter can also be the returned values of lane_h:join() or accessed by regular lane indexing (see Results and errors).
    @@ -957,7 +959,7 @@
    - Just like regulare coroutines, the reply values passed to h:resume() are returned to the lane body at the coroutine.yield() point.
    + Just like regular coroutines, the reply values passed to h:resume() are returned to the lane body at the coroutine.yield() point.
    If a coroutine lane is suspended when it is joined either by indexing or lane_h:join(), active to-be-closed variables are closed at that point, and the Lane can no longer be resumed.

    Free running lanes

    @@ -1171,7 +1173,7 @@ 

    -	[val]= lane_h[1]
+	[val] = lane_h[1]

    @@ -1181,7 +1183,7 @@ 

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

    @@ -1255,12 +1257,12 @@

  • "soft": Cancellation will only cause cancel_test() to return "soft", so that the lane can cleanup manually.
    - Lindas will also check for cancellation inside blocking calls to early out based on their wake_period. + The linda will also check for cancellation inside blocking calls to early out based on its wake_period.
  • "hard": waits for the request to be processed, or a timeout to occur. linda operations detecting the cancellation request will raise a special cancellation error (meaning they won't return in that case).
    - If the lane isn't actually waiting on a Linda when the request is issued, a lane calling cancel_test() will see it return "hard". + If the lane isn't actually waiting on a linda when the request is issued, a lane calling cancel_test() will see it return "hard".
    wake_lane defaults to true, and timeout defaults to 0 if not specified.
    • @@ -1284,7 +1286,7 @@ timeout is an optional number >= 0. Defaults to infinite if left unspecified or nil.

    - If the lane is still running after the timeout expired, there is a chance lanes will freeze forever at shutdown when failing to terminate all free-running lanes within the specified timeout. + If the lane is still running after the timeout expired, there is a chance Lanes will freeze forever at shutdown when failing to terminate all free-running lanes within the specified timeout.

    Cancellation is tested before going to sleep in receive(), receive_batched() or send() calls and after executing cancelstep Lua statements. A pending receive()or send() call is awakened. @@ -1314,7 +1316,7 @@

    Lanes registers a function set_finalizer() in the lane's Lua state for doing this. - Any functions given to it will be called in the lane Lua state, just prior to closing it. It is possible to set more than one finalizer. They are not called in any particular order. + Any functions given to it will be called in the lane's Lua state, just prior to closing it. It is possible to set more than one finalizer. They are not called in any particular order.

    @@ -1390,18 +1392,18 @@ Registered functions and userdata transiting into a Keeper state are converted to a special dummy closure that holds its actual identity. On transit out, the identity is used to find the real function or userdata in the destination. For that reason, it is not possible to run user code inside a Keeper state. The only exception is on_state_create, which is handled in a special way. -

  • Consuming method is :receive (not in).
    • -
  • Non-consuming method is :get (not rd).
    • -
  • Two producer-side methods: :send and :set (not out).
    • -
  • send allows for sending multiple values -atomically- to a given slot.
    • -
  • receive can wait for multiple slots at once.
    • -
  • receive_batched can be used to consume more than one value from a single slot, as in linda:receive_batched(1.0, "slot", 3, 6).
    • -
  • restrict can restrain a particular slot to function either with send/receive or set/get.
    • -
  • Individual slots' queue length can be limited, balancing speed differences in a producer/consumer scenario (making :send wait).
    • +
  • Consuming method is :receive() (not in).
    • +
  • Non-consuming method is :get() (not rd).
    • +
  • Two producer-side methods: :send() and :set() (not out).
    • +
  • send() allows for sending multiple values -atomically- to a given slot.
    • +
  • receive() can wait for multiple slots at once.
    • +
  • receive_batched() can be used to consume more than one value from a single slot, as in linda:receive_batched(1.0, "slot", 3, 6).
    • +
  • restrict() can restrain a particular slot to function either with send()/receive() or set()/get().
    • +
  • Individual slots' 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>"
  • Several linda objects may share the same Keeper state. In case there is more than one user Keeper state, assignation must be controlled with the linda's group (an integer in [0,nb_user_keepers]). - Lanes has an internal linda used for timers and lanes.wait; this linda uses group 0. + Lanes has an internal linda used for timers and lanes.wait(); this linda uses group 0.
  • IMPORTANT: *all* linda operations are wrapped inside a lua_gc STOP/RESTART pair. @@ -1418,7 +1420,7 @@ Argument to lanes.linda() is either nil or a single table. The table may contain the following entries: