summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBenoit Germain <bnt period germain arrobase gmail period com>2014-01-16 14:17:23 +0100
committerBenoit Germain <bnt period germain arrobase gmail period com>2014-01-16 14:17:23 +0100
commit48e375d31897056b3ab62106ba84552fd554f1c8 (patch)
tree45a94427832948de6ee123dd7d36f50cb5344bfe
parent3741cb9dbc367b6438ecc1d117b3e108ac93163e (diff)
downloadlanes-48e375d31897056b3ab62106ba84552fd554f1c8.tar.gz
lanes-48e375d31897056b3ab62106ba84552fd554f1c8.tar.bz2
lanes-48e375d31897056b3ab62106ba84552fd554f1c8.zip
Cancellation improvements and some fixes
* bumped version to 3.7.8 * lane:cancel() now accepts a boolean second argument when soft cancelling (negative timeout) to wake the thread if necessary * if a blocked linda send() or receive() call is interrupted by a cancellation request, it returns CANCEL_ERROR so that this case can be differentiated from a simple timeout * fixed WIN32 THREAD_CREATE() wrong _beginthreadex() error detection * fatal WIN32 threading errors retrieve and output the error description string with FormatMessage() * fixed missing lanes.set_singlethreaded * fixed perftest.lua * added test/cancel.lua
-rw-r--r--index.html25
1 files changed, 17 insertions, 8 deletions
diff --git a/index.html b/index.html
index c62f64f..3b64cb4 100644
--- a/index.html
+++ b/index.html
@@ -70,7 +70,7 @@
70 </p> 70 </p>
71 71
72 <p> 72 <p>
73 This document was revised on 09-Jan-14, and applies to version <tt>3.7.7</tt>. 73 This document was revised on 16-Jan-14, and applies to version <tt>3.7.8</tt>.
74 </p> 74 </p>
75 </font> 75 </font>
76 </center> 76 </center>
@@ -880,13 +880,18 @@
880<h2 id="cancelling">Cancelling</h2> 880<h2 id="cancelling">Cancelling</h2>
881 881
882<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre> 882<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
883 bool[,reason] = lane_h:cancel( [timeout_secs=0.0,] [force_kill_bool = false] [, forcekill_timeout=0.0]) 883 bool[,reason] = lane_h:cancel( [positive_timeout_secs=0.0] [, force_kill_bool = false] [, forcekill_timeout=0.0])
884 bool[,reason] = lane_h:cancel( negative_timeout_secs [, wake_bool = false])
884</pre></td></tr></table> 885</pre></td></tr></table>
885 886
886<p> 887<p>
887 <tt>cancel()</tt> sends a cancellation request to the lane.<br/> 888 <tt>cancel()</tt> sends a cancellation request to the lane.<br/>
888 If <tt>timeout_secs</tt> is negative (aka "soft cancel"), starting with version 3.6.3, will only cause <tt>cancel_test()</tt> to return <tt>true</tt>, so that the lane can cleanup manually (the actual value is irrelevant). You can't provide the additional arguments in that case.<br/> 889 First argument is a timeout, that defaults to 0 if not specified. (Starting with version 3.6.3) signification of the following arguments differ depending on whether the timeout is negative or not.
889 If <tt>timeout_secs</tt> is positive (aka "hard cancel"), waits for the request to be processed, or a timeout to occur.<br/> 890 <br/>
891 If <tt>timeout_secs</tt> is negative (aka "soft cancel"), cancellation will only cause <tt>cancel_test()</tt> to return <tt>true</tt>, so that the lane can cleanup manually (the actual value is irrelevant).
892 If <tt>wake_bool</tt> is <tt>true</tt>, the lane is also signalled so that execution returns from any pending linda operation.
893 <br/>
894 If <tt>timeout_secs</tt> is positive (aka "hard cancel"), 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).
890 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. 895 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.
891 Returns <tt>true</tt> if soft cancelling, or the 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. 896 Returns <tt>true</tt> if soft cancelling, or the 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.
892</p> 897</p>
@@ -1010,11 +1015,11 @@
1010<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre> 1015<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
1011 h = lanes.linda( [opt_name]) 1016 h = lanes.linda( [opt_name])
1012 1017
1013 bool = h:send( [timeout_secs,] key, ...) 1018 bool|cancel_error = h:send( [timeout_secs,] key, ...)
1014 1019
1015 [key, val] = h:receive( [timeout_secs,] key [, ...]) 1020 [key, val]|[cancel_error] = h:receive( [timeout_secs,] key [, ...])
1016 1021
1017 [key, val [, ...]] = h:receive( timeout, h.batched, key, n_uint_min[, n_uint_max]) 1022 [key, val [, ...]]|[cancel_error] = h:receive( timeout, h.batched, key, n_uint_min[, n_uint_max])
1018 1023
1019 [true] = h:limit( key, n_uint) 1024 [true] = h:limit( key, n_uint)
1020</pre></td></tr></table> 1025</pre></td></tr></table>
@@ -1041,12 +1046,16 @@
1041 1046
1042<p> 1047<p>
1043 <tt>send()</tt> returns <tt>true</tt> if the sending succeeded, and <tt>false</tt> if the queue limit was met, and the queue did not empty enough during the given timeout. 1048 <tt>send()</tt> returns <tt>true</tt> if the sending succeeded, and <tt>false</tt> if the queue limit was met, and the queue did not empty enough during the given timeout.
1049 <br/>
1050 (Since version 3.7.8) <tt>send()</tt> returns <tt>lanes.cancel_error</tt> if interrupted by a soft cancel request.
1044</p> 1051</p>
1045 1052
1046<p> 1053<p>
1047 Equally, <tt>receive()</tt> returns a key and the value extracted from it, or nothing for timeout. Note that <tt>nil</tt>s can be sent and received; the <tt>key</tt> value will tell it apart from a timeout. 1054 Equally, <tt>receive()</tt> returns a key and the value extracted from it, or nothing for timeout. Note that <tt>nil</tt>s can be sent and received; the <tt>key</tt> value will tell it apart from a timeout.
1048 <br> 1055 <br/>
1049 Version 3.4.0 introduces an API change in the returned values: <tt>receive()</tt> returns the key followed by the value(s), in that order, and not the other way around. 1056 Version 3.4.0 introduces an API change in the returned values: <tt>receive()</tt> returns the key followed by the value(s), in that order, and not the other way around.
1057 <br/>
1058 (Since version 3.7.8) <tt>receive()</tt> returns <tt>lanes.cancel_error</tt> if interrupted by a soft cancel request.
1050</p> 1059</p>
1051 1060
1052<p> 1061<p>