diff options
Diffstat (limited to '')
-rw-r--r-- | docs/index.html | 49 |
1 files changed, 28 insertions, 21 deletions
diff --git a/docs/index.html b/docs/index.html index ee5acfa..d24d3d7 100644 --- a/docs/index.html +++ b/docs/index.html | |||
@@ -425,7 +425,18 @@ | |||
425 | number >= 0 | 425 | number >= 0 |
426 | </td> | 426 | </td> |
427 | <td> | 427 | <td> |
428 | Sets the duration in seconds Lanes will wait for graceful termination of running lanes at application shutdown. Irrelevant for builds using pthreads. Default is <tt>0.25</tt>. | 428 | Sets the duration in seconds Lanes will wait for graceful termination of running lanes at application shutdown. Default is <tt>0.25</tt>. |
429 | </td> | ||
430 | </tr> | ||
431 | <tr valign=top> | ||
432 | <td id="shutdown_mode"> | ||
433 | <code>.shutdown_mode</code> | ||
434 | </td> | ||
435 | <td> | ||
436 | <tt>"hard"</tt>/<tt>"soft"</tt>/<tt>"call"</tt>/<tt>"ret"</tt>/<tt>"line"</tt>/<tt>"count"</tt> | ||
437 | </td> | ||
438 | <td> | ||
439 | 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>. | ||
429 | </td> | 440 | </td> |
430 | </tr> | 441 | </tr> |
431 | </table> | 442 | </table> |
@@ -875,16 +886,6 @@ | |||
875 | received <a href="#cancelling">cancellation</a> and finished itself. | 886 | received <a href="#cancelling">cancellation</a> and finished itself. |
876 | </td> | 887 | </td> |
877 | </tr> | 888 | </tr> |
878 | <tr> | ||
879 | <td/> | ||
880 | <td> | ||
881 | <tt>"killed"</tt> | ||
882 | </td> | ||
883 | <td/> | ||
884 | <td> | ||
885 | was forcefully killed by <tt>lane_h:cancel()</tt> | ||
886 | </td> | ||
887 | </tr> | ||
888 | </table> | 889 | </table> |
889 | </p> | 890 | </p> |
890 | 891 | ||
@@ -996,36 +997,33 @@ | |||
996 | <h2 id="cancelling">Cancelling</h2> | 997 | <h2 id="cancelling">Cancelling</h2> |
997 | 998 | ||
998 | <table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre> | 999 | <table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre> |
999 | bool[,reason] = lane_h:cancel( "soft" [, timeout] [, wake_bool]) | 1000 | bool[,reason] = lane_h:cancel( "soft" [, timeout] [, wake_lane]) |
1000 | bool[,reason] = lane_h:cancel( "hard" [, timeout] [, force [, forcekill_timeout]]) | 1001 | bool[,reason] = lane_h:cancel( "hard" [, timeout] [, wake_lane]) |
1001 | bool[,reason] = lane_h:cancel( [mode, hookcount] [, timeout] [, force [, forcekill_timeout]]) | 1002 | bool[,reason] = lane_h:cancel( [mode, hookcount] [, timeout] [, wake_lane]) |
1002 | </pre></td></tr></table> | 1003 | </pre></td></tr></table> |
1003 | 1004 | ||
1004 | <p> | 1005 | <p> |
1005 | <tt>cancel()</tt> sends a cancellation request to the lane.<br/> | 1006 | <tt>cancel()</tt> sends a cancellation request to the lane.<br/> |
1006 | First argument is a <tt>mode</tt> can be one of <tt>"hard"</tt>, <tt>"soft"</tt>, <tt>"count"</tt>, <tt>"line"</tt>, <tt>"call"</tt>, <tt>"ret"</tt>. | 1007 | 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>. |
1007 | If <tt>mode</tt> is not specified, it defaults to <tt>"hard"</tt>. | 1008 | If <tt>mode</tt> is not specified, it defaults to <tt>"hard"</tt>. |
1009 | If <tt>wake_lane</tt> is <tt>true</tt>, the lane is also signalled so that execution returns from any pending linda operation. Linda operations detecting the cancellation request return <tt>lanes.cancel_error</tt>. | ||
1008 | </p> | 1010 | </p> |
1009 | <p> | 1011 | <p> |
1010 | 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/> | 1012 | 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/> |
1011 | If <tt>wake_bool</tt> is <tt>true</tt>, the lane is also signalled so that execution returns from any pending linda operation. Linda operations detecting the cancellation request return <tt>lanes.cancel_error</tt>. | ||
1012 | </p> | 1013 | </p> |
1013 | <p> | 1014 | <p> |
1014 | If <tt>mode</tt> is <tt>"hard"</tt>, 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).<br/> | 1015 | If <tt>mode</tt> is <tt>"hard"</tt>, 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).<br/> |
1015 | <tt>timeout</tt> defaults to 0 if not specified. | 1016 | <tt>wake_lane</tt> defaults to <tt>true</tt>, and <tt>timeout</tt> defaults to 0 if not specified. |
1016 | </p> | 1017 | </p> |
1017 | <p> | 1018 | <p> |
1018 | Other values of <tt>mode</tt> will asynchronously install the corresponding hook, then behave as <tt>"hard"</tt>. | 1019 | Other values of <tt>mode</tt> will asynchronously install the corresponding hook, then behave as <tt>"hard"</tt>. |
1019 | </p> | 1020 | </p> |
1020 | <p> | 1021 | <p> |
1021 | If <tt>force_kill_bool</tt> is <tt>true</tt>, <tt>forcekill_timeout</tt> can be set to tell how long lanes will wait for the OS thread to terminate before raising an error. Windows threads always terminate immediately, but it might not always be the case with some pthread implementations. | ||
1022 | </p> | ||
1023 | <p> | ||
1024 | 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/> | 1022 | 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/> |
1025 | Returns <tt>false, "timeout"</tt> otherwise. | 1023 | Returns <tt>false, "timeout"</tt> otherwise. |
1026 | </p> | 1024 | </p> |
1027 | <p> | 1025 | <p> |
1028 | If the lane is still running after the timeout expired and <tt>force_kill</tt> is <tt>true</tt>, the OS thread running the lane is forcefully killed. This means no GC, probable OS resource leaks (thread stack, locks, DLL notifications), and should generally be the last resort. | 1026 | 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. |
1029 | </p> | 1027 | </p> |
1030 | <p> | 1028 | <p> |
1031 | 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. | 1029 | 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. |
@@ -1396,6 +1394,14 @@ events to a common Linda, but... :).</font> | |||
1396 | Default duration is null, which should only cause a thread context switch. | 1394 | Default duration is null, which should only cause a thread context switch. |
1397 | </p> | 1395 | </p> |
1398 | 1396 | ||
1397 | <table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre> | ||
1398 | number = lanes.now_secs() | ||
1399 | </pre></td></tr></table> | ||
1400 | |||
1401 | <p> | ||
1402 | Returns the current value of the clock used by timers and lindas. | ||
1403 | </p> | ||
1404 | |||
1399 | <!-- locks +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 1405 | <!-- locks +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
1400 | <hr/> | 1406 | <hr/> |
1401 | <h2 id="locks">Locks etc.</h2> | 1407 | <h2 id="locks">Locks etc.</h2> |
@@ -1797,3 +1803,4 @@ int luaD_new_clonable( lua_State* L) | |||
1797 | 1803 | ||
1798 | </body> | 1804 | </body> |
1799 | </html> | 1805 | </html> |
1806 | </pre> \ No newline at end of file | ||