From ac12af5c39b0689edb931fbe9a162db5687d392f Mon Sep 17 00:00:00 2001 From: Benoit Germain Date: Fri, 28 Jun 2024 17:52:29 +0200 Subject: Make Lanes crash on purpose at shutdown if some lanes still run --- docs/index.html | 50 +++++++++++++++++++++++--------------------------- 1 file changed, 23 insertions(+), 27 deletions(-) (limited to 'docs') diff --git a/docs/index.html b/docs/index.html index 148b5ab..1cc007f 100644 --- a/docs/index.html +++ b/docs/index.html @@ -369,18 +369,6 @@ - - - .shutdown_mode - - - "hard"/"soft"/"call"/"ret"/"line"/"count" - - - Select the cancellation mode used at Lanes shutdown to request free running lane termination. See lane cancellation. Default is "hard". - - - .shutdown_timeout @@ -389,7 +377,9 @@ number >= 0 - Sets the duration in seconds Lanes will wait for graceful termination of running lanes at application shutdown. Default is 0.25. + Sets the duration in seconds Lanes will wait for graceful termination of running lanes at application shutdown. Default is 0.25.
+ Lanes signals all lanes for cancellation with "soft", "hard", and "all" modes, in that order. Each attempt has shutdown_timeout seconds to succeed before the next one.
+ Then there is a last chance at cleanup with lanes.finally(). If some lanes are still running after that point, shutdown will freeze the application forever. It is YOUR responsibility to cleanup properly after yourself. @@ -462,7 +452,7 @@ -

+

It is also possible to install a function that will be called when Lanes is shutdown (that is, when the first state that required Lanes is closed).

@@ -479,7 +469,8 @@

An error will be raised if you attempt to do this from inside a lane, or on bad arguments (non-function, or too many arguments).
Only the last registered finalizer is kept. It can be cleared by passing nil or nothing.
- The installed function is called after all free-running lanes are terminated, but before lindas become unusable.
+ The installed function is called after all free-running lanes got a chance to terminate (seeshutdown_timeout), but before lindas become unusable.
+ The finalizer receives a single argument, a bool indicating whether some Lanes are still running or not at that point. It is possible to inspect them with tracking.
If an error occurs inside this finalizer, it is silently swallowed, since it happens only during state shutdown, and you can't do anything about it.

@@ -1064,26 +1055,31 @@
cancel() sends a cancellation request to the lane.
- First argument is a mode can be one of "hard", "soft", "call", "ret", "line", "count". + First argument is a mode can be one of: + If mode is not specified, it defaults to "hard". If wake_lane is true, the lane is also signalled so that execution returns from any pending Linda operation. Linda operations detecting the cancellation request return lanes.cancel_error.

-

- If mode is "soft", cancellation will only cause cancel_test() to return true, so that the lane can cleanup manually.
-

-

- If mode is "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).
- wake_lane defaults to true, and timeout defaults to 0 if not specified. -

-

- Other values of mode will asynchronously install the corresponding hook, then behave as "hard". -

Returns true, lane_h.status if lane was already done (in "done", "error" or "cancelled" status), or the cancellation was fruitful within timeout_secs timeout period.
Returns false, "timeout" otherwise.

- If the lane is still running after the timeout expired, there is a chance lanes will raise an error 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() or send() calls and after executing cancelstep Lua statements. A pending receive()or send() call is awakened. -- cgit v1.2.3-55-g6feb