summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBenoit Germain <bnt period germain arrobase gmail period com>2014-02-10 17:18:14 +0100
committerBenoit Germain <bnt period germain arrobase gmail period com>2014-02-10 17:18:14 +0100
commit6529cec6845443924f56f82a82d88a8102b30479 (patch)
treed8de97a05d78fd791ced4bd6ecbf35e083e5cd22
parent3ea37aec97638ff705b238f9c834ed8a930a6f86 (diff)
downloadlanes-6529cec6845443924f56f82a82d88a8102b30479.tar.gz
lanes-6529cec6845443924f56f82a82d88a8102b30479.tar.bz2
lanes-6529cec6845443924f56f82a82d88a8102b30479.zip
new API linda:cancel("read"|"write"|"both"|"none")
* bumped version to 3.8.4 * all linda operations return lanes.cancel_error on a cancelled linda * raised an internal string length so that longer linda names are fully output before truncation applies when doing tostring( linda)
-rw-r--r--index.html48
1 files changed, 34 insertions, 14 deletions
diff --git a/index.html b/index.html
index f639f18..1ad25a6 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 22-Jan-14, and applies to version <tt>3.8.3</tt>. 73 This document was revised on 10-Feb-14, and applies to version <tt>3.8.4</tt>.
74 </p> 74 </p>
75 </font> 75 </font>
76 </center> 76 </center>
@@ -902,10 +902,12 @@
902<p> 902<p>
903 <tt>cancel()</tt> sends a cancellation request to the lane.<br/> 903 <tt>cancel()</tt> sends a cancellation request to the lane.<br/>
904 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. 904 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.
905 <br/> 905</p>
906<p>
906 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). 907 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).
907 If <tt>wake_bool</tt> is <tt>true</tt>, the lane is also signalled so that execution returns from any pending linda operation. 908 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>.
908 <br/> 909</p>
910<p>
909 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). 911 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).
910 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. 912 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.
911 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. 913 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.
@@ -1007,7 +1009,7 @@
1007 print( "timed out") 1009 print( "timed out")
1008 break 1010 break
1009 end 1011 end
1010 print( "received: " .. val) 1012 print( tostring( linda) .. " received: " .. val)
1011 end 1013 end
1012</pre></td></tr></table> 1014</pre></td></tr></table>
1013 1015
@@ -1024,27 +1026,28 @@
1024 <li><tt>receive</tt> can wait for multiple keys at once.</li> 1026 <li><tt>receive</tt> can wait for multiple keys at once.</li>
1025 <li><tt>receive</tt> has a batched mode to consume more than one value from a single key, as in <tt>linda:receive( 1.0, linda.batched, "key", 3, 6).</tt></li> 1027 <li><tt>receive</tt> has a batched mode to consume more than one value from a single key, as in <tt>linda:receive( 1.0, linda.batched, "key", 3, 6).</tt></li>
1026 <li>individual keys' queue length can be limited, balancing speed differences in a producer/consumer scenario (making <tt>:send</tt> wait).</li> 1028 <li>individual keys' queue length can be limited, balancing speed differences in a producer/consumer scenario (making <tt>:send</tt> wait).</li>
1029 <li><tt>tostring( linda)</tt> returns a string of the form <tt>"Linda: &lt;opt_name&gt;"</tt></li>
1027 </ul> 1030 </ul>
1028</p> 1031</p>
1029 1032
1030<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre> 1033<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
1031 h = lanes.linda( [opt_name]) 1034 h = lanes.linda( [opt_name])
1032 1035
1033 bool|cancel_error = h:send( [timeout_secs,] key, ...) 1036 [true|lanes.cancel_error] = h:send( [timeout_secs,] key, ...)
1034 1037
1035 [key, val]|[cancel_error] = h:receive( [timeout_secs,] key [, ...]) 1038 [key, val]|[lanes.cancel_error] = h:receive( [timeout_secs,] key [, ...])
1036 1039
1037 [key, val [, ...]]|[cancel_error] = h:receive( timeout, h.batched, key, n_uint_min[, n_uint_max]) 1040 [key, val [, ...]]|[lanes.cancel_error] = h:receive( timeout, h.batched, key, n_uint_min[, n_uint_max])
1038 1041
1039 [true] = h:limit( key, n_uint) 1042 [true] = h:limit( key, n_uint)
1040</pre></td></tr></table> 1043</pre></td></tr></table>
1041 1044
1042<p> 1045<p>
1043 The <tt>send</tt> and <tt>receive</tt> methods use Linda keys as FIFO stacks (first in, first out). Timeouts are given in seconds (millisecond accuracy). If using numbers as the first Linda key, one must explicitly give <tt>nil</tt> as the timeout parameter to avoid ambiguities. 1046 The <tt>send()</tt> and <tt>receive()</tt> methods use Linda keys as FIFO stacks (first in, first out). Timeouts are given in seconds (millisecond accuracy). If using numbers as the first Linda key, one must explicitly give <tt>nil</tt> as the timeout parameter to avoid ambiguities.
1044</p> 1047</p>
1045 1048
1046<p> 1049<p>
1047 By default, stack sizes are unlimited but limits can be enforced using the <tt>limit</tt> method. This can be useful to balance execution speeds in a producer/consumer scenario. Any negative value removes the limit. 1050 By default, stack sizes are unlimited but limits can be enforced using the <tt>limit()</tt> method. This can be useful to balance execution speeds in a producer/consumer scenario. Any negative value removes the limit.
1048 <br/> 1051 <br/>
1049 A limit of 0 is allowed to block everything. 1052 A limit of 0 is allowed to block everything.
1050 <br/> 1053 <br/>
@@ -1083,9 +1086,9 @@
1083</p> 1086</p>
1084 1087
1085<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre> 1088<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
1086 [bool] = linda_h:set( key [, val [, ...]]) 1089 bool|lanes.cancel_error = linda_h:set( key [, val [, ...]])
1087 1090
1088 [val [, ...]] = linda_h:get( key [, count = 1]) 1091 [[val [, ...]]|lanes.cancel_error] = linda_h:get( key [, count = 1])
1089</pre></td></tr></table> 1092</pre></td></tr></table>
1090 1093
1091<p> 1094<p>
@@ -1099,9 +1102,9 @@
1099</p> 1102</p>
1100 1103
1101<p> 1104<p>
1102 <tt>set()</tt> signals the linda for write if a value is stored. 1105 <tt>set()</tt> signals the linda for write if a value is stored. If nothing special happens, <tt>set() </tt>returns nothing.
1103 <br/> 1106 <br/>
1104 (Since version 3.7.7) if the key was full but the new data count of the key after <tt>set()</tt> is below its limit, <tt>set()</tt> returns <tt>true</tt> and the linda is also signaled for read so that send()-blocked threads are awakened. 1107 Since version 3.7.7, if the key was full but the new data count of the key after <tt>set()</tt> is below its limit, <tt>set()</tt> returns <tt>true</tt> and the linda is also signaled for read so that <tt>send()</tt>-blocked threads are awakened.
1105</p> 1108</p>
1106 1109
1107<p> 1110<p>
@@ -1110,6 +1113,10 @@
1110 Also, <tt>get()</tt> can read several values at once. If the key contains no data, <tt>get()</tt> returns no value. This can be used to separate the case when reading stored <tt>nil</tt> values. 1113 Also, <tt>get()</tt> can read several values at once. If the key contains no data, <tt>get()</tt> returns no value. This can be used to separate the case when reading stored <tt>nil</tt> values.
1111</p> 1114</p>
1112 1115
1116<p>
1117 Since version 3.8.4, trying to send or receive data through a cancelled linda does nothing and returns <tt>lanes.cancel_error</tt>.
1118</p>
1119
1113<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre> 1120<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
1114 [val] = linda_h:count( [key[,...]]) 1121 [val] = linda_h:count( [key[,...]])
1115</pre></td></tr></table> 1122</pre></td></tr></table>
@@ -1134,6 +1141,19 @@
1134 Returns a table describing the full contents of a linda, or <tt>nil</tt> if the linda wasn't used yet. 1141 Returns a table describing the full contents of a linda, or <tt>nil</tt> if the linda wasn't used yet.
1135</p> 1142</p>
1136 1143
1144<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
1145 void = linda_h:cancel("read"|"write"|"both"|"none")
1146</pre></td></tr></table>
1147
1148<p>
1149 (Starting with version 3.8.4) Signals the linda so that lanes waiting for read, write, or both, wake up.
1150 All linda operations (including <tt>get()</tt> and <tt>set()</tt>) will return <tt>lanes.cancel_error</tt> as when the calling lane is <a href="#cancelling">soft-cancelled</a> as long as the linda is marked as cancelled.
1151 <br/>
1152 <tt>"none"</tt> reset the linda's cancel status, but doesn't signal it.
1153 <br/>
1154 If not void, the lane's cancel status overrides the linda's cancel status.
1155</p>
1156
1137<h3>Granularity of using Lindas</h3> 1157<h3>Granularity of using Lindas</h3>
1138 1158
1139<p> 1159<p>