aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorBenoit Germain <benoit.germain@ubisoft.com>2024-06-28 17:52:29 +0200
committerBenoit Germain <benoit.germain@ubisoft.com>2024-06-28 17:52:29 +0200
commitac12af5c39b0689edb931fbe9a162db5687d392f (patch)
tree91dd99b3808a1dae237a7f343c449c999e80a4f1 /docs
parent726aee3fbb909946e69866cc6c4497c5ec365fe8 (diff)
downloadlanes-ac12af5c39b0689edb931fbe9a162db5687d392f.tar.gz
lanes-ac12af5c39b0689edb931fbe9a162db5687d392f.tar.bz2
lanes-ac12af5c39b0689edb931fbe9a162db5687d392f.zip
Make Lanes crash on purpose at shutdown if some lanes still run
Diffstat (limited to 'docs')
-rw-r--r--docs/index.html50
1 files changed, 23 insertions, 27 deletions
diff --git a/docs/index.html b/docs/index.html
index 148b5ab..1cc007f 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -370,18 +370,6 @@
370 </tr> 370 </tr>
371 371
372 <tr valign=top> 372 <tr valign=top>
373 <td id="shutdown_mode">
374 <code>.shutdown_mode</code>
375 </td>
376 <td>
377 <tt>"hard"</tt>/<tt>"soft"</tt>/<tt>"call"</tt>/<tt>"ret"</tt>/<tt>"line"</tt>/<tt>"count"</tt>
378 </td>
379 <td>
380 Select the cancellation mode used at Lanes shutdown to request free running lane termination. See <a href="#cancelling">lane cancellation</a>. Default is <tt>"hard"</tt>.
381 </td>
382 </tr>
383
384 <tr valign=top>
385 <td id="shutdown_timeout"> 373 <td id="shutdown_timeout">
386 <code>.shutdown_timeout</code> 374 <code>.shutdown_timeout</code>
387 </td> 375 </td>
@@ -389,7 +377,9 @@
389 number >= 0 377 number >= 0
390 </td> 378 </td>
391 <td> 379 <td>
392 Sets the duration in seconds Lanes will wait for graceful termination of running lanes at application shutdown. Default is <tt>0.25</tt>. 380 Sets the duration in seconds Lanes will wait for graceful termination of running lanes at application shutdown. Default is <tt>0.25</tt>.<br />
381 Lanes signals all lanes for cancellation with <tt>"soft"</tt>, <tt>"hard"</tt>, and <tt>"all"</tt> modes, in that order. Each attempt has <tt>shutdown_timeout</tt> seconds to succeed before the next one.<br />
382 Then there is a last chance at cleanup with <a href="#finally"><tt>lanes.finally()</tt></a>. If some lanes are still running after that point, shutdown will freeze the application forever. It is YOUR responsibility to cleanup properly after yourself.
393 </td> 383 </td>
394 </tr> 384 </tr>
395 385
@@ -462,7 +452,7 @@
462 </tr> 452 </tr>
463</table> 453</table>
464 454
465<p> 455<p id="finally">
466 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). 456 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).
467</p> 457</p>
468 458
@@ -479,7 +469,8 @@
479<p> 469<p>
480 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).<br /> 470 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).<br />
481 Only the last registered finalizer is kept. It can be cleared by passing <tt>nil</tt> or nothing.<br /> 471 Only the last registered finalizer is kept. It can be cleared by passing <tt>nil</tt> or nothing.<br />
482 The installed function is called after all free-running lanes are terminated, but before lindas become unusable.<br /> 472 The installed function is called after all free-running lanes got a chance to terminate (see<a href="#shutdown_timeout"><tt>shutdown_timeout</tt></a>), but before lindas become unusable.<br />
473 The finalizer receives a single argument, a <tt>bool</tt> indicating whether some Lanes are still running or not at that point. It is possible to inspect them with <a href="#tracking">tracking</a>.<br />
483 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. 474 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.
484</p> 475</p>
485 476
@@ -1064,26 +1055,31 @@
1064 <br /> 1055 <br />
1065 <tt>cancel()</tt> sends a cancellation request to the lane. 1056 <tt>cancel()</tt> sends a cancellation request to the lane.
1066 <br /> 1057 <br />
1067 First argument is a <tt>mode</tt> can be one of <tt>"hard"</tt>, <tt>"soft"</tt>, <tt>"call"</tt>, <tt>"ret"</tt>, <tt>"line"</tt>, <tt>"count"</tt>. 1058 First argument is a <tt>mode</tt> can be one of:
1059 <ul>
1060 <li>
1061 <tt>"soft"</tt>: Cancellation will only cause <tt>cancel_test()</tt> to return <tt>true</tt>, so that the lane can cleanup manually.
1062 </li>
1063 <li>
1064 <tt>"hard"</tt>: waits for the request to be processed, or a timeout to occur. <a href="#lindas">Linda</a> operations detecting the cancellation request will raise a special cancellation error (meaning they won't return in that case).<br />
1065 <tt>wake_lane</tt> defaults to <tt>true</tt>, and <tt>timeout</tt> defaults to 0 if not specified.
1066 </li>
1067 <li>
1068 <tt>"call"</tt>, <tt>"ret"</tt>, <tt>"line"</tt>, <tt>"count"</tt>: Asynchronously install the corresponding hook, then behave as <tt>"hard"</tt>.
1069 </li>
1070 <li>
1071 <tt>"all"</tt>: Installs all hooks in one shot, just to be sure.
1072 </li>
1073 </ul>
1068 If <tt>mode</tt> is not specified, it defaults to <tt>"hard"</tt>. 1074 If <tt>mode</tt> is not specified, it defaults to <tt>"hard"</tt>.
1069 If <tt>wake_lane</tt> is <tt>true</tt>, the lane is also signalled so that execution returns from any pending <a href="#lindas">Linda</a> operation. <a href="#lindas">Linda</a> operations detecting the cancellation request return <tt>lanes.cancel_error</tt>. 1075 If <tt>wake_lane</tt> is <tt>true</tt>, the lane is also signalled so that execution returns from any pending <a href="#lindas">Linda</a> operation. <a href="#lindas">Linda</a> operations detecting the cancellation request return <tt>lanes.cancel_error</tt>.
1070</p> 1076</p>
1071<p> 1077<p>
1072 If <tt>mode</tt> is <tt>"soft"</tt>, cancellation will only cause <tt>cancel_test()</tt> to return <tt>true</tt>, so that the lane can cleanup manually.<br />
1073</p>
1074<p>
1075 If <tt>mode</tt> is <tt>"hard"</tt>, waits for the request to be processed, or a timeout to occur. <a href="#lindas">Linda</a> operations detecting the cancellation request will raise a special cancellation error (meaning they won't return in that case).<br />
1076 <tt>wake_lane</tt> defaults to <tt>true</tt>, and <tt>timeout</tt> defaults to 0 if not specified.
1077</p>
1078<p>
1079 Other values of <tt>mode</tt> will asynchronously install the corresponding hook, then behave as <tt>"hard"</tt>.
1080</p>
1081<p>
1082 Returns <tt>true, lane_h.status</tt> if lane was already done (in <tt>"done"</tt>, <tt>"error"</tt> or <tt>"cancelled"</tt> status), or the cancellation was fruitful within <tt>timeout_secs</tt> timeout period.<br /> 1078 Returns <tt>true, lane_h.status</tt> if lane was already done (in <tt>"done"</tt>, <tt>"error"</tt> or <tt>"cancelled"</tt> status), or the cancellation was fruitful within <tt>timeout_secs</tt> timeout period.<br />
1083 Returns <tt>false, "timeout"</tt> otherwise. 1079 Returns <tt>false, "timeout"</tt> otherwise.
1084</p> 1080</p>
1085<p> 1081<p>
1086 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. 1082 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.
1087</p> 1083</p>
1088<p> 1084<p>
1089 Cancellation is tested <u>before</u> going to sleep in <tt>receive()</tt> or <tt>send()</tt> calls and after executing <tt>cancelstep</tt> Lua statements. A pending <tt>receive()</tt>or <tt>send()</tt> call is awakened. 1085 Cancellation is tested <u>before</u> going to sleep in <tt>receive()</tt> or <tt>send()</tt> calls and after executing <tt>cancelstep</tt> Lua statements. A pending <tt>receive()</tt>or <tt>send()</tt> call is awakened.