aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorBenoit Germain <bnt.germain@gmail.com>2012-09-26 21:22:30 +0200
committerBenoit Germain <bnt.germain@gmail.com>2012-09-26 21:22:30 +0200
commitbba4ecea15320dfbf8edf35f7361de374d895ace (patch)
tree73bd0bfd29d2c4dbfe3a46681b0e3b2261352207 /docs
parent282f59ca02d1d1f304b9126b84a8b1427caf3172 (diff)
downloadlanes-bba4ecea15320dfbf8edf35f7361de374d895ace.tar.gz
lanes-bba4ecea15320dfbf8edf35f7361de374d895ace.tar.bz2
lanes-bba4ecea15320dfbf8edf35f7361de374d895ace.zip
version 3.4.0
* new method linda:dump() that outputs the full contents of a linda as a table, also linked to __towatch for Decoda support * linda:receive() API change! * instead of [val, key], linda:receive( timeout, key) returns [key, val] * instead of [val, [...]], linda:receive( timeout, linda.batched key) returns [key, val[, ...]] this is to unify the return values of regular and batched mode, and to be able to tell when batched mode is interrupted by a lane cancellation * fixed Lua 5.2 build to take into account the "loaders"->"searchers" name change in 'package' module. * a bit of html cleanup and added some infos in the documentation regarding the Lanes internals
Diffstat (limited to 'docs')
-rw-r--r--docs/index.html1930
1 files changed, 1052 insertions, 878 deletions
diff --git a/docs/index.html b/docs/index.html
index 932a712..bb64ba2 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -5,61 +5,74 @@
5 5
6<html> 6<html>
7<head> 7<head>
8 <meta name="description" content="Lua Lanes - multithreading in Lua" /> 8 <meta name="description" content="Lua Lanes - multithreading in Lua" />
9 <meta name="keywords" content="Lua, Library, Multithreading, Threads, Rocks" /> 9 <meta name="keywords" content="Lua, Library, Multithreading, Threads, Rocks" />
10 10
11 <title>Lua Lanes - multithreading in Lua</title> 11 <title>Lua Lanes - multithreading in Lua</title>
12</head> 12</head>
13 13
14<body> 14<body>
15<div class="header">
16<hr />
17
18<center>
19<table summary="Lua logo">
20 <tbody>
21 <tr>
22 <td align="center">
23 <a href="http://www.lua.org">
24 <img src="multi.png" alt="Lua" align="middle" border="0" height="120" width="128" />
25 <img src="multi.png" alt="Lua" align="middle" border="0" height="120" width="128" />
26 <img src="multi.png" alt="Lua" align="middle" border="0" height="120" width="128" />
27 <img src="multi.png" alt="Lua" align="middle" border="0" height="120" width="128" />
28 <img src="multi.png" alt="Lua" align="middle" border="0" height="120" width="128" />
29 </a></td>
30 </tr>
31 <tr>
32 <td align="center" valign="top"><h1>Lua Lanes - multithreading in Lua</h1>
33 </td>
34 </tr>
35 </tbody>
36</table>
37 15
38<p class="bar"> 16<div class="header">
39 <a href="#description">Description</a> &middot; 17 <hr/>
40 <a href="#systems">Supported systems</a> &middot; 18
41 <a href="#installing">Building and Installing</a> 19 <center>
42</p><p class="bar"> 20 <table summary="Lua logo"><tbody>
43 <a href="#creation">Creation</a> &middot; 21 <tr>
44 <a href="#status">Status</a> &middot; 22 <td align="center">
45 <a href="#results">Results and errors</a> 23 <a href="http://www.lua.org">
46</p><p class="bar"> 24 <img src="multi.png" alt="Lua" align="middle" border="0" height="120" width="128" />
47 <a href="#cancelling">Cancelling</a> &middot; 25 <img src="multi.png" alt="Lua" align="middle" border="0" height="120" width="128" />
48 <a href="#finalizers">Finalizers</a> &middot; 26 <img src="multi.png" alt="Lua" align="middle" border="0" height="120" width="128" />
49 <a href="#lindas">Lindas</a> &middot; 27 <img src="multi.png" alt="Lua" align="middle" border="0" height="120" width="128" />
50 <a href="#timers">Timers</a> &middot; 28 <img src="multi.png" alt="Lua" align="middle" border="0" height="120" width="128" />
51 <a href="#locks">Locks etc.</a> 29 </a>
52</p><p class="bar"> 30 </td>
53 <a href="#other">Other issues</a> &middot; 31 </tr>
54 <a href="#changes">Change log</a> 32 <tr>
55 <!-- ... --> 33 <td align="center" valign="top"><h1>Lua Lanes - multithreading in Lua</h1></td>
56 34 </tr>
57<p><br/><font size="-1"><i>Copyright &copy; 2007-12 Asko Kauppi, Benoit Germain. All rights reserved.</i> 35 </tbody></table>
58 <br>Lua Lanes is published under the same <A HREF="http://en.wikipedia.org/wiki/MIT_License">MIT license</A> as Lua 5.1 and 5.2. 36
59 </p><p>This document was revised on 10-Sep-12, and applies to version 3.3.0 37 <p class="bar">
60</font></p> 38 <a href="#description">Description</a> &middot;
61 39 <a href="#systems">Supported systems</a> &middot;
62</center> 40 <a href="#installing">Building and Installing</a>
41 </p>
42
43 <p class="bar">
44 <a href="#creation">Creation</a> &middot;
45 <a href="#status">Status</a> &middot;
46 <a href="#results">Results and errors</a>
47 </p>
48
49 <p class="bar">
50 <a href="#cancelling">Cancelling</a> &middot;
51 <a href="#finalizers">Finalizers</a> &middot;
52 <a href="#lindas">Lindas</a> &middot;
53 <a href="#timers">Timers</a> &middot;
54 <a href="#locks">Locks etc.</a>
55 </p>
56
57 <p class="bar">
58 <a href="#other">Other issues</a> &middot;
59 <a href="#changes">Change log</a>
60 </p>
61 <!-- ... -->
62
63 <font size="-1">
64 <p>
65 <br>
66 <i>Copyright &copy; 2007-12 Asko Kauppi, Benoit Germain. All rights reserved.</i>
67 <br>
68 Lua Lanes is published under the same <a href="http://en.wikipedia.org/wiki/MIT_License">MIT license</a> as Lua 5.1 and 5.2.
69 </p>
70
71 <p>
72 This document was revised on 25-Sep-12, and applies to version <tt>3.4.0</tt>.
73 </p>
74 </font>
75 </center>
63</div> 76</div>
64 77
65 78
@@ -67,50 +80,40 @@
67<hr/> 80<hr/>
68<h2 id="description">Description</h2> 81<h2 id="description">Description</h2>
69 82
70<p>Lua Lanes is a Lua extension library providing 83<p>
71 the possibility to run multiple Lua states in parallel. It is intended to 84 Lua Lanes is a Lua extension library providing the possibility to run multiple Lua states in parallel. It is intended to be used for optimizing performance on multicore CPU's and to study ways to make Lua programs naturally parallel to begin with.
72 be used for optimizing performance on multicore CPU's and to study ways to make Lua programs naturally parallel to begin with. 85</p>
73</p><p> 86<p>
74 Lanes is included into your software by the regular 87 Lanes is included into your software by the regular <tt>require "lanes"</tt> method. No C side programming is needed; all APIs are Lua side, and most existing extension modules should work seamlessly together with the multiple lanes.
75 <tt>require "lanes"</tt> method. No C side programming is needed; all APIs are Lua side, and most existing extension modules should 88</p>
76 work seamlessly together with the multiple lanes. 89<p>
77</p><p>
78 Starting with version 3.1.6, Lanes should build and run identically with either Lua 5.1 or Lua 5.2. 90 Starting with version 3.1.6, Lanes should build and run identically with either Lua 5.1 or Lua 5.2.
79</p><p> 91</p>
92<p>
80 See <A HREF="comparison.html">comparison</A> of Lua Lanes with other Lua multithreading solutions. 93 See <A HREF="comparison.html">comparison</A> of Lua Lanes with other Lua multithreading solutions.
81</p><p> 94</p>
82 <h3>Features:</h3> 95<p>
83 96 <h3>Features:</h3>
84 <ul> 97
85 <li>Lanes have separated data, by default. Shared data is possible with Linda objects. 98 <ul>
86 </li> 99 <li>Lanes have separated data, by default. Shared data is possible with Linda objects.</li>
87 <li>Communications is separate of threads, using Linda objects. 100 <li>Communications is separate of threads, using Linda objects.</li>
88 </li> 101 <li>Data passing uses fast inter-state copies (no serialization required).</li>
89 <li>Data passing uses fast inter-state copies (no serialization required)</li> 102 <li>"Deep userdata" concept, for sharing userdata over multiple lanes.</li>
90 </li> 103 <li>Millisecond level timers, integrated with the Linda system.</li>
91 <li>"Deep userdata" concept, for sharing userdata over multiple lanes 104 <li>Threads can be given priorities -2..+2 (default is 0).</li>
92 </li> 105 <li>Lanes are cancellable, with proper cleanup.</li>
93 <li>Millisecond level timers, integrated with the Linda system. 106 <li>No Lua-side application level locking - ever!</li>
94 </li> 107 </ul>
95 <li>Threads can be given priorities -2..+2 (default is 0). 108
96 </li> 109
97 <li>Lanes are cancellable, with proper cleanup. 110 <h3 id="limitations">Limitations:</h3>
98 </li> 111
99 <li>No application level locking - ever! 112 <ul>
100 </li> 113 <li>Coroutines are not passed between states.</li>
101 </ul> 114 <li>Sharing full userdata between states needs special C side preparations (-&gt; <A HREF="#deep_userdata">deep userdata</A>).</li>
102 115 <li>Network level parallelism not included.</li>
103 116 </ul>
104<h3>Limitations:</h3>
105
106 <ul><li>coroutines are not passed between states
107 </li>
108 <li>sharing full userdata between states needs special C side
109 preparations (-&gt; <A HREF="#deep_userdata">deep userdata</A>)
110 </li>
111 <li>network level parallelism not included
112 </li>
113 </ul>
114</p> 117</p>
115 118
116 119
@@ -118,23 +121,24 @@
118<hr/> 121<hr/>
119<h2 id="systems">Supported systems</h2> 122<h2 id="systems">Supported systems</h2>
120 123
121<p>Lua Lanes supports the following operating systems: 124<p>
125 Lua Lanes supports the following operating systems:
122 126
123 <ul> 127 <ul>
124 <li>Mac OS X PowerPC / Intel (10.4 and later)</li> 128 <li>Mac OS X PowerPC / Intel (10.4 and later)</li>
125 <li>Linux x86</li> 129 <li>Linux x86</li>
126 <li>Windows 2000/XP and later <font size="-1">(MinGW or Visual C++ 2005/2008)</font></li> 130 <li>Windows 2000/XP and later <font size="-1">(MinGW or Visual C++ 2005/2008)</font></li>
127<!-- 131<!--
128 Other OS'es here once people help test them. (and the tester's name) 132 Other OS'es here once people help test them. (and the tester's name)
129 133
130 Win64, BSD, Linux x64, Linux embedded, QNX, Solaris, ... 134 Win64, BSD, Linux x64, Linux embedded, QNX, Solaris, ...
131--> 135-->
132 </ul> 136 </ul>
133 137
134 <p>The underlying threading code can be compiled either towards Win32 API 138</p>
135 or <a TARGET="_blank" HREF="http://en.wikipedia.org/wiki/POSIX_Threads">Pthreads</a>. Unfortunately, thread prioritization under Pthreads is a JOKE, 139<p>
136 requiring OS specific tweaks and guessing undocumented behaviour. Other features should be portable to any modern platform. 140 The underlying threading code can be compiled either towards Win32 API or <a TARGET="_blank" HREF="http://en.wikipedia.org/wiki/POSIX_Threads">Pthreads</a>. Unfortunately, thread prioritization under Pthreads is a JOKE,
137 </p> 141 requiring OS specific tweaks and guessing undocumented behaviour. Other features should be portable to any modern platform.
138</p> 142</p>
139 143
140 144
@@ -142,258 +146,373 @@
142<hr/> 146<hr/>
143<h2 id="installing">Building and Installing</h2> 147<h2 id="installing">Building and Installing</h2>
144 148
145<p>Lua Lanes is built simply by <tt>make</tt> on the supported platforms 149<p>
146(<tt>make-vc</tt> for Visual C++). See <tt>README</tt> for system specific 150 Lua Lanes is built simply by <tt>make</tt> on the supported platforms (<tt>make-vc</tt> for Visual C++). See <tt>README</tt> for system specific details and limitations.
147details and limitations.
148</p> 151</p>
149 152
150<p>To install Lanes, all you need are the <tt>lanes.lua</tt> and <tt>lanes/core.so|dll</tt> 153<p>
151files to be reachable by Lua (see LUA_PATH, LUA_CPATH). 154 To install Lanes, all you need are the <tt>lanes.lua</tt> and <tt>lanes/core.so|dll</tt> files to be reachable by Lua (see LUA_PATH, LUA_CPATH).
152 155 Or use <A HREF="http://www.luarocks.org" TARGET="_blank">Lua Rocks</A> package management.
153Or use <A HREF="http://www.luarocks.org" TARGET="_blank">Lua Rocks</A> package management.
154</p> 156</p>
155 157
156<pre> 158<pre>
157 > luarocks search lanes 159 > luarocks search lanes
158 ... output listing Lua Lanes is there ... 160 ... output listing Lua Lanes is there ...
159 161
160 > luarocks install lanes 162 > luarocks install lanes
161 ... output ... 163 ... output ...
162</pre> 164</pre>
163 165
164 166
165<!-- launching +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 167<!-- launching +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
166<hr/> 168<hr/>
167 169
168 <h2 id="initialization">Initialization</h2> 170<h2 id="initialization">Initialization</h2>
169
170 <p>
171 The following sample shows how to initialize the Lanes module.
172 </p>
173
174 <table border="1" bgcolor="#FFFFE0" width="500">
175 <tr>
176 <td>
177 <pre>
178 local lanes = require "lanes".configure()
179 </pre>
180 </table>
181
182 <p>
183 Starting with version 3.0-beta, requiring the module follows Lua 5.2 rules:
184 the module is not available under the global name "lanes", but has to be accessed
185 through require's return value.
186 After lanes is required, it is necessary to call <tt>lanes.configure()</tt>, which is the
187 only function exposed by the module at this point. Calling <tt>configure()</tt> will
188 perform one-time initializations and make the rest of the API available.
189 At the same time, <tt>configure()</tt> itself will be replaced by another function that
190 raises an error if called again with differing arguments.
191 </p>
192
193 <p>
194 <table border="1" bgcolor="#E0E0FF" cellpadding="10">
195 <tr>
196 <td>
197 <code>
198 lanes.configure( [opt_tbl])
199 </code>
200 </table>
201 </p>
202 <p>
203 <tt>lanes.configure</tt> accepts an optional options table as sole argument.
204 <table>
205 <tr valign=top><td width=40></td><td>
206 <code>.nb_keepers</code> <br/><nobr>N</nobr></td><td width=40></td>
207 <td>
208 Controls the number of keeper states used internally by lindas to transfer data between lanes. (see below). Default is <tt>1</tt>.
209 </td></tr>
210
211 <tr valign=top><td/><td>
212 <code>.with_timers</code> <br/>nil/false/anything</td><td/>
213 <td>
214 If equal to <tt>false</tt>, Lanes doesn't start the timer service,
215 and the associated API will be absent from the interface (see below).
216 Any other value (including <tt>nil</tt>), starts the timer service. Default is <tt>true</tt>.
217 </td></tr>
218
219 <tr valign="top">
220 <td/>
221 <td>
222 <code>.on_create_state</code> <br/>C function/nil
223 </td><td/>
224 <td>
225 If provided, will be called in every created Lua state (keepers and lanes) right after it is created, and *before* any library is loaded.
226 That way, all C functions it loads in the state can be added to the function lookup database. Default is <tt>nil</tt>.
227 </td>
228 </tr>
229
230 <tr valign=top><td width=40></td><td>
231 <code>.shutdown_timeout</code> <br/><nobr>N</nobr></td><td width=40></td>
232 <td>
233 (Since v3.3.0) 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>.
234 </td></tr>
235 </table>
236<h2 id="creation">Creation</h2>
237 171
238<p>The following sample shows preparing a function for parallel calling, and 172<p>
239calling it with varying arguments. Each of the two results is calculated in 173 The following sample shows how to initialize the Lanes module.
240a separate OS thread, parallel to the calling one. Reading the results
241joins the threads, waiting for any results not already there.
242</p> 174</p>
243 175
244<table border=1 bgcolor="#FFFFE0" width=500><tr><td> 176<table border="1" bgcolor="#FFFFE0" cellpadding="10" style="width:50%">
245<pre> 177 <tr>
246 local lanes = require "lanes" 178 <td>
247 lanes.configure() 179 <pre> local lanes = require "lanes".configure()</pre>
180 </td>
181 </tr>
182</table>
248 183
249 f= lanes.gen( function(n) return 2*n end ) 184<p>
250 a= f(1) 185 Starting with version 3.0-beta, requiring the module follows Lua 5.2 rules: the module is not available under the global name "lanes", but has to be accessed through require's return value.
251 b= f(2) 186</p>
187<p>
188 After lanes is required, it is necessary to call <tt>lanes.configure()</tt>, which is the only function exposed by the module at this point. Calling <tt>configure()</tt> will perform one-time initializations and make the rest of the API available.
189</p>
190<p>
191 At the same time, <tt>configure()</tt> itself will be replaced by another function that raises an error if called again with differing arguments.
192</p>
252 193
253 print( a[1], b[1] ) -- 2 4 194<p>
254</pre> 195 <table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%">
255</table> 196 <tr>
197 <td>
198 <pre> lanes.configure( [opt_tbl])</pre>
199 </td>
200 </tr>
201 </table>
202</p>
256 203
257<p> 204<p>
258<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td> 205 <tt>lanes.configure</tt> accepts an optional options table as sole argument.
259 <code>func= lanes.gen( [libs_str | opt_tbl [, ...],] lane_func ) 206 <table border="1" cellpadding="10" style="width:100%">
260 <br/><br/> 207 <tr>
261 lane_h= func( ... )</code> 208 <th style="width:15%">name</th>
209 <th style="width:15%">value</th>
210 <th style="width:70%">definition</th>
211 </tr>
212 <tr valign=top>
213 <td>
214 <code>.nb_keepers</code>
215 </td>
216 <td>integer >= 1</td>
217 <td>
218 Controls the number of keeper states used internally by lindas to transfer data between lanes. (see <a href="#lindas">below</a>). Default is <tt>1</tt>.
219 </td>
220 </tr>
221
222 <tr valign=top>
223 <td>
224 <code>.with_timers</code>
225 </td>
226 <td>
227 <tt>nil</tt>/<tt>false</tt>/anything
228 </td>
229 <td>
230 If equal to <tt>false</tt>, Lanes doesn't start the timer service, and the associated API will be absent from the interface (see below).
231 Any other non-<tt>nil</tt> value starts the timer service. Default is <tt>true</tt>.
232 </td>
233 </tr>
234
235 <tr valign=top>
236 <td>
237 <code>.on_create_state</code>
238 </td>
239 <td>
240 C function/<tt>nil</tt>
241 </td>
242 <td>
243 If provided, will be called in every created Lua state (keepers and lanes) right after it is created, and *before* any library is loaded. That way, all C functions it loads in the state can be added to the function lookup database. Default is <tt>nil</tt>.
244 </td>
245 </tr>
246
247 <tr valign=top>
248 <td>
249 <code>.shutdown_timeout</code> <br/>
250 </td>
251 <td>
252 number >= 0
253 </td>
254 <td>
255 (Since v3.3.0) 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>.
256 </td>
257 </tr>
258 </table>
259</p>
260
261<hr/>
262<h2 id="creation">Creation</h2>
263
264<p>
265 The following sample shows preparing a function for parallel calling, and calling it with varying arguments. Each of the two results is calculated in a separate OS thread, parallel to the calling one. Reading the results joins the threads, waiting for any results not already there.
266</p>
267
268<table border=1 bgcolor="#FFFFE0" cellpadding="10" style="width:50%">
269 <tr>
270 <td>
271 <pre> local lanes = require "lanes".configure()</pre>
272 <br/>
273 <pre> f = lanes.gen( function( n) return 2 * n end)</pre>
274 <pre> a = f( 1)</pre>
275 <pre> b = f( 2)</pre>
276 <br/>
277 <pre> print( a[1], b[1] ) -- 2 4</pre>
278 </td>
279 </tr>
262</table> 280</table>
281<br>
282<table border=1 bgcolor="#E0E0FF" cellpadding="10" style="width:50%">
283 <tr>
284 <td>
285 <pre> func = lanes.gen( [libs_str | opt_tbl [, ...],] lane_func)</pre>
286 <pre> lane_h = func( ...)</pre>
287 </td>
288 </tr>
289</table>
290
291<p>
292 The function returned by <tt>lanes.gen()</tt> is a "generator" for launching any number of lanes. They will share code, options, initial globals, but the particular arguments may vary. Only calling the generator function actually launches a lane, and provides a handle for controlling it.
293 <br/>
294 Alternatively, <tt>lane_func</tt> may be a string, in which case it will be compiled in the lane. This was to be able to launch lanes with older versions of LuaJIT, which didn't not support <tt>lua_dump</tt>, used internally to transfer functions to the lane.
263</p> 295</p>
296
264<p> 297<p>
265 The function returned by <tt>lanes.gen()</tt> is a "generator" for 298 Lanes automatically copies upvalues over to the new lanes, so you need not wrap all the required elements into one 'wrapper' function. If <tt>lane_func</tt> uses some local values, or local functions, they will be there also in the new lanes.
266 launching any number of lanes. They will share code, options, initial globals,
267 but the particular arguments may vary. Only calling the generator function
268 actually launches a lane, and provides a handle for controlling it.
269 Alternatively, <tt>lane_func</tt> may be a string, in which case it will be compiled
270 in the lane. This was to be able to launch lanes with older versions of LuaJIT,
271 which didn't not support lua_dump, used internally to transfer functions to the lane.
272<!--
273</p> 299</p>
274<p>This prepares <tt>lane_func</tt> to be called in parallel. It does not yet start 300
275anything, but merely returns a <i>generator function</i> that can be called 301<p>
276any number of times, with varying parameters. Each call will spawn a new lane. 302 <code>libs_str</code> defines the standard libraries made available to the new Lua state:
277--> 303 <table style="width:100%">
278</p><p> 304 <tr>
279Lanes automatically copies upvalues over to the new lanes, so you 305 <td style="width:5%"></td>
280need not wrap all the required elements into one 'wrapper' function. If 306 <td>(nothing)</td>
281<tt>lane_func</tt> uses some local values, or local functions, they will be there 307 <td style="width:5%"></td>
282also in the new lanes. 308 <td>no standard libraries (default)</td>
283</p><p> 309 </tr>
284 <code>libs_str</code> defines the standard libraries made available to the 310 <tr>
285 new Lua state: 311 <td/>
286 <table> 312 <td><tt>"base"</tt> or <tt>""</tt>
287 <tr><td width=40></td><td>(nothing)</td><td width=40></td><td>no standard libraries (default)</td></tr> 313 </td>
288 <tr><td/> 314 <td/>
289 <td><tt>"base"</tt> or <tt>""</tt></td><td/> 315 <td>
290 <td>root level names, <tt>print</tt>, <tt>assert</tt>, <tt>unpack</tt> etc.</td> 316 root level names, <tt>print</tt>, <tt>assert</tt>, <tt>unpack</tt> etc.
291 </tr> 317 </td>
292 <tr><td/><td><tt>"coroutine"</tt></td><td/><td><tt>coroutine.*</tt> namespace <font size="-1">(part of base in Lua 5.1 and 5.2)</font></td></tr> 318 </tr>
293 <tr><td/><td><tt>"debug"</tt></td><td/><td><tt>debug.*</tt> namespace</td></tr> 319 <tr>
294 <tr><td/><td><tt>"io"</tt></td><td/><td><tt>io.*</tt> namespace</td></tr> 320 <td/>
295 <tr><td/><td><tt>"math"</tt></td><td/><td><tt>math.*</tt> namespace</td></tr> 321 <td>
296 <tr><td/><td><tt>"os"</tt></td><td/><td><tt>os.*</tt> namespace</td></tr> 322 <tt>"coroutine"</tt>
297 <tr><td/><td><tt>"package"</tt></td><td/><td><tt>package.*</tt> namespace and <tt>require</tt></td></tr> 323 </td>
298 <tr><td/><td><tt>"string"</tt></td><td/><td><tt>string.*</tt> namespace</td></tr> 324 <td/>
299 <tr><td/><td><tt>"table"</tt></td><td/><td><tt>table.*</tt> namespace</td></tr> 325 <td>
300 <br/> 326 <tt>coroutine.*</tt> namespace (part of base in Lua 5.1 and 5.2)
301 <tr><td/><td><tt>"*"</tt></td><td/><td>all standard libraries (including those specific to LuaJIT and not listed above)</td></tr> 327 </td>
302 </table> 328 </tr>
303 329 <tr>
304</p><p> 330 <td/>
305 Initializing the standard libs takes a bit of time at each lane invocation. 331 <td>
306 This is the main reason why "no libraries" is the default. 332 <tt>"debug"</tt>
307</p><p> 333 </td>
308 334 <td/>
309 <code>opt_tbl</code> is a collection of named options to control the way 335 <td>
310 lanes are run: 336 <tt>debug.*</tt> namespace
311</p><p> 337 </td>
312 <table> 338 </tr>
313 <tr valign=top><td width=40></td><td> 339 <tr>
314 <code>.cancelstep</code> <br/><nobr>N / true</nobr></td> 340 <td/>
315 <td width=40></td><td> 341 <td>
316 By default, lanes are only cancellable when they <u>enter</u> a pending 342 <tt>"io"</tt>
317 <tt>:receive()</tt> or <tt>:send()</tt> call. 343 </td>
318 With this option, one can set cancellation check to occur every <tt>N</tt> 344 <td/>
319 Lua statements. The value <tt>true</tt> uses a default value (100). 345 <td>
320 It is also possible to manually test for cancel requests with <tt>cancel_test()</tt>. 346 <tt>io.*</tt> namespace
321 </td></tr> 347 </td>
322 348 </tr>
323 <tr valign=top><td/><td> 349 <tr>
324 <code>.globals</code> <br/>globals_tbl</td><td/> 350 <td/>
325 <td> 351 <td>
326 Sets the globals table for the launched threads. This can be used for giving 352 <tt>"math"</tt>
327 them constants. The key/value pairs of <tt>globals_tbl</tt> are transfered in the lane globals after the libraries have been loaded and the modules required. 353 </td>
328 <br> 354 <td/>
329 The global values of different lanes are in no manner connected; 355 <td>
330 modifying one will only affect the particular lane. 356 <tt>math.*</tt> namespace
331 </td></tr> 357 </td>
332 358 </tr>
333 <tr valign="top"> 359 <tr>
334 <td/> 360 <td/>
335 <td> 361 <td>
336 <code>.required</code> <br/>modules_tbl 362 <tt>"os"</tt>
337 </td><td/> 363 </td>
338 <td> 364 <td/>
339 Lists modules that have to be required in order to be able to trasnfer 365 <td>
340 functions they exposed. Starting with Lanes 3.0-beta, non-Lua functions are 366 <tt>os.*</tt> namespace
341 no longer copied by recreating a C closure from a C pointer, but are searched 367 </td>
342 in lookup tables. These tables are built from the modules listed here. <tt>required</tt> 368 </tr>
343 must be a list of strings, each one being the name of a module to be required. 369 <tr>
344 </td> 370 <td/>
345 </tr> 371 <td>
346 372 <tt>"package"</tt>
347 <tr valign=top><td width=40><td> 373 </td>
348 <code>.priority</code> <br/><nobr>-2..+2</nobr></td><td/> 374 <td/>
349 <td>The priority of lanes generated. -2 is lowest, +2 is highest. 375 <td>
350 <br> 376 <tt>package.*</tt> namespace and <tt>require</tt>
351 Implementation and dependability of priorities varies 377 </td>
352 by platform. Especially Linux kernel 2.6 is not supporting priorities in user mode. 378 </tr>
353 </td></tr> 379 <tr>
354 380 <td/>
355 <tr valign="top"> 381 <td>
356 <td width="40"> 382 <tt>"string"</tt>
357 <td> 383 </td>
358 <code>.package</code><br/> 384 <td/>
359 </td> 385 <td>
360 <td><td/> 386 <tt>string.*</tt> namespace
361 <code>package</code> contents overrides, if needed. 387 </td>
362 Specifying it when <code>libs_str</code> doesn't cause the <code>package</code> library to be loaded will generate an error. 388 </tr>
363 If not specified, the created lane will receive the current values of <tt>package</tt>. Only <tt>path</tt>, <tt>cpath</tt>, <tt>preload</tt> and <tt>loaders</tt> are transfered. 389 <tr>
364 <br> 390 <td/>
365 </td> 391 <td>
366 </tr> 392 <tt>"table"</tt>
367 </table> 393 </td>
368 <p>Each lane also gets a function <tt>set_debug_threadname()</tt> that it can use anytime to do as the name says. 394 <td/>
369Supported debuggers are Microsoft Visual Studio (for the C side) and Decoda (for the Lua side). 395 <td>
370</p> 396 <tt>table.*</tt> namespace
371 <p> 397 </td>
398 </tr>
399 <tr>
400 <td/>
401 <td>
402 <tt>"*"</tt>
403 </td>
404 <td/>
405 <td>
406 all standard libraries (including those specific to LuaJIT and not listed above)
407 </td>
408 </tr>
409 </table>
410</p>
411
412<p>
413 Initializing the standard libs takes a bit of time at each lane invocation. This is the main reason why "no libraries" is the default.
414</p>
415
416<p>
417 <code>opt_tbl</code> is a collection of named options to control the way lanes are run:
418</p>
419
420<p>
421
422 <table border="1" cellpadding="10" style="width:100%">
423 <tr>
424 <th style="width:15%">name</th>
425 <th style="width:15%">value</th>
426 <th style="width:70%">definition</th>
427 </tr>
428 <tr valign=top>
429 <td>
430 <code>.cancelstep</code>
431 </td>
432 <td>integer >= 1/<tt>true</tt></td>
433 <td>
434 By default, lanes are only cancellable when they <u>enter</u> a pending <tt>:receive()</tt> or <tt>:send()</tt> call. With this option, one can set cancellation check to occur every <tt>N</tt> Lua statements. The value <tt>true</tt> uses a default value (100).
435 It is also possible to manually test for cancel requests with <tt>cancel_test()</tt>.
436 </td>
437 </tr>
438 <tr valign=top>
439 <td>
440 <code>.globals</code>
441 </td>
442 <td>table</td>
443 <td>
444 Sets the globals table for the launched threads. This can be used for giving them constants. The key/value pairs of <tt>table</tt> are transfered in the lane globals after the libraries have been loaded and the modules required.
445 <br/>
446 The global values of different lanes are in no manner connected; modifying one will only affect the particular lane.
447 </td>
448 </tr>
449 <tr id=".required" valign=top>
450 <td>
451 <code>.required</code>
452 </td>
453 <td>table</td>
454 <td>
455 Lists modules that have to be required in order to be able to transfer functions they exposed. Starting with Lanes 3.0-beta, non-Lua functions are no longer copied by recreating a C closure from a C pointer, but are <a href="#function_notes">searched in lookup tables</a>.
456 These tables are built from the modules listed here. <tt>required</tt> must be a list of strings, each one being the name of a module to be required. Each module is required with <tt>require()</tt> before the lanes function is invoked.
457 So, from the required module's point of view, requiring it manually from inside the lane body or having it required this way doesn't change anything. From the lane body's point of view, the only difference is that a module not creating a global won't be accessible.
458 Therefore, a lane body will also have to require a module manually, but this won't do anything more (see Lua's <tt>require</tt> documentation).
459 </td>
460 </tr>
461 <tr valign=top>
462 <td>
463 <code>.priority</code>
464 </td>
465 <td> integer -2..+2</td>
466 <td>
467 The priority of lanes generated. -2 is lowest, +2 is highest.
468 <br>
469 Implementation and dependability of priorities varies by platform. Especially Linux kernel 2.6 is not supporting priorities in user mode.
470 </td>
471 </tr>
472 <tr valign=top>
473 <td>
474 <code>.package</code>
475 </td>
476 <td> table</td>
477 <td>
478 Specifying it when <code>libs_str</code> doesn't cause the <code>package</code> library to be loaded will generate an error.
479 <br>
480 If not specified, the created lane will receive the current values of <tt>package</tt>. Only <tt>path</tt>, <tt>cpath</tt>, <tt>preload</tt> and <tt>loaders</tt> (Lua 5.1)/<tt>searchers</tt> (Lua 5.2) are transfered.
481 </td>
482 </tr>
483 </table>
484
485<p>
486 Each lane also gets a function <tt>set_debug_threadname()</tt> that it can use anytime to do as the name says. Supported debuggers are Microsoft Visual Studio (for the C side) and Decoda (for the Lua side).
487</p>
488
489<p>
372 If a lane body pulls a C function imported by a module required before Lanes itself (thus not through a hooked <tt>require</tt>), the lane generator creation will raise an error. 490 If a lane body pulls a C function imported by a module required before Lanes itself (thus not through a hooked <tt>require</tt>), the lane generator creation will raise an error.
373 The function name it shows is a path where it was found by scanning _G. As a utility, the name guessing functionality is exposed as such: 491 The function name it shows is a path where it was found by scanning _G. As a utility, the name guessing functionality is exposed as such:
374<table border="1" bgcolor="#E0E0FF" cellpadding="10"> 492
375 <tr> 493 <table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%">
376 <td> 494 <tr>
377 <code> 495 <td>
378 "type", "name" = lanes.nameof( o) 496 <pre> "type", "name" = lanes.nameof( o)</pre>
379 </code> 497 </td>
380 </table> 498 </tr>
499 </table>
381</p> 500</p>
382 501
383<h3>Free running lanes</h3> 502<h3>Free running lanes</h3>
384 503
385<p> 504<p>
386The lane handles are allowed to be 'let loose'; in other words you may execute 505 The lane handles are allowed to be 'let loose'; in other words you may execute a lane simply by:
387a lane simply by:
388 506
389<pre> 507 <table border="1" bgcolor="#FFFFE0" cellpadding="10" style="width:50%">
390 lanes.gen( function() ... end ) () 508 <tr>
391</pre> 509 <td>
510 <pre> lanes.gen( function( params) ... end ) ( ...)</pre>
511 </td>
512 </tr>
513 </table>
392 514
393Normally, this kind of lanes will be in an eternal loop handling messages. 515 Normally, this kind of lanes will be in an eternal loop handling messages. Since the lane handle is gone, there is no way to control such a lane from the outside, nor read its potential return values. Then again, such a lane does not even normally return.
394Since the lane handle is gone,
395there is no way to control such a lane from the outside, nor read its potential
396return values. Then again, such a lane does not even normally return.
397</p> 516</p>
398 517
399 518
@@ -401,26 +520,95 @@ return values. Then again, such a lane does not even normally return.
401<hr/> 520<hr/>
402<h2 id="status">Status</h2> 521<h2 id="status">Status</h2>
403 522
404<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td> 523 <table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%">
405 <code>str= lane_h.status</code> 524 <tr>
406</table> 525 <td>
526 <pre> str = lane_h.status</pre>
527 </td>
528 </tr>
529 </table>
407 530
408<p>The current execution state of a lane can be read via its <tt>status</tt> 531<p>
409member, providing one of these values: <sup>(<a href="#2">2</a></sup> 532 The current execution state of a lane can be read via its <tt>status</tt> member, providing one of these values: <sup>(<a href="#2">2</a>)</sup>
533
534 <table style="width:100%">
535 <tr>
536 <td style="width:5%"></td>
537 <td>
538 <tt>"pending"</tt>
539 </td>
540 <td style="width:5%"></td>
541 <td>
542 Not started yet. Shouldn't stay very long in that state.
543 </td>
544 </tr>
545 <tr>
546 <td/>
547 <td>
548 <tt>
549 "running"
550 </tt>
551 </td>
552 <td/>
553 <td>
554 running, not suspended on a Linda call.
555 </td>
556 </tr>
557 <tr>
558 <td/>
559 <td>
560 <tt>"waiting"</tt>
561 </td>
562 <td/>
563 <td>
564 waiting at a Linda <tt>:receive()</tt> or <tt>:send()</tt>
565 </td>
566 </tr>
567 <tr>
568 <td/>
569 <td>
570 <tt>"done"</tt>
571 </td>
572 <td/>
573 <td>
574 finished executing (results are ready)
575 </td>
576 </tr>
577 <tr>
578 <td/>
579 <td>
580 <tt>"error"</tt>
581 </td>
582 <td/>
583 <td>
584 met an error (reading results will propagate it)
585 </td>
586 </tr>
587 <tr>
588 <td/>
589 <td>
590 <tt>"cancelled"</tt>
591 </td>
592 <td/>
593 <td>
594 received cancellation and finished itself.
595 </td>
596 </tr>
597 <tr>
598 <td/>
599 <td>
600 <tt>"killed"</tt>
601 </td>
602 <td/>
603 <td>
604 was forcefully killed by <tt>lane_h:cancel()</tt> (since v3.3.0)
605 </td>
606 </tr>
607 </table>
608</p>
410 609
411 <table> 610<p>
412 <tr><td width=40><td><tt>"pending"</tt></td><td>not started, yet</td></tr> 611 This is similar to <tt>coroutine.status</tt>, which has: <tt>"running"</tt> / <tt>"suspended"</tt> / <tt>"normal"</tt> / <tt>"dead"</tt>. Not using the exact same names is intentional.
413 <tr><td/><td><tt>"running"</tt></td><td>running</td></tr>
414 <tr><td/><td><tt>"waiting"</tt></td><td>waiting at a Linda <tt>:receive()</tt> or <tt>:send()</tt></td></tr>
415 <tr><td/><td><tt>"done"</tt></td><td>finished executing (results are ready)</td></tr>
416 <tr><td/><td><tt>"error"</tt></td><td>met an error (reading results will propagate it)</td></tr>
417 <tr><td/><td><tt>"cancelled"</tt></td><td>received cancellation and finished itself</td></tr>
418 <tr><td/><td><tt>"killed"</tt></td><td>was forcefully killed by <tt>lane_h:cancel()</tt> (since v3.3.0)</td></tr>
419 </table>
420</p><p>
421 This is similar to <tt>coroutine.status</tt>, which has: <tt>"running"</tt> /
422 <tt>"suspended"</tt> / <tt>"normal"</tt> / <tt>"dead"</tt>. Not using the
423 exact same names is intentional.
424</p> 612</p>
425 613
426 614
@@ -428,101 +616,110 @@ member, providing one of these values: <sup>(<a href="#2">2</a></sup>
428<hr/> 616<hr/>
429<h2 id="results">Results and errors</h2> 617<h2 id="results">Results and errors</h2>
430 618
431<p>A lane can be waited upon by simply reading its results. This can be done 619<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
432in two ways. 620 set_error_reporting( "basic"|"extended")
433</p><p> 621</pre></td></tr></table>
434 622
435<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td>
436 <code>[val]= lane_h[1]</code>
437</table>
438<p> 623<p>
439Makes sure lane has finished, and gives its first (maybe only) return value. 624 Sets the error reporting mode. "basic" is selected by default.
440Other return values will be available in other <tt>lane_h</tt> indices.
441</p><p>
442If the lane ended in an error, it is propagated to master state at this place.
443</p> 625</p>
444 626
445<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td>
446 <code>[...]|[nil,err,stack_tbl]= lane_h:join( [timeout_secs] )</code>
447</table>
448<p> 627<p>
449Waits until the lane finishes, or <tt>timeout</tt> seconds have passed. 628 A lane can be waited upon by simply reading its results. This can be done in two ways.
450Returns <tt>nil</tt> on timeout, <tt>nil,err,stack_tbl</tt> if the lane hit an error, 629</p>
451<tt>nil, "killed"</tt> if forcefully killed (starting with v3.3.0), or the return values of the lane.
452Unlike in reading the results in table fashion, errors are not propagated.
453 630
454</p><p> 631<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
632 [val]= lane_h[1]
633</pre></td></tr></table>
455 634
456<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td> 635<p>
457 <code>set_error_reporting("basic"|"extended")</code> 636 Makes sure lane has finished, and gives its first (maybe only) return value. Other return values will be available in other <tt>lane_h</tt> indices.
458</table> 637 <br>
459</p><p> 638 If the lane ended in an error, it is propagated to master state at this place.
460 Sets the error reporting mode. "basic" is selected by default. 639</p>
461</p><p>
462 <tt>stack_tbl</tt> is a table describing where the error was thrown.<br/>
463 In extended mode, <tt>stack_tbl</tt> is an array of tables containing info gathered with <tt>lua_getinfo()</tt> (<tt>"source"</tt>,<tt>"currentline"</tt>,<tt>"name"</tt>,<tt>"namewhat"</tt>,<tt>"what"</tt>).<br/>
464In "basic mode", <tt>stack_tbl</tt> is an array of "&lt;filename&gt;:&lt;line&gt;" strings. Use <tt>table.concat()</tt> to format it to your liking (or just ignore it).
465
466</p><p>
467If you use <tt>:join</tt>, make sure your lane main function returns
468a non-nil value so you can tell timeout and error cases apart from succesful
469return (using the <tt>.status</tt> property may be risky, since it might change
470between a timed out join and the moment you read it).
471</p><p>
472
473<table border=1 bgcolor="#FFFFE0" width=500><tr><td>
474<pre>
475 require "lanes"
476 640
477 f= lanes.gen( function() error "!!!" end ) 641<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
478 a= f(1) 642 [...]|[nil,err,stack_tbl]= lane_h:join( [timeout_secs] )
643</pre></td></tr></table>
479 644
480 --print( a[1] ) -- propagates error 645<p>
646 Waits until the lane finishes, or <tt>timeout</tt> seconds have passed. Returns <tt>nil</tt> on timeout, <tt>nil,err,stack_tbl</tt> if the lane hit an error, <tt>nil, "killed"</tt> if forcefully killed (starting with v3.3.0), or the return values of the lane.
647 Unlike in reading the results in table fashion, errors are not propagated.
648</p>
481 649
482 v,err= a:join() -- no propagation 650<p>
483 if v==nil then 651 <tt>stack_tbl</tt> is a table describing where the error was thrown.
484 error( "'a' faced error"..tostring(err) ) -- manual propagation 652 <br>
485 end 653 In <tt>"extended"</tt> mode, <tt>stack_tbl</tt> is an array of tables containing info gathered with <tt>lua_getinfo()</tt> (<tt>"source"</tt>,<tt>"currentline"</tt>,<tt>"name"</tt>,<tt>"namewhat"</tt>,<tt>"what"</tt>).
486</pre> 654 <br>
487</table> 655 In <tt>"basic mode"</tt>, <tt>stack_tbl</tt> is an array of "&lt;filename&gt;:&lt;line&gt;" strings. Use <tt>table.concat()</tt> to format it to your liking (or just ignore it).
656</p>
657
658<p>
659 If you use <tt>:join</tt>, make sure your lane main function returns a non-nil value so you can tell timeout and error cases apart from succesful return (using the <tt>.status</tt> property may be risky, since it might change between a timed out join and the moment you read it).
660</p>
661
662<p>
663
664<table border=1 bgcolor="#FFFFE0" cellpadding="10" style="width:50%"><tr><td><pre>
665 require "lanes".configure()
666
667 f = lanes.gen( function() error "!!!" end)
668 a = f( 1)
669
670 --print( a[1]) -- propagates error
671
672 v, err = a:join() -- no propagation
673 if v == nil then
674 error( "'a' faced error"..tostring(err)) -- manual propagation
675 end
676</pre></td></tr></table>
488 677
489<p> 678<p>
490If you want to wait for multiple lanes to finish (any of a set of lanes), use 679 If you want to wait for multiple lanes to finish (any of a set of lanes), use a <a href="#lindas">Linda</a> object. Give each lane a specific id, and send that id over a Linda once that thread is done (as the last thing you do).
491a <a href="#lindas">Linda</a> object. Give each lane a specific id, and send
492that id over a Linda once that thread is done (as the last thing you do).
493</p> 680</p>
494 681
682<table border=1 bgcolor="#FFFFE0" cellpadding="10" style="width:50%"><tr><td><pre>
683 require "lanes".configure()
684
685 local sync_linda = lanes.linda()
686 f = lanes.gen( function() dostuff() sync_linda:send( "done", true) end)
687 a = f()
688 b = f()
689 c = f()
690
691 sync_linda:receive( nil, sync_linda.batched, "done", 3) -- wait for 3 lanes to write something in "done" slot of sync_linda
692</pre></td></tr></table>
495 693
496<!-- cancelling +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 694<!-- cancelling +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
497<hr/> 695<hr/>
498<h2 id="cancelling">Cancelling</h2> 696<h2 id="cancelling">Cancelling</h2>
499 697
500<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td> 698<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
501 <code>bool[,reason]= lane_h:cancel( [timeout_secs=0.0,] [force_kill_bool=false] )</code> 699 bool[,reason] = lane_h:cancel( [timeout_secs=0.0,] [force_kill_bool = false] )
502 <br/> 700</pre></td></tr></table>
503 <br/> 701
504 <code> 702<p>
505 bool= cancel_test() 703 <tt>cancel()</tt>sends a cancellation request to the lane. If <tt>timeout_secs</tt> is non-zero, waits for the request to be processed, or a timeout to occur.
506 </code> 704 Returns <tt>true</tt> if the lane was already done (in <tt>"done"</tt>, <tt>"error"</tt> or <tt>"cancelled"</tt> status) or if the cancellation was fruitful within timeout period.
507</table> 705</p>
508 706
509<p><tt>cancel()</tt>sends a cancellation request to the lane. If <tt>timeout_secs</tt> is non-zero, waits 707<p>
510for the request to be processed, or a timeout to occur. 708 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, and should generally be the last resort.
511Returns <tt>true</tt> if the lane was already done (in <tt>"done"</tt>, <tt>"error"</tt> or <tt>"cancelled"</tt> status)
512or if the cancellation was fruitful within timeout period.
513</p><p>
514If the lane is still running and <tt>force_kill</tt> is <tt>true</tt>, the
515OS thread running the lane is forcefully killed. This means no GC, and should
516generally be the last resort.
517</p> 709</p>
710
518<p> 711<p>
519Starting with v3.3.0, if <tt>cancel()</tt> returns false, it also returns either <tt>"timeout"</tt> or <tt>"killed"</tt> as second return value. 712 Starting with v3.3.0, if <tt>cancel()</tt> returns false, it also returns either <tt>"timeout"</tt> or <tt>"killed"</tt> as second return value.
520</p> 713</p>
521<p>Cancellation is tested <u>before</u> going to sleep in <tt>receive()</tt> or <tt>send()</tt> calls 714
522and after executing <tt>cancelstep</tt> Lua statements. Starting with version 3.0-beta, a pending <tt>receive()</tt> 715<p>
523or <tt>send()</tt> call is awakened. This means the execution of the lane will resume although the operation has 716 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. Starting with version 3.0-beta, a pending <tt>receive()</tt>or <tt>send()</tt> call is awakened.
524not completed, to give the lane a chance to detect cancellation. The code should be able to handle this situation appropriately if required. 717 <br>
525It is also possible to manually test for cancel requests with <tt>cancel_test()</tt>. 718 This means the execution of the lane will resume although the operation has not completed, to give the lane a chance to detect cancellation (even in the case the code waits on a linda with infinite timeout).
719 <br>
720 The code should be able to handle this situation appropriately if required (in other words, it should gracefully handle the fact that it didn't receive the expected values).
721 <br>
722 It is also possible to manually test for cancel requests with <tt>cancel_test()</tt>.
526</p> 723</p>
527 724
528 725
@@ -530,24 +727,24 @@ It is also possible to manually test for cancel requests with <tt>cancel_test()<
530<hr/> 727<hr/>
531<h2 id="finalizers">Finalizers</h2> 728<h2 id="finalizers">Finalizers</h2>
532 729
533<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td> 730<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
534 <code>set_finalizer( finalizer_func )</code> 731 set_finalizer( finalizer_func)
535 <br/><br/> 732
536 <code>void= finalizer_func( [err, stack_tbl] )</code> 733 void = finalizer_func( [err, stack_tbl])
537</table> 734</pre></td></tr></table>
538 735
539<p>The <tt>error</tt> call is used for throwing exceptions in Lua. What Lua 736<p>
540does not offer, however, is scoped <a href="http://en.wikipedia.org/wiki/Finalizer">finalizers</a> 737 The <tt>error</tt> call is used for throwing exceptions in Lua. What Lua does not offer, however, is scoped <a href="http://en.wikipedia.org/wiki/Finalizer">finalizers</a>
541that would get called when a certain block of instructions gets exited, whether 738 that would get called when a certain block of instructions gets exited, whether through peaceful return or abrupt <tt>error</tt>.
542through peaceful return or abrupt <tt>error</tt>.
543</p> 739</p>
544<p>Since 2.0.3, Lanes prepares a function <tt>set_finalizer</tt> for doing this. 740
545Any functions given to it will be called in the lane Lua state, just prior to 741<p>
546closing it. They are not called in any particular order. 742 Since 2.0.3, Lanes registers a function <tt>set_finalizer</tt> in the lane's Lua state for doing this.
743 Any functions given to it will be called in the lane Lua state, just prior to closing it. It is possible to set more than one finalizer. They are not called in any particular order.
547</p> 744</p>
548<p>An error in a finalizer itself overrides the state of the regular chunk 745
549(in practise, it would be highly preferable <i>not</i> to have errors in finalizers). 746<p>
550If one finalizer errors, the others may not get called. 747 An error in a finalizer itself overrides the state of the regular chunk (in practise, it would be highly preferable <i>not</i> to have errors in finalizers). If one finalizer errors, the others may not get called.
551</p> 748</p>
552 749
553 750
@@ -555,195 +752,181 @@ If one finalizer errors, the others may not get called.
555<hr/> 752<hr/>
556<h2 id="lindas">Lindas</h2> 753<h2 id="lindas">Lindas</h2>
557 754
558<p>Communications between lanes is completely detached from the lane handles 755<p>
559themselves. By itself, a lane can only provide return values once it's finished, 756 Communications between lanes is completely detached from the lane handles themselves. By itself, a lane can only provide return values once it's finished, or throw an error.
560or throw an error. Needs to communicate during runtime are handled by <A HREF="http://en.wikipedia.org/wiki/Linda_%28coordination_language%29" TARGET="_blank">Linda objects</A>, which are 757 Needs to communicate during runtime are handled by <a href="http://en.wikipedia.org/wiki/Linda_%28coordination_language%29" target="_blank">Linda objects</a>, which are
561<A HREF="#deep_userdata">deep userdata</A> instances. They can be provided to a lane 758 <a href="#deep_userdata">deep userdata</a> instances. They can be provided to a lane as startup parameters, upvalues or in some other Linda's message.
562as startup parameters, upvalues or in some other Linda's message. 759</p>
563</p><p>
564Access to a Linda object means a lane can read or write to any of its data
565slots. Multiple lanes can be accessing the same Linda in parallel. No application
566level locking is required; each Linda operation is atomic.
567</p><p>
568
569<table border=1 bgcolor="#FFFFE0" width=500><tr><td>
570<pre>
571 require "lanes"
572
573 local linda= lanes.linda()
574
575 local function loop( max )
576 for i=1,max do
577 print( "sending: "..i )
578 linda:send( "x", i ) -- linda as upvalue
579 end
580 end
581
582 a= lanes.gen("",loop)( 10000 )
583
584 while true do
585 local val= linda:receive( 3.0, "x" ) -- timeout in seconds&nbsp;
586 if val==nil then
587 print( "timed out" )
588 break
589 end
590 print( "received: "..val )
591 end
592</pre>
593</table>
594 760
761<p>
762 Access to a Linda object means a lane can read or write to any of its data slots. Multiple lanes can be accessing the same Linda in parallel. No application level locking is required; each Linda operation is atomic.
595</p> 763</p>
596<p>Characteristics of the Lanes implementation of Lindas are: 764
597 765<table border="1" bgcolor="#FFFFE0" cellpadding="10" style="width:50%"><tr><td><pre>
598<ul> 766 require "lanes".configure()
599 <li>keys can be of boolean, number, string or light userdata type 767
600 </li> 768 local linda = lanes.linda()
601 <li>values can be any type supported by inter-state copying (same limits 769
602 as for function parameters and upvalues) 770 local function loop( max)
603 </li> 771 for i = 1, max do
604 <li>consuming method is <tt>:receive</tt> (not in) 772 print( "sending: " .. i)
605 </li> 773 linda:send( "x", i) -- linda as upvalue
606 <li>non-consuming method is <tt>:get</tt> (not rd) 774 end
607 </li> 775 end
608 <li>two producer-side methods: <tt>:send</tt> and <tt>:set</tt> (not out) 776
609 </li> 777 a = lanes.gen( "", loop)( 10000)
610 <li><tt>send</tt> allows for sending multiple values -atomically- to a 778
611 given key 779 while true do
612 </li> 780 local key, val = linda:receive( 3.0, "x") -- timeout in seconds
613 <li><tt>receive</tt> can wait for multiple keys at once 781 if val == nil then
614 </li> 782 print( "timed out")
615 <li> 783 break
616 <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> 784 end
617 </li> 785 print( "received: " .. val)
618 <li>individual keys' queue length can be limited, balancing speed differences 786 end
619 in a producer/consumer scenario (making <tt>:send</tt> wait) 787</pre></td></tr></table>
620 </li> 788
621</ul> 789<p>
790 Characteristics of the Lanes implementation of Lindas are:
791
792 <ul>
793 <li>Keys can be of boolean, number, string or light userdata type. Tables and functions can't be keys because their identity isn't preserved when transfered from one Lua state to another.</li>
794 <li>values can be any type supported by inter-state copying (same <a href="#limitations">limits</a> as for function parameters and upvalues).</li>
795 <li>consuming method is <tt>:receive</tt> (not in).</li>
796 <li>non-consuming method is <tt>:get</tt> (not rd).</li>
797 <li>two producer-side methods: <tt>:send</tt> and <tt>:set</tt> (not out).</li>
798 <li><tt>send</tt> allows for sending multiple values -atomically- to a given key.</li>
799 <li><tt>receive</tt> can wait for multiple keys at once.</li>
800 <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>
801 <li>individual keys' queue length can be limited, balancing speed differences in a producer/consumer scenario (making <tt>:send</tt> wait).</li>
802 </ul>
803</p>
804
805<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
806 h = lanes.linda( [opt_name])
807
808 bool = h:send( [timeout_secs,] key, ... )
809
810 [key, val] = h:receive( [timeout_secs,] key [, ...])
811
812 [key, val [, ...]] = h:receive( timeout, h.batched, key, n_uint_min[, n_uint_max])
813
814 void = h:limit( key, n_uint)
815</pre></td></tr></table>
816
817<p>
818 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.
622</p> 819</p>
623 820
624<p> 821<p>
625<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td> 822 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.
626 <code>h= lanes.linda( [opt_name])</code> 823</p>
627 <br/><br/>
628 <code>bool= h:send( [timeout_secs,] key, ... )</code>
629 <br/>
630 <code>[val, key]= h:receive( [timeout_secs,] key [, ...] )</code>
631 <br/><br/>
632 <code>= h:limit( key, n_uint )</code>
633</table>
634 824
635<p>The <tt>send</tt> and <tt>receive</tt> methods use Linda keys as FIFO stacks 825<p>
636(first in, first out). Timeouts are given in seconds (millisecond accuracy). 826 Note that any number of lanes can be reading or writing a Linda. There can be many producers, and many consumers. It's up to you.
637If using numbers as the first Linda key, one must explicitly give <tt>nil</tt> 827</p>
638as the timeout parameter to avoid ambiguities.
639</p><p>
640By default, stack sizes are unlimited but limits can be
641enforced using the <tt>limit</tt> method. This can be useful to balance execution
642speeds in a producer/consumer scenario.
643</p><p>
644Note that any number of lanes can be reading or writing a Linda. There can be
645many producers, and many consumers. It's up to you.
646</p>
647<p><tt>send</tt> returns <tt>true</tt> if the sending succeeded, and <tt>false</tt>
648if the queue limit was met, and the queue did not empty enough during the given
649timeout.
650</p><p>
651Equally, <tt>receive</tt> returns a value and the key that provided the value,
652or nothing for timeout. Note that <tt>nil</tt>s can be sent and received;
653the <tt>key</tt> value will tell it apart from a timeout.
654</p><p>
655Multiple values can be sent to a given key at once, atomically (the send will
656fail unless all the values fit within the queue limit). This can be useful for
657multiple producer scenarios, if the protocols used are giving data in streams
658of multiple units. Atomicity avoids the producers from garbling each others
659messages, which could happen if the units were sent individually.
660</p><p>
661
662When receiving from multiple slots, the keys are checked in order, which can
663be used for making priority queues.
664</p><p>
665
666<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td>
667 <code>linda_h:set( key, [val] )</code>
668 <br/>
669 <code>[val]= linda_h:get( key )</code>
670</table>
671 828
672</p><p> 829<p>
673The table access methods are for accessing a slot without queuing or consuming. 830 <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, or the operation was <a href="#cancelling">cancelled</a>.
674They can be used for making shared tables of storage among the lanes. 831</p>
675</p><p>
676Writing to a slot overwrites existing value, and clears any possible queued
677entries. Table access and <tt>send</tt>/<tt>receive</tt> can be used together;
678reading a slot essentially peeks the next outcoming value of a queue.
679</p>
680 <p>
681
682 <table border="1" bgcolor="#E0E0FF" cellpadding="10">
683 <tr>
684 <td>
685 <code>[val]= linda_h:count( [key[,...]])</code>
686 </table>
687
688 </p>
689 <p>
690 Returns some information about the contents of the linda.
691 <br/>If no key is specified, and the linda is empty, returns nothing.
692 <br/>If no key is specified, and the linda is not empty, returns a table of key/count pairs that counts the number of items in each
693 of the exiting keys of the linda. This count can be 0 if the key has been used but is empty.
694 <br/>If a single key is specified, returns the number of pending items, or nothing if the key is unknown.
695 <br/>If more than one key is specified, return a table of key/count pairs for the known keys.
696 </p>
697 832
698<!--
699<p> 833<p>
700<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td> 834 Equally, <tt>receive</tt> returns a key and the value extracted from it, or nothing for timeout or <a href="#cancelling">cancellation</a>. Note that <tt>nil</tt>s can be sent and received; the <tt>key</tt> value will tell it apart from a timeout.
701 <code>lightuserdata= linda_h:deep()</code> 835 <br>
702</table> 836 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.
837</p>
703 838
704<p>There is one more method that is not required in applications, but 839<p>
705discussing it is good for a preview of how deep userdata works. 840 Multiple values can be sent to a given key at once, atomically (the send will fail unless all the values fit within the queue limit). This can be useful for multiple producer scenarios, if the protocols used are giving data in streams of multiple units.
706</p><p> 841 Atomicity avoids the producers from garbling each others messages, which could happen if the units were sent individually.
707Because proxy objects (<tt>linda_h</tt>) are just pointers to the real, deep 842</p>
708userdata, they cannot be used to identify a certain Linda from the others. 843
709The internal timer system needs to do this, and the <tt>:deep()</tt> method 844<p>
710has been added for its use. It returns a light userdata pointing to the 845 When receiving from multiple slots, the keys are checked in order, which can be used for making priority queues.
711<i>actual</i> deep object, and thus can be used for seeing, which proxies actually 846</p>
712mean the same underlying object. You might or might not need a similar system 847
713with your own deep userdata. 848<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
849 linda_h:set( key, [val])
850
851 [val] = linda_h:get( key )
852</pre></td></tr></table>
853
854<p>
855 The table access methods are for accessing a slot without queuing or consuming. They can be used for making shared tables of storage among the lanes.
856</p>
857
858<p>
859 Writing to a slot overwrites existing value, and clears any possible queued entries. Table access and <tt>send</tt>/<tt>receive</tt> can be used together; reading a slot essentially peeks the next outcoming value of a queue.
860</p>
861
862<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
863 [val] = linda_h:count( [key[,...]])
864</pre></td></tr></table>
865
866<p>
867 Returns some information about the contents of the linda.
868 <br>
869 If no key is specified, and the linda is empty, returns nothing.
870 <br>
871 If no key is specified, and the linda is not empty, returns a table of key/count pairs that counts the number of items in each of the exiting keys of the linda. This count can be 0 if the key has been used but is empty.
872 <br>
873 If a single key is specified, returns the number of pending items, or nothing if the key is unknown.
874 <br>
875 If more than one key is specified, return a table of key/count pairs for the known keys.
714</p> 876</p>
715-->
716 877
878<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
879 [table] = linda_h:dump()
880</pre></td></tr></table>
881
882<p>
883 Returns a table describing the full contents of a linda, or <tt>nil</tt> if the linda wasn't used yet.
884</p>
717 885
718<h3>Granularity of using Lindas</h3> 886<h3>Granularity of using Lindas</h3>
719 887
720<p>A single Linda object provides an infinite number of slots, so why would 888<p>
721you want to use several? 889 A linda is a gateway to read and write data inside some hidden Lua states, called keeper states. Lindas are hashed to a fixed number of keeper states, which are a locking entity.
722</p><p>There are some important reasons: 890 <br>
723 891 The data sent through a linda is stored inside the associated keeper state in a Lua table where each linda slot is the key to another table containing a FIFO for that slot.
724<ul> 892 <br>
725 <li>Access control. If you don't trust certain code completely, or just 893 Each keeper state is associated with an OS mutex, to prevent concurrent access to the keeper state. The linda itself uses two signals to be made aware of operations occuring on it.
726 to modularize your design, use one Linda for one usage and another one 894 <br>
727 for the other. This keeps your code clear and readable. You can pass 895 Whenever Lua code reads from or writes to a linda, the mutex is acquired. If linda limits don't block the operation, it is fulfilled, then the mutex is released.
728 multiple Linda handles to a lane with practically no added cost. 896 <br>
729 </li> 897 If the linda has to block, the mutex is released and the OS thread sleeps, waiting for a linda operation to be signalled. When an operation occurs on the same linda, possibly fufilling the condition, or a timeout expires, the thread wakes up.
730 898 <br>
731 <li>Namespace control. Linda keys have a "flat" namespace, so collisions 899 If the thread is woken but the condition is not yet fulfilled, it goes back to sleep, until the timeout expires.
732 are possible if you try to use the same Linda for too many separate uses. 900 <br>
733 </li> 901 When a lane is cancelled, the signal it is waiting on (if any) is signalled. In that case, the linda operation will return no data.
734 902</p>
735 <li>Performance. Changing any slot in a Linda causes all pending threads 903
736 for that Linda to be momentarily awakened (at least in the C level). 904<p>
737 This can degrade performance due to unnecessary OS level context switches. 905 A single Linda object provides an infinite number of slots, so why would you want to use several?
738 The more keeper states you declared with <tt>lanes.configure()</tt> the less 906</p>
739 this should be a problem. 907
740 </li> 908<p>
741</ul> 909 There are some important reasons:
910 <ul>
911 <li>
912 Access control. If you don't trust certain code completely, or just to modularize your design, use one Linda for one usage and another one
913 for the other. This keeps your code clear and readable. You can pass multiple Linda handles to a lane with practically no added cost.
914 </li>
915
916 <li>
917 Namespace control. Linda keys have a "flat" namespace, so collisions are possible if you try to use the same Linda for too many separate uses.
918 </li>
919
920 <li>
921 Performance. Changing any slot in a Linda causes all pending threads for that Linda to be momentarily awakened (at least in the C level).
922 This can degrade performance due to unnecessary OS level context switches. The more keeper states you declared with <tt>lanes.configure()</tt> the less this should be a problem.
923 </li>
924 </ul>
925
926On the other side, you need to use a common Linda for waiting for multiple keys. You cannot wait for keys from two separate Linda objects at the same time.
927</p>
742 928
743On the other side, you need to use a common Linda for waiting for multiple 929<p>
744keys. You cannot wait for keys from two separate Linda objects at the same
745time.
746</p><p>
747<font size="-1">Actually, you can. Make separate lanes to wait each, and then multiplex those 930<font size="-1">Actually, you can. Make separate lanes to wait each, and then multiplex those
748events to a common Linda, but... :).</font> 931events to a common Linda, but... :).</font>
749</p> 932</p>
@@ -753,77 +936,66 @@ events to a common Linda, but... :).</font>
753<hr/> 936<hr/>
754<h2 id="timers">Timers</h2> 937<h2 id="timers">Timers</h2>
755 938
756<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td> 939<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
757 <code>= lanes.timer( linda_h, key, date_tbl|first_secs [,period_secs] )</code> 940 void = lanes.timer( linda_h, key, date_tbl|first_secs [,period_secs])
758</table> 941</pre></td></tr></table>
759 942
760<p> 943<p>
761 Timers are implemented as a lane. They can be disabled by setting <tt>"with_timers"</tt> to <tt>nil</tt> or <tt>false</tt> 944 Timers are implemented as a lane. They can be disabled by setting <tt>"with_timers"</tt> to <tt>nil</tt> or <tt>false</tt> to <tt>lanes.configure()</tt>.
762 to <tt>lanes.configure()</tt>. 945</p>
763 </p> 946
764<p> 947<p>
765Timers can be run once, or in a reoccurring fashion (<tt>period_secs > 0</tt>). 948 Timers can be run once, or in a reoccurring fashion (<tt>period_secs > 0</tt>). The first occurrence can be given either as a date or as a relative delay in seconds. The <tt>date</tt> table is like what <tt>os.date("*t")</tt> returns, in the local time zone.
766The first occurrence can be given either as a date or as a relative delay in seconds. 949</p>
767The <tt>date</tt> table is like what <tt>os.date("*t")</tt> returns, in the 950
768local time zone. 951<p>
769</p><p> 952 Once a timer expires, the <tt>key</tt> is set with the current time (in seconds, same offset as <tt>os.time()</tt> but with millisecond accuracy). The key can be waited upon using the regular Linda <tt>:receive()</tt> method.
770Once a timer expires, the <tt>key</tt> is set with the current time 953</p>
771(in seconds, same offset as <tt>os.time()</tt> but with millisecond accuracy).
772The key can be waited upon using the regular Linda <tt>:receive()</tt>
773method.
774</p><p>
775A timer can be stopped simply with <tt>first_secs=0|nil</tt> and no period.
776</p><p>
777
778<table border=1 bgcolor="#FFFFE0" width=500><tr><td>
779<pre>
780 local lanes = require "lanes"
781 lanes.configure( 1)
782 954
783 local linda= lanes.linda() 955<p>
956 A timer can be stopped simply with <tt>first_secs=0|nil</tt> and no period.
957</p>
784 958
785 -- First timer once a second, not synchronized to wall clock 959<table border="1" bgcolor="#FFFFE0" cellpadding="10" style="width:50%"><tr><td><pre>
786 -- 960 local lanes = require "lanes"
787 lanes.timer( linda, "sec", 1, 1 ) 961 lanes.configure()
788 962
789 -- Timer to a future event (next even minute); wall clock synchronized&nbsp; 963 local linda = lanes.linda()
790 --
791 local t= os.date( "*t", os.time()+60 ) -- now + 1min
792 t.sec= 0
793 964
794 lanes.timer( linda, "min", t, 60 ) -- reoccur every minute (sharp) 965 -- First timer once a second, not synchronized to wall clock
966 --
967 lanes.timer( linda, "sec", 1, 1)
795 968
796 while true do 969 -- Timer to a future event (next even minute); wall clock synchronized
797 local v,key= linda:receive( "sec", "min" ) 970 --
798 print( "Timer "..key..": "..v ) 971 local t = os.date( "*t", os.time() + 60) -- now + 1min
799 end 972 t.sec = 0
800</pre> 973
801</table> 974 lanes.timer( linda, "min", t, 60) -- reoccur every minute (sharp)
975
976 while true do
977 local key, v = linda:receive( "sec", "min")
978 print( "Timer "..key..": "..v)
979 end
980</pre></td></tr></table>
981
982<p>
983 NOTE: Timer keys are set, not queued, so missing a beat is possible especially if the timer cycle is extremely small. The key value can be used to know the actual time passed.
984</p>
802 985
803</p><p>
804NOTE: Timer keys are set, not queued, so missing a beat is possible especially
805if the timer cycle is extremely small. The key value can be used to know the
806actual time passed.
807</p><p>
808<table> 986<table>
809 <tr><td valign=top><nobr><i>Design note:</i></nobr>&nbsp;</td> 987 <tr>
810 <td> 988 <td valign=top><i><nobr>Design note:</nobr></i></td>
811<font size="-1"> 989 <td>
812Having the API as <tt>lanes.timer()</tt> is intentional. Another 990 <font size="-1">
813alternative would be <tt>linda_h:timer()</tt> but timers are not traditionally 991 Having the API as <tt>lanes.timer()</tt> is intentional. Another alternative would be <tt>linda_h:timer()</tt> but timers are not traditionally seen to be part of Lindas. Also, it would mean any lane getting a Linda handle would be able to modify timers on it.
814seen to be part of Lindas. Also, it would mean any lane getting a Linda handle 992 A third choice could be abstracting the timers out of Linda realm altogether (<tt>timer_h= lanes.timer( date|first_secs, period_secs )</tt>) but that would mean separate waiting functions for timers, and lindas.
815would be able to modify timers on it. A third choice could 993 Even if a linda object and key was returned, that key couldn't be waited upon simultaneously with one's general linda events.
816be abstracting the timers out of Linda realm altogether (<tt>timer_h= lanes.timer( date|first_secs, period_secs )</tt>) 994 The current system gives maximum capabilities with minimum API, and any smoothenings can easily be crafted in Lua at the application level.
817but that would mean separate waiting functions for timers, and lindas. Even if 995 </font>
818a linda object and key was returned, that key couldn't be waited upon simultaneously 996 </td>
819with one's general linda events. 997 </tr>
820The current system gives maximum capabilities with minimum API, and any smoothenings
821can easily be crafted in Lua at the application level.
822</font>
823 </td>
824 </tr>
825</table> 998</table>
826</p>
827 999
828 1000
829<!-- locks +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 1001<!-- locks +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
@@ -831,46 +1003,43 @@ can easily be crafted in Lua at the application level.
831<h2 id="locks">Locks etc.</h2> 1003<h2 id="locks">Locks etc.</h2>
832 1004
833<p> 1005<p>
834Lanes does not generally require locks or critical sections to be used, at all. 1006 Lanes does not generally require locks or critical sections to be used, at all. If necessary, a limited queue can be used to emulate them. <tt>lanes.lua</tt> offers some sugar to make it easy:
835If necessary, a limited queue can be used to emulate them. <tt>lanes.lua</tt> 1007</p>
836offers some sugar to make it easy:
837</p><p>
838 1008
839<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td><pre> 1009<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
840 lock_func= lanes.genlock( linda_h, key [,N_uint=1] ) 1010 lock_func = lanes.genlock( linda_h, key [,N_uint=1])
841 1011
842 lock_func( M_uint ) -- acquire 1012 lock_func( M_uint ) -- acquire
843 .. 1013 ..
844 lock_func( -M_uint ) -- release 1014 lock_func( -M_uint ) -- release
845</table> 1015</pre></td></tr></table>
846</p><p>
847 1016
848The generated function acquires M entries from the N available, or releases 1017<p>
849them if the value is negative. The acquiring call will suspend the lane, if necessary. 1018 The generated function acquires M entries from the N available, or releases them if the value is negative. The acquiring call will suspend the lane, if necessary. Use <tt>M=N=1</tt> for a critical section lock (only one lane allowed to enter).
850Use <tt>M=N=1</tt> for a critical section lock (only one lane allowed to enter). 1019</p>
851</p><p>
852 1020
853Note: The locks generated are <u>not recursive</u>. That would need another 1021<p>
854kind of generator, which is currently not implemented. 1022 Note: The locks generated are <u>not recursive</u>. That would need another kind of generator, which is currently not implemented.
855</p><p> 1023</p>
856 1024
857Similar sugar exists for atomic counters: 1025<p>
858</p><p> 1026 Similar sugar exists for atomic counters:
1027</p>
859 1028
860<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td><pre> 1029<p>
861 atomic_func= lanes.genatomic( linda_h, key [,initial_num=0.0] )
862 1030
863 new_num= atomic_func( [diff_num=+1.0] ) 1031<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
864</table> 1032 atomic_func = lanes.genatomic( linda_h, key [,initial_num=0.0])
865</p><p>
866 1033
867Each time called, the generated function will change <tt>linda[key]</tt> 1034 new_num = atomic_func( [diff_num=+1.0])
868atomically, without other lanes being able to interfere. The new value is 1035</pre></td></tr></table>
869returned. You can use either <tt>diff 0.0</tt> or <tt>get</tt> to just read the current
870value.
871</p><p>
872 1036
873Note that the generated functions can be passed on to other lanes. 1037<p>
1038 Each time called, the generated function will change <tt>linda[key]</tt> atomically, without other lanes being able to interfere. The new value is returned. You can use either <tt>diff 0.0</tt> or <tt>get</tt> to just read the current value.
1039</p>
1040
1041<p>
1042 Note that the generated functions can be passed on to other lanes.
874</p> 1043</p>
875 1044
876 1045
@@ -880,209 +1049,218 @@ Note that the generated functions can be passed on to other lanes.
880 1049
881<h3>Limitations on data passing</h3> 1050<h3>Limitations on data passing</h3>
882 1051
883<p>Data passed between lanes (either as starting parameters, return values, upvalues or via Lindas) must conform to the following: 1052<p>
1053 Data passed between lanes (either as starting parameters, return values, upvalues or via Lindas) must conform to the following:
884</p> 1054</p>
885<p><ul> 1055
886 <li>Booleans, numbers, strings, light userdata, Lua functions and tables of such can always be passed. 1056<p>
887 </li> 1057 <ul>
888 <li>Cyclic tables and/or duplicate references are allowed and reproduced appropriately, 1058 <li>Booleans, numbers, strings, light userdata, Lua functions and tables of such can always be passed.</li>
889 but only <u>within the same transmission</u>. 1059 <li>
890 <ul> 1060 Cyclic tables and/or duplicate references are allowed and reproduced appropriately, but only <u>within the same transmission</u>.
891 <li>using the same source table in multiple Linda messages keeps no ties between the tables 1061 <ul>
892 </li> 1062 <li>Using the same source table in multiple Linda messages keeps no ties between the tables (this is the same reason why tables can't be used as keys).</li>
893 </ul> 1063 </ul>
894 </li> 1064 </li>
895 <li>Objects (tables with a metatable) are copyable between lanes. 1065 <li>
896 <ul> 1066 Objects (tables with a metatable) are copyable between lanes.
897 <li>metatables are assumed to be immutable; they are internally indexed and only copied once 1067 <ul>
898 per each type of objects per lane 1068 <li>Metatables are assumed to be immutable; they are internally indexed and only copied once per each type of objects per lane.</li>
899 </li> 1069 </ul>
900 </ul> 1070 </li>
901 </li> 1071 <li>
902 <li>C functions (<tt>lua_CFunction</tt>) referring to <tt>LUA_ENVIRONINDEX</tt> or <tt>LUA_REGISTRYINDEX</tt> might not 1072 C functions (<tt>lua_CFunction</tt>) referring to <tt>LUA_ENVIRONINDEX</tt> or <tt>LUA_REGISTRYINDEX</tt> might not work right in the target
903 work right in the target 1073 <ul>
904 <ul> 1074 <li>Rather completely re-initialize a module with <tt>require</tt> in the target lane.</li>
905 <li>rather completely re-initialize a module with <tt>require</tt> in the target lane 1075 </ul>
906 </li> 1076 </li>
907 </ul> 1077 <li>
908 </li> 1078 Full userdata can be passed only if it's prepared using the <a href="#deep_userdata">deep userdata</a> system, which handles its lifespan management
909 <li>Full userdata can be passed only if it's prepared using the <A HREF="#deep_userdata">deep userdata</A> 1079 <ul>
910 system, which handles its lifespan management 1080 <li>In particular, lane handles cannot be passed between lanes.</li>
911 <ul> 1081 </ul>
912 <li>in particular, lane handles cannot be passed between lanes 1082 </li>
913 </li> 1083 <li>Coroutines cannot be passed. A coroutine's Lua state is tied to the Lua state that created it, and there is no way the mixed C/Lua stack of a couroutine can be transfered from one Lua state to another.</li>
914 </ul> 1084 </ul>
915 </li> 1085</p>
916 <li>coroutines cannot be passed 1086
917 </li> 1087
918</ul> 1088<h3 id="function_notes">Notes about passing C functions</h3>
1089
1090<p>
1091 Originally, a C function was copied from one Lua state to another as follows:
1092</p>
1093
1094<table border="1" bgcolor="#FFFFE0" cellpadding="10" style="width:50%"><tr><td><pre>
1095 // expects a C function on top of the source Lua stack
1096 copy_func( lua_State *dest, lua_State* source)
1097 {
1098 // extract C function pointer from source
1099 lua_CFunction func = lua_tocfunction( source, -1);
1100 // transfer upvalues
1101 int nup = trasnfer_upvalues( dest, source);
1102 // dest Lua stack contains a copy of all upvalues
1103 lua_pushcfunction( dest, func, nup);
1104 }
1105</pre></td></tr></table>
1106
1107<p>
1108 This has the main drawback of not being LuaJIT-compatible, because some functions registered by LuaJIT are not regular C functions, but specially optimized implementations. As a result, <tt>lua_tocfunction()</tt> returns NULL for them.
1109 <br>
1110 Therefore, Lanes no longer transfers functions that way. Instead, functions are transfered as follows (more or less):
1111</p>
1112
1113<table border="1" bgcolor="#FFFFE0" cellpadding="10" style="width:50%"><tr><td><pre>
1114 // expects a C function on top of the source Lua stack
1115 copy_func( lua_State *dest, lua_State* source)
1116 {
1117 // extract C function pointer from source
1118 char const* funcname = lookup_func_name( source, -1);
1119 // lookup a function bound to this name in the destination state, and push it on the stack
1120 push_resolved_func( dest, funcname);
1121 }
1122</pre></td></tr></table>
1123
1124<p>
1125 The devil lies in the details: what does "function lookup" mean?
1126</p>
1127
1128<p>
1129 Since functions are first class values, they don't have a name. All we know for sure is that when a C module registers some functions, they are accessible to the script that required the module through some exposed variables.
1130 <br>
1131 For example, loading the <tt>string</tt> base library creates a table accessible when indexing the global environment with key <tt>"string"</tt>. Indexing this table with <tt>"match"</tt>, <tt>"gsub"</tt>, etc. will give us a function.
1132 <br>
1133 When a lane generator creates a lane and performs initializations described by the list of base libraries and the list of required modules, it recursively scans the table created by the initialisation of the module, looking for all values that are C functions.
1134 <br>
1135 Each time a function is encountered, the sequence of keys that reached that function is contatenated in a (hopefully) unique name. The [name, function] and [function, name] pairs are both stored in a lookup table in all involved Lua states (main Lua state, keeper states, lanes states).
1136 <br>
1137 Then when a function is transfered from one state to another, all we have to do is retrieve the name associated to a function in the source Lua state, then with that name retrieve the equivalent function that already exists in the destination state.
1138 <br>
1139 Note that there is no need to transfer upvalues, as they are already bound to the function registered in the destination state. (And in any event, it is not possible to create a closure from a C function pushed on the stack, it can only be created with a lua_CFunction pointer).
1140</p>
1141
1142<p>
1143 There are two issues here:
1144 <ul>
1145 <li>Some base libraries register some C functions in the global environment. Because of that, Lanes must scan the global namespace to find all C functions (such as <tt>error</tt>, <tt>print</tt>, etc.).</li>
1146 <li>
1147 Nothing prevents a script to create other references to a C function. For example one could do
1148 <table border="1" bgcolor="#FFFFE0" cellpadding="10" style="width:50%"><tr><td><pre>
1149 string2 = string
1150 </pre></td></tr></table>
1151 When iterating over all keys of the global table, Lanes has no guarantee that it will hit <tt>"string"</tt> before or after <tt>"string2"</tt>. However, the values associated to <tt>string.match</tt> and <tt>string2.match</tt> are the same C function.
1152 Lanes doesn't expect a C function value to be encountered more than once. In the event it occurs, when the lookup table is populated with a [function, name] pair, an existing pair won't be updated if it is already found. In other words, the first name that was computed is retained.
1153 If Lanes processed <tt>"string2"</tt> first, it means that if the Lua state that contains the <tt>"string2"</tt> global name sends function <tt>string.match</tt>, <tt>lookup_func_name</tt> would return name <tt>"string2.match"</tt>, with the obvious effect that <tt>push_resolved_func</tt>
1154 won't find <tt>"string2.match"</tt> in the destination lookup database, thus failing the transfer (even though this function is referenced under name <tt>"string.match"</tt>).
1155 </li>
1156 </ul>
1157 Another more direct reason of failed transfer is that the destination state doesn't know about the C function that has to be transferred. This occurs if a function is tranferred in a lane before it had a chance to scan the module.
1158 If the C function is sent through a linda, it is enough for the destination lane body to have required the module before the function is sent.
1159 But if the lane body provided to the generator has a C function as upvalue, the transfer itself must succeed, therefore the module that imported that C function must be required in the destination lane before the lane body starts executing. This is where the <a href = "#.required"><tt>.required</tt></a> options play their role.
919</p> 1160</p>
920 1161
921 1162
922<h3>Required of module makers</h3> 1163<h3>Required of module makers</h3>
923 1164
924<p> 1165<p>
925Most Lua extension modules should work unaltered with Lanes. 1166 Most Lua extension modules should work unaltered with Lanes. If the module simply ties C side features to Lua, everything is fine without alterations. The <tt>luaopen_...()</tt> entry point will be called separately for each lane, where the module is <tt>require</tt>'d from.
926If the module simply ties C side features to Lua, everything is fine without 1167</p>
927alterations. The <tt>luaopen_...()</tt> entry point will be called separately for each
928lane, where the module is <tt>require</tt>'d from.
929</p><p>
930If it, however, also does one-time C side initializations, these
931should be covered into a one-time-only construct such as below.
932</p><p>
933 1168
934<table><tr><td width=40> 1169<p>
935 <td bgcolor="#ffffe0"> 1170 If it, however, also does one-time C side initializations, these should be covered into a one-time-only construct such as below.
936<pre>
937 int luaopen_module( lua_State *L )
938 {
939 static char been_here; /* 0 by ANSI C */
940
941 /* Calls to 'require' serialized by Lanes; this is safe.&nbsp;&nbsp;
942 */
943 if (!been_here) {
944 been_here= 1;
945 ... one time initializations ...
946 }
947
948 ... binding to Lua ...
949 }
950</pre>
951</td></tr></table>
952</p> 1171</p>
953 1172
1173<table border="1" bgcolor="#FFFFE0" cellpadding="10" style="width:50%"><tr><td><pre>
1174 int luaopen_module( lua_State *L )
1175 {
1176 static char been_here; /* 0 by ANSI C */
1177
1178 // Calls to 'require' serialized by Lanes; this is safe.
1179 if (!been_here)
1180 {
1181 been_here= 1;
1182 ... one time initializations ...
1183 }
1184 ... binding to Lua ...
1185 }
1186</pre></td></tr></table>
1187
954 1188
955<h3 id="shared_userdata">Deep userdata in your own apps</h3> 1189<h3 id="shared_userdata">Deep userdata in your own apps</h3>
956 1190
957<p> 1191<p>
958The mechanism Lanes uses for sharing Linda handles between separate Lua states 1192 The mechanism Lanes uses for sharing Linda handles between separate Lua states can be used for custom userdata as well. Here's what to do.
959can be used for custom userdata as well. Here's what to do.
960</p> 1193</p>
1194
961<ol> 1195<ol>
962 <li>Provide an <i>identity function</i> for your userdata, in C. This function is 1196 <li>
963used for creation and deletion of your deep userdata (the shared resource), 1197 Provide an <i>identity function</i> for your userdata, in C. This function is used for creation and deletion of your deep userdata (the shared resource), and for making metatables for the state-specific proxies for accessing it. The prototype is
964 and for making metatables for the state-specific proxies for accessing it. The 1198 <table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
965 prototype is 1199 void idfunc( lua_State *L, char const * const which);
966 <table border="1" bgcolor="#E0E0FF" cellpadding="10"> 1200 </pre></td></tr></table>
967 <tr> 1201 <tt>which</tt> can be one of:
968 <td> 1202 <ul>
969 <code>void idfunc( lua_State *L, char const * const which);</code> 1203 <li><tt>"new"</tt>: requests the creation of a new object, whose pointer is pushed on the stack as a light userdata.</li>
970 </table> 1204 <li><tt>"delete"</tt>: receives this same pointer on the stack, and should cleanup the object.</li>
971<tt>which</tt> can be one of: 1205 <li><tt>"metatable"</tt>: should build a metatable for the object. Don't cache the metatable yourself, Lanes takes care of it ("metatable" should only be invoked once).</li>
972<ul> 1206 <li><tt>"module"</tt>: is the name of the module that exports the idfunc, to be pushed on the stack as a string. It is necessary so that Lanes can require it in any Lane and keeper state that receives a userdata. This is to prevent crashes in situations where the module could be unloaded while the idfunc pointer is still held.</li>
973 <li> 1207 </ul>
974 <tt>"new"</tt>: requests the creation of a new object, whose pointer is pushed on the stack 1208 Take a look at <tt>linda_id</tt> in <tt>lanes.c</tt>.
975 as a light userdata. 1209 </li>
976 </li> 1210 <li>Instanciate your userdata using <tt>luaG_deep_userdata()</tt>, instead of the regular <tt>lua_newuserdata()</tt>. Given an <tt>idfunc</tt>, it sets up the support structures and returns a state-specific proxy userdata for accessing your data. This proxy can also be copied over to other lanes.</li>
977 <li> 1211 <li>Accessing the deep userdata from your C code, use <tt>luaG_todeep()</tt> instead of the regular <tt>lua_touserdata()</tt>.</li>
978 <tt>"delete"</tt>: receives this same pointer on the stack, and should cleanup the object.</li>
979 <li>
980 <tt>"metatable"</tt>: should build a metatable for the object. Don't cache the metatable
981yourself, Lanes takes care of it ("metatable" should only be invoked once).</li>
982 <li>
983 <tt>"module"</tt>: is the name of the module that exports the idfunc,
984to be pushed on the stack as a string. It is necessary so that Lanes can require it in
985any Lane and keeper state that receives a userdata. This is to prevent crashes in situations
986where the module could be unloaded while the idfunc pointer is still held.</li>
987</ul>
988Take a look at <tt>linda_id</tt> in <tt>lanes.c</tt>.
989 </li>
990 <li>Instanciate your userdata using <tt>luaG_deep_userdata()</tt>,
991 instead of the regular <tt>lua_newuserdata()</tt>.
992 Given an <tt>idfunc</tt>, it sets up the support
993 structures and returns a state-specific proxy userdata for accessing your
994 data. This proxy can also be copied over to other lanes.
995 </li>
996 <li>Accessing the deep userdata from your C code, use <tt>luaG_todeep()</tt>
997 instead of the regular <tt>lua_touserdata()</tt>.
998 </li>
999</ol> 1212</ol>
1000 1213
1001<p>Deep userdata management will take care of tying to <tt>__gc</tt> methods, 1214<p>
1002and doing reference counting to see how many proxies are still there for 1215 Deep userdata management will take care of tying to <tt>__gc</tt> methods, and doing reference counting to see how many proxies are still there for accessing the data. Once there are none, the data will be freed through a call to the <tt>idfunc</tt> you provided.
1003accessing the data. Once there are none, the data will be freed through a call
1004to the <tt>idfunc</tt> you provided.
1005</p> 1216</p>
1006<p><b>NOTE</b>: The lifespan of deep userdata may exceed that of the Lua state 1217
1007that created it. The allocation of the data storage should not be tied to 1218<p>
1008the Lua state used. In other words, use <tt>malloc</tt>/<tt>free</tt> or 1219 <b>NOTE</b>: The lifespan of deep userdata may exceed that of the Lua state that created it. The allocation of the data storage should not be tied to the Lua state used. In other words, use <tt>malloc</tt>/<tt>free</tt> or similar memory handling mechanism.
1009similar memory handling mechanism.
1010</p> 1220</p>
1011 1221
1012 1222
1013<h3>Lane handles don't travel</h3> 1223<h3>Lane handles don't travel</h3>
1014 1224
1015<p> 1225<p>
1016Lane handles are not implemented as deep userdata, and cannot thus be 1226 Lane handles are not implemented as deep userdata, and cannot thus be copied across lanes. This is intentional; problems would occur at least when multiple lanes were to wait upon one to get ready. Also, it is a matter of design simplicity.
1017copied across lanes. This is intentional; problems would occur at least when 1227</p>
1018multiple lanes were to wait upon one to get ready. Also, it is a matter of 1228
1019design simplicity. 1229<p>
1020</p><p> 1230 The same benefits can be achieved by having a single worker lane spawn all the sublanes, and keep track of them. Communications to and from this lane can be handled via a Linda.
1021The same benefits can be achieved by having a single worker lane spawn all
1022the sublanes, and keep track of them. Communications to and from this lane
1023can be handled via a Linda.
1024</p> 1231</p>
1025 1232
1026 1233
1027<h3>Beware with print and file output</h3> 1234<h3>Beware with print and file output</h3>
1028 1235
1029<p> 1236<p>
1030In multithreaded scenarios, giving multiple parameters to <tt>print()</tt> 1237 In multithreaded scenarios, giving multiple parameters to <tt>print()</tt> or <tt>file:write()</tt> may cause them to be overlapped in the output, something like this:
1031or <tt>file:write()</tt> may cause them to be overlapped in the output,
1032something like this:
1033 1238
1034<pre> 1239<table border="1" bgcolor="#FFFFE0" cellpadding="10" style="width:50%"><tr><td><pre>
1035 A: print( 1, 2, 3, 4 ) 1240 A: print( 1, 2, 3, 4 )
1036 B: print( 'a', 'b', 'c', 'd' ) 1241 B: print( 'a', 'b', 'c', 'd' )
1037 1242
1038 1 a b 2 3 c d 4 1243 1 a b 2 3 c d 4
1039</pre> 1244</pre></td></tr></table>
1040 1245
1041Lanes does not protect you from this behaviour. The thing to do is either to 1246 Lanes does not protect you from this behaviour. The thing to do is either to concentrate your output to a certain lane per stream, or to concatenate output into a single string before you call the output function.
1042concentrate your output to a certain lane per stream, or to concatenate output
1043into a single string before you call the output function.
1044</p> 1247</p>
1045 1248
1046 1249
1047<h3 id="performance">Performance considerations</h3> 1250<h3 id="performance">Performance considerations</h3>
1048 1251
1049<p> 1252<p>
1050Lanes is about making multithreading easy, and natural in the Lua state of mind. 1253 Lanes is about making multithreading easy, and natural in the Lua state of mind. Expect performance not to be an issue, if your program is logically built. Here are some things one should consider, if best performance is vital:
1051Expect performance not to be an issue, if your program is logically built. 1254</p>
1052Here are some things one should consider, if best performance is vital: 1255
1053</p><p> 1256<p>
1054<ul> 1257 <ul>
1055 <li>Data passing (parameters, upvalues, Linda messages) is generally fast, 1258 <li>Data passing (parameters, upvalues, Linda messages) is generally fast, doing two binary state-to-state copies (from source state to hidden state, hidden state to target state). Remember that not only the function you specify but also its upvalues, their upvalues, etc. etc. will get copied.</li>
1056 doing two binary state-to-state copies (from source state to hidden state, 1259 <li>Lane startup is fast (1000's of lanes a second), depending on the number of standard libraries initialized. Initializing all standard libraries is about 3-4 times slower than having no standard libraries at all. If you throw in a lot of lanes per second, make sure you give them minimal necessary set of libraries.</li>
1057 hidden state to target state). Remember that not only the function you 1260 <li>Waiting Lindas are woken up (and execute some hidden Lua code) each time <u>any</u> key in the Lindas they are waiting for are changed. This may give essential slow-down (not measured, just a gut feeling) if a lot of Linda keys are used. Using separate Linda objects for logically separate issues will help (which is good practise anyhow).</li>
1058 specify but also its upvalues, their upvalues, etc. etc. will get copied. 1261 <li>Linda objects are light. The memory footprint is two OS-level signalling objects (<tt>HANDLE</tt> or <tt>pthread_cond_t</tt>) for each, plus one C pointer for the proxies per each Lua state using the Linda. Barely nothing.</li>
1059 </li> 1262 <li>Timers are light. You can probably expect timers up to 0.01 second resolution to be useful, but that is very system specific. All timers are merged into one main timer state (see <tt>timer.lua</tt>); no OS side timers are utilized.</li>
1060 <li>Lane startup is fast (1000's of lanes a second), depending on the 1263 <li>If you are using a lot of Linda objects, it may be useful to try having more of these keeper states. By default, only one is used (see <a href="#initialization"><tt>lanes.configure()</tt></a>).</li>
1061 number of standard libraries initialized. Initializing all standard libraries
1062 is about 3-4 times slower than having no standard libraries at all. If you
1063 throw in a lot of lanes per second, make sure you give them minimal necessary
1064 set of libraries.
1065 </li>
1066 <li>Waiting Lindas are woken up (and execute some hidden Lua code) each
1067 time <u>any</u> key in the Lindas they are waiting for are changed. This
1068 may give essential slow-down (not measured, just a gut feeling) if a lot
1069 of Linda keys are used. Using separate Linda objects for logically separate
1070 issues will help (which is good practise anyhow).
1071 </li>
1072 <li>Linda objects are light. The memory footprint is two OS-level signalling
1073 objects (<tt>HANDLE</tt> or <tt>pthread_cond_t</tt>) for each, plus one
1074 C pointer for the proxies per each Lua state using the Linda. Barely nothing.
1075 </li>
1076 <li>Timers are light. You can probably expect timers up to 0.01 second
1077 resolution to be useful, but that is very system specific. All timers are
1078 merged into one main timer state (see <tt>timer.lua</tt>); no OS side
1079 timers are utilized.
1080 </li>
1081 <li>Lindas are hashed to a fixed number of "keeper states", which are a locking entity.
1082 If you are using a lot of Linda objects,
1083 it may be useful to try having more of these keeper states. By default,
1084 only one is used (see <tt>lanes.configure()</tt>).
1085 </li>
1086</ul> 1264</ul>
1087</p> 1265</p>
1088 1266
@@ -1090,20 +1268,17 @@ Here are some things one should consider, if best performance is vital:
1090<h3 id="cancelling_cancel">Cancelling cancel</h3> 1268<h3 id="cancelling_cancel">Cancelling cancel</h3>
1091 1269
1092<p> 1270<p>
1093Cancellation of lanes uses the Lua error mechanism with a special lightuserdata 1271 Cancellation of lanes uses the Lua error mechanism with a special lightuserdata error sentinel.
1094error sentinel. 1272 If you use <tt>pcall</tt> in code that needs to be cancellable from the outside, the special error might not get through to Lanes, thus preventing the Lane from being cleanly cancelled.
1095If you use <tt>pcall</tt> in code that needs to be cancellable 1273 You should throw any lightuserdata error further.
1096from the outside, the special error might not get through to Lanes, thus 1274</p>
1097preventing the Lane from being cleanly cancelled. You should throw any 1275
1098lightuserdata error further. 1276<p>
1099</p><p> 1277 This system can actually be used by application to detect cancel, do your own cancellation duties, and pass on the error so Lanes will get it. If it does not get a clean cancellation from a lane in due time, it may forcefully kill the lane.
1100This system can actually be used by application to detect cancel, do your own 1278</p>
1101cancellation duties, and pass on the error so Lanes will get it. If it does 1279
1102not get a clean cancellation from a lane in due time, 1280<p>
1103it may forcefully kill the lane. 1281 The sentinel is exposed as <tt>lanes.cancel_error</tt>, if you wish to use its actual value.
1104</p><p>
1105The sentinel is exposed as <tt>lanes.cancel_error</tt>, if you wish to use
1106its actual value.
1107</p> 1282</p>
1108 1283
1109 1284
@@ -1113,21 +1288,20 @@ its actual value.
1113<h2 id="changes">Change log</h2> 1288<h2 id="changes">Change log</h2>
1114 1289
1115<p> 1290<p>
1116 See CHANGES. 1291 See CHANGES.
1117</p> 1292</p>
1118 1293
1119<!-- footnotes +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 1294<!-- footnotes +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
1120<hr/> 1295<hr/>
1121 1296
1122<p>For feedback, questions and suggestions: 1297<p>
1123<UL> 1298 For feedback, questions and suggestions:
1124 <li><A HREF="http://github.com/LuaLanes/lanes">Lanes @ GitHub</A></li> 1299 <ul>
1125 <li><A HREF="mailto:bnt.germain@gmail.com">the maintainer</A></li> 1300 <li><A HREF="http://github.com/LuaLanes/lanes">Lanes @ GitHub</A></li>
1126 <li><A HREF="http://www.lua.org/lua-l.html">the lua mailing list</A></li> 1301 <li><A HREF="mailto:bnt.germain@gmail.com">the maintainer</A></li>
1127</UL> 1302 <li><A HREF="http://www.lua.org/lua-l.html">the lua mailing list</A></li>
1303 </ul>
1128</p> 1304</p>
1129 1305
1130<p><br/></p>
1131
1132</body> 1306</body>
1133</html> 1307</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-03-17 00:00:43 +0000