From 36cddc5e17277c10b0301c4be04612ce75232da6 Mon Sep 17 00:00:00 2001
From: Benoit Germain <bnt.germain@gmail.com>
Date: Wed, 26 Sep 2012 21:22:30 +0200
Subject: 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
---
index.html | 1930 +++++++++++++++++++++++++++++++++---------------------------
1 file changed, 1052 insertions(+), 878 deletions(-)
(limited to 'index.html')
diff --git a/index.html b/index.html
index 932a712..bb64ba2 100644
--- a/index.html
+++ b/index.html
@@ -5,61 +5,74 @@
<html>
<head>
- <meta name="description" content="Lua Lanes - multithreading in Lua" />
- <meta name="keywords" content="Lua, Library, Multithreading, Threads, Rocks" />
+ <meta name="description" content="Lua Lanes - multithreading in Lua" />
+ <meta name="keywords" content="Lua, Library, Multithreading, Threads, Rocks" />
- <title>Lua Lanes - multithreading in Lua</title>
+ <title>Lua Lanes - multithreading in Lua</title>
</head>
<body>
-<div class="header">
-<hr />
-
-<center>
-<table summary="Lua logo">
- <tbody>
- <tr>
- <td align="center">
- <a href="http://www.lua.org">
- <img src="multi.png" alt="Lua" align="middle" border="0" height="120" width="128" />
- <img src="multi.png" alt="Lua" align="middle" border="0" height="120" width="128" />
- <img src="multi.png" alt="Lua" align="middle" border="0" height="120" width="128" />
- <img src="multi.png" alt="Lua" align="middle" border="0" height="120" width="128" />
- <img src="multi.png" alt="Lua" align="middle" border="0" height="120" width="128" />
- </a></td>
- </tr>
- <tr>
- <td align="center" valign="top"><h1>Lua Lanes - multithreading in Lua</h1>
- </td>
- </tr>
- </tbody>
-</table>
-<p class="bar">
- <a href="#description">Description</a> ·
- <a href="#systems">Supported systems</a> ·
- <a href="#installing">Building and Installing</a>
-</p><p class="bar">
- <a href="#creation">Creation</a> ·
- <a href="#status">Status</a> ·
- <a href="#results">Results and errors</a>
-</p><p class="bar">
- <a href="#cancelling">Cancelling</a> ·
- <a href="#finalizers">Finalizers</a> ·
- <a href="#lindas">Lindas</a> ·
- <a href="#timers">Timers</a> ·
- <a href="#locks">Locks etc.</a>
-</p><p class="bar">
- <a href="#other">Other issues</a> ·
- <a href="#changes">Change log</a>
- <!-- ... -->
-
-<p><br/><font size="-1"><i>Copyright © 2007-12 Asko Kauppi, Benoit Germain. All rights reserved.</i>
- <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.
- </p><p>This document was revised on 10-Sep-12, and applies to version 3.3.0
-</font></p>
-
-</center>
+<div class="header">
+ <hr/>
+
+ <center>
+ <table summary="Lua logo"><tbody>
+ <tr>
+ <td align="center">
+ <a href="http://www.lua.org">
+ <img src="multi.png" alt="Lua" align="middle" border="0" height="120" width="128" />
+ <img src="multi.png" alt="Lua" align="middle" border="0" height="120" width="128" />
+ <img src="multi.png" alt="Lua" align="middle" border="0" height="120" width="128" />
+ <img src="multi.png" alt="Lua" align="middle" border="0" height="120" width="128" />
+ <img src="multi.png" alt="Lua" align="middle" border="0" height="120" width="128" />
+ </a>
+ </td>
+ </tr>
+ <tr>
+ <td align="center" valign="top"><h1>Lua Lanes - multithreading in Lua</h1></td>
+ </tr>
+ </tbody></table>
+
+ <p class="bar">
+ <a href="#description">Description</a> ·
+ <a href="#systems">Supported systems</a> ·
+ <a href="#installing">Building and Installing</a>
+ </p>
+
+ <p class="bar">
+ <a href="#creation">Creation</a> ·
+ <a href="#status">Status</a> ·
+ <a href="#results">Results and errors</a>
+ </p>
+
+ <p class="bar">
+ <a href="#cancelling">Cancelling</a> ·
+ <a href="#finalizers">Finalizers</a> ·
+ <a href="#lindas">Lindas</a> ·
+ <a href="#timers">Timers</a> ·
+ <a href="#locks">Locks etc.</a>
+ </p>
+
+ <p class="bar">
+ <a href="#other">Other issues</a> ·
+ <a href="#changes">Change log</a>
+ </p>
+ <!-- ... -->
+
+ <font size="-1">
+ <p>
+ <br>
+ <i>Copyright © 2007-12 Asko Kauppi, Benoit Germain. All rights reserved.</i>
+ <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.
+ </p>
+
+ <p>
+ This document was revised on 25-Sep-12, and applies to version <tt>3.4.0</tt>.
+ </p>
+ </font>
+ </center>
</div>
@@ -67,50 +80,40 @@
<hr/>
<h2 id="description">Description</h2>
-<p>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.
-</p><p>
- 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.
-</p><p>
+<p>
+ 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.
+</p>
+<p>
+ 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.
+</p>
+<p>
Starting with version 3.1.6, Lanes should build and run identically with either Lua 5.1 or Lua 5.2.
-</p><p>
+</p>
+<p>
See <A HREF="comparison.html">comparison</A> of Lua Lanes with other Lua multithreading solutions.
-</p><p>
- <h3>Features:</h3>
-
- <ul>
- <li>Lanes have separated data, by default. Shared data is possible with Linda objects.
- </li>
- <li>Communications is separate of threads, using Linda objects.
- </li>
- <li>Data passing uses fast inter-state copies (no serialization required)</li>
- </li>
- <li>"Deep userdata" concept, for sharing userdata over multiple lanes
- </li>
- <li>Millisecond level timers, integrated with the Linda system.
- </li>
- <li>Threads can be given priorities -2..+2 (default is 0).
- </li>
- <li>Lanes are cancellable, with proper cleanup.
- </li>
- <li>No application level locking - ever!
- </li>
- </ul>
-
-
-<h3>Limitations:</h3>
-
- <ul><li>coroutines are not passed between states
- </li>
- <li>sharing full userdata between states needs special C side
- preparations (-> <A HREF="#deep_userdata">deep userdata</A>)
- </li>
- <li>network level parallelism not included
- </li>
- </ul>
+</p>
+<p>
+ <h3>Features:</h3>
+
+ <ul>
+ <li>Lanes have separated data, by default. Shared data is possible with Linda objects.</li>
+ <li>Communications is separate of threads, using Linda objects.</li>
+ <li>Data passing uses fast inter-state copies (no serialization required).</li>
+ <li>"Deep userdata" concept, for sharing userdata over multiple lanes.</li>
+ <li>Millisecond level timers, integrated with the Linda system.</li>
+ <li>Threads can be given priorities -2..+2 (default is 0).</li>
+ <li>Lanes are cancellable, with proper cleanup.</li>
+ <li>No Lua-side application level locking - ever!</li>
+ </ul>
+
+
+ <h3 id="limitations">Limitations:</h3>
+
+ <ul>
+ <li>Coroutines are not passed between states.</li>
+ <li>Sharing full userdata between states needs special C side preparations (-> <A HREF="#deep_userdata">deep userdata</A>).</li>
+ <li>Network level parallelism not included.</li>
+ </ul>
</p>
@@ -118,23 +121,24 @@
<hr/>
<h2 id="systems">Supported systems</h2>
-<p>Lua Lanes supports the following operating systems:
+<p>
+ Lua Lanes supports the following operating systems:
- <ul>
- <li>Mac OS X PowerPC / Intel (10.4 and later)</li>
- <li>Linux x86</li>
- <li>Windows 2000/XP and later <font size="-1">(MinGW or Visual C++ 2005/2008)</font></li>
+ <ul>
+ <li>Mac OS X PowerPC / Intel (10.4 and later)</li>
+ <li>Linux x86</li>
+ <li>Windows 2000/XP and later <font size="-1">(MinGW or Visual C++ 2005/2008)</font></li>
<!--
Other OS'es here once people help test them. (and the tester's name)
Win64, BSD, Linux x64, Linux embedded, QNX, Solaris, ...
-->
- </ul>
+ </ul>
- <p>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,
- requiring OS specific tweaks and guessing undocumented behaviour. Other features should be portable to any modern platform.
- </p>
+</p>
+<p>
+ 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,
+ requiring OS specific tweaks and guessing undocumented behaviour. Other features should be portable to any modern platform.
</p>
@@ -142,258 +146,373 @@
<hr/>
<h2 id="installing">Building and Installing</h2>
-<p>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.
+<p>
+ 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.
</p>
-<p>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).
-
-Or use <A HREF="http://www.luarocks.org" TARGET="_blank">Lua Rocks</A> package management.
+<p>
+ 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).
+ Or use <A HREF="http://www.luarocks.org" TARGET="_blank">Lua Rocks</A> package management.
</p>
<pre>
- > luarocks search lanes
- ... output listing Lua Lanes is there ...
+ > luarocks search lanes
+ ... output listing Lua Lanes is there ...
- > luarocks install lanes
- ... output ...
+ > luarocks install lanes
+ ... output ...
</pre>
<!-- launching +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<hr/>
- <h2 id="initialization">Initialization</h2>
-
- <p>
- The following sample shows how to initialize the Lanes module.
- </p>
-
- <table border="1" bgcolor="#FFFFE0" width="500">
- <tr>
- <td>
- <pre>
- local lanes = require "lanes".configure()
- </pre>
- </table>
-
- <p>
- 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.
- 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.
- At the same time, <tt>configure()</tt> itself will be replaced by another function that
- raises an error if called again with differing arguments.
- </p>
-
- <p>
- <table border="1" bgcolor="#E0E0FF" cellpadding="10">
- <tr>
- <td>
- <code>
- lanes.configure( [opt_tbl])
- </code>
- </table>
- </p>
- <p>
- <tt>lanes.configure</tt> accepts an optional options table as sole argument.
- <table>
- <tr valign=top><td width=40></td><td>
- <code>.nb_keepers</code> <br/><nobr>N</nobr></td><td width=40></td>
- <td>
- Controls the number of keeper states used internally by lindas to transfer data between lanes. (see below). Default is <tt>1</tt>.
- </td></tr>
-
- <tr valign=top><td/><td>
- <code>.with_timers</code> <br/>nil/false/anything</td><td/>
- <td>
- 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).
- Any other value (including <tt>nil</tt>), starts the timer service. Default is <tt>true</tt>.
- </td></tr>
-
- <tr valign="top">
- <td/>
- <td>
- <code>.on_create_state</code> <br/>C function/nil
- </td><td/>
- <td>
- 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>.
- </td>
- </tr>
-
- <tr valign=top><td width=40></td><td>
- <code>.shutdown_timeout</code> <br/><nobr>N</nobr></td><td width=40></td>
- <td>
- (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>.
- </td></tr>
- </table>
-<h2 id="creation">Creation</h2>
+<h2 id="initialization">Initialization</h2>
-<p>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.
+<p>
+ The following sample shows how to initialize the Lanes module.
</p>
-<table border=1 bgcolor="#FFFFE0" width=500><tr><td>
-<pre>
- local lanes = require "lanes"
- lanes.configure()
+<table border="1" bgcolor="#FFFFE0" cellpadding="10" style="width:50%">
+ <tr>
+ <td>
+ <pre> local lanes = require "lanes".configure()</pre>
+ </td>
+ </tr>
+</table>
- f= lanes.gen( function(n) return 2*n end )
- a= f(1)
- b= f(2)
+<p>
+ 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.
+</p>
+<p>
+ 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.
+</p>
+<p>
+ At the same time, <tt>configure()</tt> itself will be replaced by another function that raises an error if called again with differing arguments.
+</p>
- print( a[1], b[1] ) -- 2 4
-</pre>
-</table>
+<p>
+ <table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%">
+ <tr>
+ <td>
+ <pre> lanes.configure( [opt_tbl])</pre>
+ </td>
+ </tr>
+ </table>
+</p>
<p>
-<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td>
- <code>func= lanes.gen( [libs_str | opt_tbl [, ...],] lane_func )
- <br/><br/>
- lane_h= func( ... )</code>
+ <tt>lanes.configure</tt> accepts an optional options table as sole argument.
+ <table border="1" cellpadding="10" style="width:100%">
+ <tr>
+ <th style="width:15%">name</th>
+ <th style="width:15%">value</th>
+ <th style="width:70%">definition</th>
+ </tr>
+ <tr valign=top>
+ <td>
+ <code>.nb_keepers</code>
+ </td>
+ <td>integer >= 1</td>
+ <td>
+ 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>.
+ </td>
+ </tr>
+
+ <tr valign=top>
+ <td>
+ <code>.with_timers</code>
+ </td>
+ <td>
+ <tt>nil</tt>/<tt>false</tt>/anything
+ </td>
+ <td>
+ 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).
+ Any other non-<tt>nil</tt> value starts the timer service. Default is <tt>true</tt>.
+ </td>
+ </tr>
+
+ <tr valign=top>
+ <td>
+ <code>.on_create_state</code>
+ </td>
+ <td>
+ C function/<tt>nil</tt>
+ </td>
+ <td>
+ 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>.
+ </td>
+ </tr>
+
+ <tr valign=top>
+ <td>
+ <code>.shutdown_timeout</code> <br/>
+ </td>
+ <td>
+ number >= 0
+ </td>
+ <td>
+ (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>.
+ </td>
+ </tr>
+ </table>
+</p>
+
+<hr/>
+<h2 id="creation">Creation</h2>
+
+<p>
+ 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.
+</p>
+
+<table border=1 bgcolor="#FFFFE0" cellpadding="10" style="width:50%">
+ <tr>
+ <td>
+ <pre> local lanes = require "lanes".configure()</pre>
+ <br/>
+ <pre> f = lanes.gen( function( n) return 2 * n end)</pre>
+ <pre> a = f( 1)</pre>
+ <pre> b = f( 2)</pre>
+ <br/>
+ <pre> print( a[1], b[1] ) -- 2 4</pre>
+ </td>
+ </tr>
</table>
+<br>
+<table border=1 bgcolor="#E0E0FF" cellpadding="10" style="width:50%">
+ <tr>
+ <td>
+ <pre> func = lanes.gen( [libs_str | opt_tbl [, ...],] lane_func)</pre>
+ <pre> lane_h = func( ...)</pre>
+ </td>
+ </tr>
+</table>
+
+<p>
+ 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.
+ <br/>
+ 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.
</p>
+
<p>
- 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.
- 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 lua_dump, used internally to transfer functions to the lane.
-<!--
+ 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.
</p>
-<p>This prepares <tt>lane_func</tt> to be called in parallel. It does not yet start
-anything, but merely returns a <i>generator function</i> that can be called
-any number of times, with varying parameters. Each call will spawn a new lane.
--->
-</p><p>
-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.
-</p><p>
- <code>libs_str</code> defines the standard libraries made available to the
- new Lua state:
- <table>
- <tr><td width=40></td><td>(nothing)</td><td width=40></td><td>no standard libraries (default)</td></tr>
- <tr><td/>
- <td><tt>"base"</tt> or <tt>""</tt></td><td/>
- <td>root level names, <tt>print</tt>, <tt>assert</tt>, <tt>unpack</tt> etc.</td>
- </tr>
- <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>
- <tr><td/><td><tt>"debug"</tt></td><td/><td><tt>debug.*</tt> namespace</td></tr>
- <tr><td/><td><tt>"io"</tt></td><td/><td><tt>io.*</tt> namespace</td></tr>
- <tr><td/><td><tt>"math"</tt></td><td/><td><tt>math.*</tt> namespace</td></tr>
- <tr><td/><td><tt>"os"</tt></td><td/><td><tt>os.*</tt> namespace</td></tr>
- <tr><td/><td><tt>"package"</tt></td><td/><td><tt>package.*</tt> namespace and <tt>require</tt></td></tr>
- <tr><td/><td><tt>"string"</tt></td><td/><td><tt>string.*</tt> namespace</td></tr>
- <tr><td/><td><tt>"table"</tt></td><td/><td><tt>table.*</tt> namespace</td></tr>
- <br/>
- <tr><td/><td><tt>"*"</tt></td><td/><td>all standard libraries (including those specific to LuaJIT and not listed above)</td></tr>
- </table>
-
-</p><p>
- Initializing the standard libs takes a bit of time at each lane invocation.
- This is the main reason why "no libraries" is the default.
-</p><p>
-
- <code>opt_tbl</code> is a collection of named options to control the way
- lanes are run:
-</p><p>
- <table>
- <tr valign=top><td width=40></td><td>
- <code>.cancelstep</code> <br/><nobr>N / true</nobr></td>
- <td width=40></td><td>
- 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).
- It is also possible to manually test for cancel requests with <tt>cancel_test()</tt>.
- </td></tr>
-
- <tr valign=top><td/><td>
- <code>.globals</code> <br/>globals_tbl</td><td/>
- <td>
- Sets the globals table for the launched threads. This can be used for giving
- 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.
- <br>
- The global values of different lanes are in no manner connected;
- modifying one will only affect the particular lane.
- </td></tr>
-
- <tr valign="top">
- <td/>
- <td>
- <code>.required</code> <br/>modules_tbl
- </td><td/>
- <td>
- Lists modules that have to be required in order to be able to trasnfer
- 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 searched
- in lookup tables. 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.
- </td>
- </tr>
-
- <tr valign=top><td width=40><td>
- <code>.priority</code> <br/><nobr>-2..+2</nobr></td><td/>
- <td>The priority of lanes generated. -2 is lowest, +2 is highest.
- <br>
- Implementation and dependability of priorities varies
- by platform. Especially Linux kernel 2.6 is not supporting priorities in user mode.
- </td></tr>
-
- <tr valign="top">
- <td width="40">
- <td>
- <code>.package</code><br/>
- </td>
- <td><td/>
- <code>package</code> contents overrides, if needed.
- Specifying it when <code>libs_str</code> doesn't cause the <code>package</code> library to be loaded will generate an error.
- 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.
- <br>
- </td>
- </tr>
- </table>
- <p>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).
-</p>
- <p>
+
+<p>
+ <code>libs_str</code> defines the standard libraries made available to the new Lua state:
+ <table style="width:100%">
+ <tr>
+ <td style="width:5%"></td>
+ <td>(nothing)</td>
+ <td style="width:5%"></td>
+ <td>no standard libraries (default)</td>
+ </tr>
+ <tr>
+ <td/>
+ <td><tt>"base"</tt> or <tt>""</tt>
+ </td>
+ <td/>
+ <td>
+ root level names, <tt>print</tt>, <tt>assert</tt>, <tt>unpack</tt> etc.
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ <tt>"coroutine"</tt>
+ </td>
+ <td/>
+ <td>
+ <tt>coroutine.*</tt> namespace (part of base in Lua 5.1 and 5.2)
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ <tt>"debug"</tt>
+ </td>
+ <td/>
+ <td>
+ <tt>debug.*</tt> namespace
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ <tt>"io"</tt>
+ </td>
+ <td/>
+ <td>
+ <tt>io.*</tt> namespace
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ <tt>"math"</tt>
+ </td>
+ <td/>
+ <td>
+ <tt>math.*</tt> namespace
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ <tt>"os"</tt>
+ </td>
+ <td/>
+ <td>
+ <tt>os.*</tt> namespace
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ <tt>"package"</tt>
+ </td>
+ <td/>
+ <td>
+ <tt>package.*</tt> namespace and <tt>require</tt>
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ <tt>"string"</tt>
+ </td>
+ <td/>
+ <td>
+ <tt>string.*</tt> namespace
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ <tt>"table"</tt>
+ </td>
+ <td/>
+ <td>
+ <tt>table.*</tt> namespace
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ <tt>"*"</tt>
+ </td>
+ <td/>
+ <td>
+ all standard libraries (including those specific to LuaJIT and not listed above)
+ </td>
+ </tr>
+ </table>
+</p>
+
+<p>
+ Initializing the standard libs takes a bit of time at each lane invocation. This is the main reason why "no libraries" is the default.
+</p>
+
+<p>
+ <code>opt_tbl</code> is a collection of named options to control the way lanes are run:
+</p>
+
+<p>
+
+ <table border="1" cellpadding="10" style="width:100%">
+ <tr>
+ <th style="width:15%">name</th>
+ <th style="width:15%">value</th>
+ <th style="width:70%">definition</th>
+ </tr>
+ <tr valign=top>
+ <td>
+ <code>.cancelstep</code>
+ </td>
+ <td>integer >= 1/<tt>true</tt></td>
+ <td>
+ 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).
+ It is also possible to manually test for cancel requests with <tt>cancel_test()</tt>.
+ </td>
+ </tr>
+ <tr valign=top>
+ <td>
+ <code>.globals</code>
+ </td>
+ <td>table</td>
+ <td>
+ 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.
+ <br/>
+ The global values of different lanes are in no manner connected; modifying one will only affect the particular lane.
+ </td>
+ </tr>
+ <tr id=".required" valign=top>
+ <td>
+ <code>.required</code>
+ </td>
+ <td>table</td>
+ <td>
+ 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>.
+ 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.
+ 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.
+ 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).
+ </td>
+ </tr>
+ <tr valign=top>
+ <td>
+ <code>.priority</code>
+ </td>
+ <td> integer -2..+2</td>
+ <td>
+ The priority of lanes generated. -2 is lowest, +2 is highest.
+ <br>
+ Implementation and dependability of priorities varies by platform. Especially Linux kernel 2.6 is not supporting priorities in user mode.
+ </td>
+ </tr>
+ <tr valign=top>
+ <td>
+ <code>.package</code>
+ </td>
+ <td> table</td>
+ <td>
+ Specifying it when <code>libs_str</code> doesn't cause the <code>package</code> library to be loaded will generate an error.
+ <br>
+ 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.
+ </td>
+ </tr>
+ </table>
+
+<p>
+ 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).
+</p>
+
+<p>
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.
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:
-<table border="1" bgcolor="#E0E0FF" cellpadding="10">
- <tr>
- <td>
- <code>
- "type", "name" = lanes.nameof( o)
- </code>
- </table>
+
+ <table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%">
+ <tr>
+ <td>
+ <pre> "type", "name" = lanes.nameof( o)</pre>
+ </td>
+ </tr>
+ </table>
</p>
<h3>Free running lanes</h3>
<p>
-The lane handles are allowed to be 'let loose'; in other words you may execute
-a lane simply by:
+ The lane handles are allowed to be 'let loose'; in other words you may execute a lane simply by:
-<pre>
- lanes.gen( function() ... end ) ()
-</pre>
+ <table border="1" bgcolor="#FFFFE0" cellpadding="10" style="width:50%">
+ <tr>
+ <td>
+ <pre> lanes.gen( function( params) ... end ) ( ...)</pre>
+ </td>
+ </tr>
+ </table>
-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.
+ 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.
</p>
@@ -401,26 +520,95 @@ return values. Then again, such a lane does not even normally return.
<hr/>
<h2 id="status">Status</h2>
-<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td>
- <code>str= lane_h.status</code>
-</table>
+ <table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%">
+ <tr>
+ <td>
+ <pre> str = lane_h.status</pre>
+ </td>
+ </tr>
+ </table>
-<p>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>
+<p>
+ 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>
+
+ <table style="width:100%">
+ <tr>
+ <td style="width:5%"></td>
+ <td>
+ <tt>"pending"</tt>
+ </td>
+ <td style="width:5%"></td>
+ <td>
+ Not started yet. Shouldn't stay very long in that state.
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ <tt>
+ "running"
+ </tt>
+ </td>
+ <td/>
+ <td>
+ running, not suspended on a Linda call.
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ <tt>"waiting"</tt>
+ </td>
+ <td/>
+ <td>
+ waiting at a Linda <tt>:receive()</tt> or <tt>:send()</tt>
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ <tt>"done"</tt>
+ </td>
+ <td/>
+ <td>
+ finished executing (results are ready)
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ <tt>"error"</tt>
+ </td>
+ <td/>
+ <td>
+ met an error (reading results will propagate it)
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ <tt>"cancelled"</tt>
+ </td>
+ <td/>
+ <td>
+ received cancellation and finished itself.
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ <tt>"killed"</tt>
+ </td>
+ <td/>
+ <td>
+ was forcefully killed by <tt>lane_h:cancel()</tt> (since v3.3.0)
+ </td>
+ </tr>
+ </table>
+</p>
- <table>
- <tr><td width=40><td><tt>"pending"</tt></td><td>not started, yet</td></tr>
- <tr><td/><td><tt>"running"</tt></td><td>running</td></tr>
- <tr><td/><td><tt>"waiting"</tt></td><td>waiting at a Linda <tt>:receive()</tt> or <tt>:send()</tt></td></tr>
- <tr><td/><td><tt>"done"</tt></td><td>finished executing (results are ready)</td></tr>
- <tr><td/><td><tt>"error"</tt></td><td>met an error (reading results will propagate it)</td></tr>
- <tr><td/><td><tt>"cancelled"</tt></td><td>received cancellation and finished itself</td></tr>
- <tr><td/><td><tt>"killed"</tt></td><td>was forcefully killed by <tt>lane_h:cancel()</tt> (since v3.3.0)</td></tr>
- </table>
-</p><p>
- 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.
+<p>
+ 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.
</p>
@@ -428,101 +616,110 @@ member, providing one of these values: <sup>(<a href="#2">2</a></sup>
<hr/>
<h2 id="results">Results and errors</h2>
-<p>A lane can be waited upon by simply reading its results. This can be done
-in two ways.
-</p><p>
+<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
+ set_error_reporting( "basic"|"extended")
+</pre></td></tr></table>
-<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td>
- <code>[val]= lane_h[1]</code>
-</table>
<p>
-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.
-</p><p>
-If the lane ended in an error, it is propagated to master state at this place.
+ Sets the error reporting mode. "basic" is selected by default.
</p>
-<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td>
- <code>[...]|[nil,err,stack_tbl]= lane_h:join( [timeout_secs] )</code>
-</table>
<p>
-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.
-Unlike in reading the results in table fashion, errors are not propagated.
+ A lane can be waited upon by simply reading its results. This can be done in two ways.
+</p>
-</p><p>
+<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
+ [val]= lane_h[1]
+</pre></td></tr></table>
-<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td>
- <code>set_error_reporting("basic"|"extended")</code>
-</table>
-</p><p>
- Sets the error reporting mode. "basic" is selected by default.
-</p><p>
- <tt>stack_tbl</tt> is a table describing where the error was thrown.<br/>
- 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/>
-In "basic mode", <tt>stack_tbl</tt> is an array of "<filename>:<line>" strings. Use <tt>table.concat()</tt> to format it to your liking (or just ignore it).
-
-</p><p>
-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).
-</p><p>
-
-<table border=1 bgcolor="#FFFFE0" width=500><tr><td>
-<pre>
- require "lanes"
+<p>
+ 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.
+ <br>
+ If the lane ended in an error, it is propagated to master state at this place.
+</p>
- f= lanes.gen( function() error "!!!" end )
- a= f(1)
+<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
+ [...]|[nil,err,stack_tbl]= lane_h:join( [timeout_secs] )
+</pre></td></tr></table>
- --print( a[1] ) -- propagates error
+<p>
+ 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.
+ Unlike in reading the results in table fashion, errors are not propagated.
+</p>
- v,err= a:join() -- no propagation
- if v==nil then
- error( "'a' faced error"..tostring(err) ) -- manual propagation
- end
-</pre>
-</table>
+<p>
+ <tt>stack_tbl</tt> is a table describing where the error was thrown.
+ <br>
+ 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>).
+ <br>
+ In <tt>"basic mode"</tt>, <tt>stack_tbl</tt> is an array of "<filename>:<line>" strings. Use <tt>table.concat()</tt> to format it to your liking (or just ignore it).
+</p>
+
+<p>
+ 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).
+</p>
+
+<p>
+
+<table border=1 bgcolor="#FFFFE0" cellpadding="10" style="width:50%"><tr><td><pre>
+ require "lanes".configure()
+
+ f = lanes.gen( function() error "!!!" end)
+ a = f( 1)
+
+ --print( a[1]) -- propagates error
+
+ v, err = a:join() -- no propagation
+ if v == nil then
+ error( "'a' faced error"..tostring(err)) -- manual propagation
+ end
+</pre></td></tr></table>
<p>
-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).
+ 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).
</p>
+<table border=1 bgcolor="#FFFFE0" cellpadding="10" style="width:50%"><tr><td><pre>
+ require "lanes".configure()
+
+ local sync_linda = lanes.linda()
+ f = lanes.gen( function() dostuff() sync_linda:send( "done", true) end)
+ a = f()
+ b = f()
+ c = f()
+
+ sync_linda:receive( nil, sync_linda.batched, "done", 3) -- wait for 3 lanes to write something in "done" slot of sync_linda
+</pre></td></tr></table>
<!-- cancelling +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<hr/>
<h2 id="cancelling">Cancelling</h2>
-<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td>
- <code>bool[,reason]= lane_h:cancel( [timeout_secs=0.0,] [force_kill_bool=false] )</code>
- <br/>
- <br/>
- <code>
- bool= cancel_test()
- </code>
-</table>
+<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
+ bool[,reason] = lane_h:cancel( [timeout_secs=0.0,] [force_kill_bool = false] )
+</pre></td></tr></table>
+
+<p>
+ <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.
+ 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.
+</p>
-<p><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.
-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.
-</p><p>
-If the lane is still running 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.
+<p>
+ 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.
</p>
+
<p>
-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.
+ 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.
</p>
-<p>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. This means the execution of the lane will resume although the operation has
-not completed, to give the lane a chance to detect cancellation. The code should be able to handle this situation appropriately if required.
-It is also possible to manually test for cancel requests with <tt>cancel_test()</tt>.
+
+<p>
+ 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.
+ <br>
+ 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).
+ <br>
+ 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).
+ <br>
+ It is also possible to manually test for cancel requests with <tt>cancel_test()</tt>.
</p>
@@ -530,24 +727,24 @@ It is also possible to manually test for cancel requests with <tt>cancel_test()<
<hr/>
<h2 id="finalizers">Finalizers</h2>
-<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td>
- <code>set_finalizer( finalizer_func )</code>
- <br/><br/>
- <code>void= finalizer_func( [err, stack_tbl] )</code>
-</table>
+<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
+ set_finalizer( finalizer_func)
+
+ void = finalizer_func( [err, stack_tbl])
+</pre></td></tr></table>
-<p>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>
-that would get called when a certain block of instructions gets exited, whether
-through peaceful return or abrupt <tt>error</tt>.
+<p>
+ 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>
+ that would get called when a certain block of instructions gets exited, whether through peaceful return or abrupt <tt>error</tt>.
</p>
-<p>Since 2.0.3, Lanes prepares a function <tt>set_finalizer</tt> for doing this.
-Any functions given to it will be called in the lane Lua state, just prior to
-closing it. They are not called in any particular order.
+
+<p>
+ Since 2.0.3, Lanes registers a function <tt>set_finalizer</tt> in the lane's Lua state for doing this.
+ 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.
</p>
-<p>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.
+
+<p>
+ 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.
</p>
@@ -555,195 +752,181 @@ If one finalizer errors, the others may not get called.
<hr/>
<h2 id="lindas">Lindas</h2>
-<p>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. 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
-<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.
-</p><p>
-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.
-</p><p>
-
-<table border=1 bgcolor="#FFFFE0" width=500><tr><td>
-<pre>
- require "lanes"
-
- local linda= lanes.linda()
-
- local function loop( max )
- for i=1,max do
- print( "sending: "..i )
- linda:send( "x", i ) -- linda as upvalue
- end
- end
-
- a= lanes.gen("",loop)( 10000 )
-
- while true do
- local val= linda:receive( 3.0, "x" ) -- timeout in seconds
- if val==nil then
- print( "timed out" )
- break
- end
- print( "received: "..val )
- end
-</pre>
-</table>
+<p>
+ 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.
+ 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
+ <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.
+</p>
+<p>
+ 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.
</p>
-<p>Characteristics of the Lanes implementation of Lindas are:
-
-<ul>
- <li>keys can be of boolean, number, string or light userdata type
- </li>
- <li>values can be any type supported by inter-state copying (same limits
- as for function parameters and upvalues)
- </li>
- <li>consuming method is <tt>:receive</tt> (not in)
- </li>
- <li>non-consuming method is <tt>:get</tt> (not rd)
- </li>
- <li>two producer-side methods: <tt>:send</tt> and <tt>:set</tt> (not out)
- </li>
- <li><tt>send</tt> allows for sending multiple values -atomically- to a
- given key
- </li>
- <li><tt>receive</tt> can wait for multiple keys at once
- </li>
- <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>
- <li>individual keys' queue length can be limited, balancing speed differences
- in a producer/consumer scenario (making <tt>:send</tt> wait)
- </li>
-</ul>
+
+<table border="1" bgcolor="#FFFFE0" cellpadding="10" style="width:50%"><tr><td><pre>
+ require "lanes".configure()
+
+ local linda = lanes.linda()
+
+ local function loop( max)
+ for i = 1, max do
+ print( "sending: " .. i)
+ linda:send( "x", i) -- linda as upvalue
+ end
+ end
+
+ a = lanes.gen( "", loop)( 10000)
+
+ while true do
+ local key, val = linda:receive( 3.0, "x") -- timeout in seconds
+ if val == nil then
+ print( "timed out")
+ break
+ end
+ print( "received: " .. val)
+ end
+</pre></td></tr></table>
+
+<p>
+ Characteristics of the Lanes implementation of Lindas are:
+
+ <ul>
+ <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>
+ <li>values can be any type supported by inter-state copying (same <a href="#limitations">limits</a> as for function parameters and upvalues).</li>
+ <li>consuming method is <tt>:receive</tt> (not in).</li>
+ <li>non-consuming method is <tt>:get</tt> (not rd).</li>
+ <li>two producer-side methods: <tt>:send</tt> and <tt>:set</tt> (not out).</li>
+ <li><tt>send</tt> allows for sending multiple values -atomically- to a given key.</li>
+ <li><tt>receive</tt> can wait for multiple keys at once.</li>
+ <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>
+ <li>individual keys' queue length can be limited, balancing speed differences in a producer/consumer scenario (making <tt>:send</tt> wait).</li>
+ </ul>
+</p>
+
+<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
+ h = lanes.linda( [opt_name])
+
+ bool = h:send( [timeout_secs,] key, ... )
+
+ [key, val] = h:receive( [timeout_secs,] key [, ...])
+
+ [key, val [, ...]] = h:receive( timeout, h.batched, key, n_uint_min[, n_uint_max])
+
+ void = h:limit( key, n_uint)
+</pre></td></tr></table>
+
+<p>
+ 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.
</p>
<p>
-<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td>
- <code>h= lanes.linda( [opt_name])</code>
- <br/><br/>
- <code>bool= h:send( [timeout_secs,] key, ... )</code>
- <br/>
- <code>[val, key]= h:receive( [timeout_secs,] key [, ...] )</code>
- <br/><br/>
- <code>= h:limit( key, n_uint )</code>
-</table>
+ 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.
+</p>
-<p>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.
-</p><p>
-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.
-</p><p>
-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.
-</p>
-<p><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.
-</p><p>
-Equally, <tt>receive</tt> returns a value and the key that provided the value,
-or nothing for timeout. Note that <tt>nil</tt>s can be sent and received;
-the <tt>key</tt> value will tell it apart from a timeout.
-</p><p>
-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. Atomicity avoids the producers from garbling each others
-messages, which could happen if the units were sent individually.
-</p><p>
-
-When receiving from multiple slots, the keys are checked in order, which can
-be used for making priority queues.
-</p><p>
-
-<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td>
- <code>linda_h:set( key, [val] )</code>
- <br/>
- <code>[val]= linda_h:get( key )</code>
-</table>
+<p>
+ 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.
+</p>
-</p><p>
-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.
-</p><p>
-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.
-</p>
- <p>
-
- <table border="1" bgcolor="#E0E0FF" cellpadding="10">
- <tr>
- <td>
- <code>[val]= linda_h:count( [key[,...]])</code>
- </table>
-
- </p>
- <p>
- Returns some information about the contents of the linda.
- <br/>If no key is specified, and the linda is empty, returns nothing.
- <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
- of the exiting keys of the linda. This count can be 0 if the key has been used but is empty.
- <br/>If a single key is specified, returns the number of pending items, or nothing if the key is unknown.
- <br/>If more than one key is specified, return a table of key/count pairs for the known keys.
- </p>
+<p>
+ <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>.
+</p>
-<!--
<p>
-<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td>
- <code>lightuserdata= linda_h:deep()</code>
-</table>
+ 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.
+ <br>
+ 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.
+</p>
-<p>There is one more method that is not required in applications, but
-discussing it is good for a preview of how deep userdata works.
-</p><p>
-Because proxy objects (<tt>linda_h</tt>) are just pointers to the real, deep
-userdata, they cannot be used to identify a certain Linda from the others.
-The internal timer system needs to do this, and the <tt>:deep()</tt> method
-has been added for its use. It returns a light userdata pointing to the
-<i>actual</i> deep object, and thus can be used for seeing, which proxies actually
-mean the same underlying object. You might or might not need a similar system
-with your own deep userdata.
+<p>
+ 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.
+ Atomicity avoids the producers from garbling each others messages, which could happen if the units were sent individually.
+</p>
+
+<p>
+ When receiving from multiple slots, the keys are checked in order, which can be used for making priority queues.
+</p>
+
+<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
+ linda_h:set( key, [val])
+
+ [val] = linda_h:get( key )
+</pre></td></tr></table>
+
+<p>
+ 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.
+</p>
+
+<p>
+ 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.
+</p>
+
+<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
+ [val] = linda_h:count( [key[,...]])
+</pre></td></tr></table>
+
+<p>
+ Returns some information about the contents of the linda.
+ <br>
+ If no key is specified, and the linda is empty, returns nothing.
+ <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 of the exiting keys of the linda. This count can be 0 if the key has been used but is empty.
+ <br>
+ If a single key is specified, returns the number of pending items, or nothing if the key is unknown.
+ <br>
+ If more than one key is specified, return a table of key/count pairs for the known keys.
</p>
--->
+<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
+ [table] = linda_h:dump()
+</pre></td></tr></table>
+
+<p>
+ Returns a table describing the full contents of a linda, or <tt>nil</tt> if the linda wasn't used yet.
+</p>
<h3>Granularity of using Lindas</h3>
-<p>A single Linda object provides an infinite number of slots, so why would
-you want to use several?
-</p><p>There are some important reasons:
-
-<ul>
- <li>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
- for the other. This keeps your code clear and readable. You can pass
- multiple Linda handles to a lane with practically no added cost.
- </li>
-
- <li>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.
- </li>
-
- <li>Performance. Changing any slot in a Linda causes all pending threads
- for that Linda to be momentarily awakened (at least in the C level).
- 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.
- </li>
-</ul>
+<p>
+ 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.
+ <br>
+ 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.
+ <br>
+ 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.
+ <br>
+ 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.
+ <br>
+ 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.
+ <br>
+ If the thread is woken but the condition is not yet fulfilled, it goes back to sleep, until the timeout expires.
+ <br>
+ 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.
+</p>
+
+<p>
+ A single Linda object provides an infinite number of slots, so why would you want to use several?
+</p>
+
+<p>
+ There are some important reasons:
+ <ul>
+ <li>
+ 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
+ for the other. This keeps your code clear and readable. You can pass multiple Linda handles to a lane with practically no added cost.
+ </li>
+
+ <li>
+ 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.
+ </li>
+
+ <li>
+ Performance. Changing any slot in a Linda causes all pending threads for that Linda to be momentarily awakened (at least in the C level).
+ 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.
+ </li>
+ </ul>
+
+On 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.
+</p>
-On 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.
-</p><p>
+<p>
<font size="-1">Actually, you can. Make separate lanes to wait each, and then multiplex those
events to a common Linda, but... :).</font>
</p>
@@ -753,77 +936,66 @@ events to a common Linda, but... :).</font>
<hr/>
<h2 id="timers">Timers</h2>
-<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td>
- <code>= lanes.timer( linda_h, key, date_tbl|first_secs [,period_secs] )</code>
-</table>
+<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
+ void = lanes.timer( linda_h, key, date_tbl|first_secs [,period_secs])
+</pre></td></tr></table>
<p>
- 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>.
- </p>
-<p>
-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.
-</p><p>
-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.
-</p><p>
-A timer can be stopped simply with <tt>first_secs=0|nil</tt> and no period.
-</p><p>
-
-<table border=1 bgcolor="#FFFFE0" width=500><tr><td>
-<pre>
- local lanes = require "lanes"
- lanes.configure( 1)
+ 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>.
+</p>
+
+<p>
+ 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.
+</p>
+
+<p>
+ 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.
+</p>
- local linda= lanes.linda()
+<p>
+ A timer can be stopped simply with <tt>first_secs=0|nil</tt> and no period.
+</p>
- -- First timer once a second, not synchronized to wall clock
- --
- lanes.timer( linda, "sec", 1, 1 )
+<table border="1" bgcolor="#FFFFE0" cellpadding="10" style="width:50%"><tr><td><pre>
+ local lanes = require "lanes"
+ lanes.configure()
- -- Timer to a future event (next even minute); wall clock synchronized
- --
- local t= os.date( "*t", os.time()+60 ) -- now + 1min
- t.sec= 0
+ local linda = lanes.linda()
- lanes.timer( linda, "min", t, 60 ) -- reoccur every minute (sharp)
+ -- First timer once a second, not synchronized to wall clock
+ --
+ lanes.timer( linda, "sec", 1, 1)
- while true do
- local v,key= linda:receive( "sec", "min" )
- print( "Timer "..key..": "..v )
- end
-</pre>
-</table>
+ -- Timer to a future event (next even minute); wall clock synchronized
+ --
+ local t = os.date( "*t", os.time() + 60) -- now + 1min
+ t.sec = 0
+
+ lanes.timer( linda, "min", t, 60) -- reoccur every minute (sharp)
+
+ while true do
+ local key, v = linda:receive( "sec", "min")
+ print( "Timer "..key..": "..v)
+ end
+</pre></td></tr></table>
+
+<p>
+ 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.
+</p>
-</p><p>
-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.
-</p><p>
<table>
- <tr><td valign=top><nobr><i>Design note:</i></nobr> </td>
- <td>
-<font size="-1">
-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. 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. Even if
-a linda object and key was returned, that key couldn't be waited upon simultaneously
-with one's general linda events.
-The current system gives maximum capabilities with minimum API, and any smoothenings
-can easily be crafted in Lua at the application level.
-</font>
- </td>
- </tr>
+ <tr>
+ <td valign=top><i><nobr>Design note:</nobr></i></td>
+ <td>
+ <font size="-1">
+ 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.
+ 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.
+ Even if a linda object and key was returned, that key couldn't be waited upon simultaneously with one's general linda events.
+ The current system gives maximum capabilities with minimum API, and any smoothenings can easily be crafted in Lua at the application level.
+ </font>
+ </td>
+ </tr>
</table>
-</p>
<!-- locks +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
@@ -831,46 +1003,43 @@ can easily be crafted in Lua at the application level.
<h2 id="locks">Locks etc.</h2>
<p>
-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:
-</p><p>
+ 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:
+</p>
-<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td><pre>
- lock_func= lanes.genlock( linda_h, key [,N_uint=1] )
+<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
+ lock_func = lanes.genlock( linda_h, key [,N_uint=1])
- lock_func( M_uint ) -- acquire
- ..
- lock_func( -M_uint ) -- release
-</table>
-</p><p>
+ lock_func( M_uint ) -- acquire
+ ..
+ lock_func( -M_uint ) -- release
+</pre></td></tr></table>
-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).
-</p><p>
+<p>
+ 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).
+</p>
-Note: The locks generated are <u>not recursive</u>. That would need another
-kind of generator, which is currently not implemented.
-</p><p>
+<p>
+ Note: The locks generated are <u>not recursive</u>. That would need another kind of generator, which is currently not implemented.
+</p>
-Similar sugar exists for atomic counters:
-</p><p>
+<p>
+ Similar sugar exists for atomic counters:
+</p>
-<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td><pre>
- atomic_func= lanes.genatomic( linda_h, key [,initial_num=0.0] )
+<p>
- new_num= atomic_func( [diff_num=+1.0] )
-</table>
-</p><p>
+<table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
+ atomic_func = lanes.genatomic( linda_h, key [,initial_num=0.0])
-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.
-</p><p>
+ new_num = atomic_func( [diff_num=+1.0])
+</pre></td></tr></table>
-Note that the generated functions can be passed on to other lanes.
+<p>
+ 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.
+</p>
+
+<p>
+ Note that the generated functions can be passed on to other lanes.
</p>
@@ -880,209 +1049,218 @@ Note that the generated functions can be passed on to other lanes.
<h3>Limitations on data passing</h3>
-<p>Data passed between lanes (either as starting parameters, return values, upvalues or via Lindas) must conform to the following:
+<p>
+ Data passed between lanes (either as starting parameters, return values, upvalues or via Lindas) must conform to the following:
</p>
-<p><ul>
- <li>Booleans, numbers, strings, light userdata, Lua functions and tables of such can always be passed.
- </li>
- <li>Cyclic tables and/or duplicate references are allowed and reproduced appropriately,
- but only <u>within the same transmission</u>.
- <ul>
- <li>using the same source table in multiple Linda messages keeps no ties between the tables
- </li>
- </ul>
- </li>
- <li>Objects (tables with a metatable) are copyable between lanes.
- <ul>
- <li>metatables are assumed to be immutable; they are internally indexed and only copied once
- per each type of objects per lane
- </li>
- </ul>
- </li>
- <li>C functions (<tt>lua_CFunction</tt>) referring to <tt>LUA_ENVIRONINDEX</tt> or <tt>LUA_REGISTRYINDEX</tt> might not
- work right in the target
- <ul>
- <li>rather completely re-initialize a module with <tt>require</tt> in the target lane
- </li>
- </ul>
- </li>
- <li>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
- <ul>
- <li>in particular, lane handles cannot be passed between lanes
- </li>
- </ul>
- </li>
- <li>coroutines cannot be passed
- </li>
-</ul>
+
+<p>
+ <ul>
+ <li>Booleans, numbers, strings, light userdata, Lua functions and tables of such can always be passed.</li>
+ <li>
+ Cyclic tables and/or duplicate references are allowed and reproduced appropriately, but only <u>within the same transmission</u>.
+ <ul>
+ <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>
+ </ul>
+ </li>
+ <li>
+ Objects (tables with a metatable) are copyable between lanes.
+ <ul>
+ <li>Metatables are assumed to be immutable; they are internally indexed and only copied once per each type of objects per lane.</li>
+ </ul>
+ </li>
+ <li>
+ C functions (<tt>lua_CFunction</tt>) referring to <tt>LUA_ENVIRONINDEX</tt> or <tt>LUA_REGISTRYINDEX</tt> might not work right in the target
+ <ul>
+ <li>Rather completely re-initialize a module with <tt>require</tt> in the target lane.</li>
+ </ul>
+ </li>
+ <li>
+ 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
+ <ul>
+ <li>In particular, lane handles cannot be passed between lanes.</li>
+ </ul>
+ </li>
+ <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>
+ </ul>
+</p>
+
+
+<h3 id="function_notes">Notes about passing C functions</h3>
+
+<p>
+ Originally, a C function was copied from one Lua state to another as follows:
+</p>
+
+<table border="1" bgcolor="#FFFFE0" cellpadding="10" style="width:50%"><tr><td><pre>
+ // expects a C function on top of the source Lua stack
+ copy_func( lua_State *dest, lua_State* source)
+ {
+ // extract C function pointer from source
+ lua_CFunction func = lua_tocfunction( source, -1);
+ // transfer upvalues
+ int nup = trasnfer_upvalues( dest, source);
+ // dest Lua stack contains a copy of all upvalues
+ lua_pushcfunction( dest, func, nup);
+ }
+</pre></td></tr></table>
+
+<p>
+ 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.
+ <br>
+ Therefore, Lanes no longer transfers functions that way. Instead, functions are transfered as follows (more or less):
+</p>
+
+<table border="1" bgcolor="#FFFFE0" cellpadding="10" style="width:50%"><tr><td><pre>
+ // expects a C function on top of the source Lua stack
+ copy_func( lua_State *dest, lua_State* source)
+ {
+ // extract C function pointer from source
+ char const* funcname = lookup_func_name( source, -1);
+ // lookup a function bound to this name in the destination state, and push it on the stack
+ push_resolved_func( dest, funcname);
+ }
+</pre></td></tr></table>
+
+<p>
+ The devil lies in the details: what does "function lookup" mean?
+</p>
+
+<p>
+ 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.
+ <br>
+ 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.
+ <br>
+ 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.
+ <br>
+ 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).
+ <br>
+ 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.
+ <br>
+ 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).
+</p>
+
+<p>
+ There are two issues here:
+ <ul>
+ <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>
+ <li>
+ Nothing prevents a script to create other references to a C function. For example one could do
+ <table border="1" bgcolor="#FFFFE0" cellpadding="10" style="width:50%"><tr><td><pre>
+ string2 = string
+ </pre></td></tr></table>
+ 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.
+ 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.
+ 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>
+ 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>).
+ </li>
+ </ul>
+ 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.
+ 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.
+ 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.
</p>
<h3>Required of module makers</h3>
<p>
-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.
-</p><p>
-If it, however, also does one-time C side initializations, these
-should be covered into a one-time-only construct such as below.
-</p><p>
+ 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.
+</p>
-<table><tr><td width=40>
- <td bgcolor="#ffffe0">
-<pre>
- int luaopen_module( lua_State *L )
- {
- static char been_here; /* 0 by ANSI C */
-
- /* Calls to 'require' serialized by Lanes; this is safe.
- */
- if (!been_here) {
- been_here= 1;
- ... one time initializations ...
- }
-
- ... binding to Lua ...
- }
-</pre>
-</td></tr></table>
+<p>
+ If it, however, also does one-time C side initializations, these should be covered into a one-time-only construct such as below.
</p>
+<table border="1" bgcolor="#FFFFE0" cellpadding="10" style="width:50%"><tr><td><pre>
+ int luaopen_module( lua_State *L )
+ {
+ static char been_here; /* 0 by ANSI C */
+
+ // Calls to 'require' serialized by Lanes; this is safe.
+ if (!been_here)
+ {
+ been_here= 1;
+ ... one time initializations ...
+ }
+ ... binding to Lua ...
+ }
+</pre></td></tr></table>
+
<h3 id="shared_userdata">Deep userdata in your own apps</h3>
<p>
-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.
+ 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.
</p>
+
<ol>
- <li>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
- <table border="1" bgcolor="#E0E0FF" cellpadding="10">
- <tr>
- <td>
- <code>void idfunc( lua_State *L, char const * const which);</code>
- </table>
-<tt>which</tt> can be one of:
-<ul>
- <li>
- <tt>"new"</tt>: requests the creation of a new object, whose pointer is pushed on the stack
- as a light userdata.
- </li>
- <li>
- <tt>"delete"</tt>: receives this same pointer on the stack, and should cleanup the object.</li>
- <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>
- <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>
-</ul>
-Take a look at <tt>linda_id</tt> in <tt>lanes.c</tt>.
- </li>
- <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>
- <li>Accessing the deep userdata from your C code, use <tt>luaG_todeep()</tt>
- instead of the regular <tt>lua_touserdata()</tt>.
- </li>
+ <li>
+ 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
+ <table border="1" bgcolor="#E0E0FF" cellpadding="10" style="width:50%"><tr><td><pre>
+ void idfunc( lua_State *L, char const * const which);
+ </pre></td></tr></table>
+ <tt>which</tt> can be one of:
+ <ul>
+ <li><tt>"new"</tt>: requests the creation of a new object, whose pointer is pushed on the stack as a light userdata.</li>
+ <li><tt>"delete"</tt>: receives this same pointer on the stack, and should cleanup the object.</li>
+ <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>
+ <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>
+ </ul>
+ Take a look at <tt>linda_id</tt> in <tt>lanes.c</tt>.
+ </li>
+ <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>
+ <li>Accessing the deep userdata from your C code, use <tt>luaG_todeep()</tt> instead of the regular <tt>lua_touserdata()</tt>.</li>
</ol>
-<p>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.
+<p>
+ 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.
</p>
-<p><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.
+
+<p>
+ <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.
</p>
<h3>Lane handles don't travel</h3>
<p>
-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.
-</p><p>
-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.
+ 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.
+</p>
+
+<p>
+ 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.
</p>
<h3>Beware with print and file output</h3>
<p>
-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:
+ 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:
-<pre>
- A: print( 1, 2, 3, 4 )
- B: print( 'a', 'b', 'c', 'd' )
+<table border="1" bgcolor="#FFFFE0" cellpadding="10" style="width:50%"><tr><td><pre>
+ A: print( 1, 2, 3, 4 )
+ B: print( 'a', 'b', 'c', 'd' )
- 1 a b 2 3 c d 4
-</pre>
+ 1 a b 2 3 c d 4
+</pre></td></tr></table>
-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.
+ 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.
</p>
<h3 id="performance">Performance considerations</h3>
<p>
-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:
-</p><p>
-<ul>
- <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>
- <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>
- <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>
- <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>
- <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>
- <li>Lindas are hashed to a fixed number of "keeper states", which are a locking entity.
- 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 <tt>lanes.configure()</tt>).
- </li>
+ 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:
+</p>
+
+<p>
+ <ul>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
</ul>
</p>
@@ -1090,20 +1268,17 @@ Here are some things one should consider, if best performance is vital:
<h3 id="cancelling_cancel">Cancelling cancel</h3>
<p>
-Cancellation of lanes uses the Lua error mechanism with a special lightuserdata
-error sentinel.
-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. You should throw any
-lightuserdata error further.
-</p><p>
-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.
-</p><p>
-The sentinel is exposed as <tt>lanes.cancel_error</tt>, if you wish to use
-its actual value.
+ Cancellation of lanes uses the Lua error mechanism with a special lightuserdata error sentinel.
+ 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.
+ You should throw any lightuserdata error further.
+</p>
+
+<p>
+ 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.
+</p>
+
+<p>
+ The sentinel is exposed as <tt>lanes.cancel_error</tt>, if you wish to use its actual value.
</p>
@@ -1113,21 +1288,20 @@ its actual value.
<h2 id="changes">Change log</h2>
<p>
- See CHANGES.
+ See CHANGES.
</p>
<!-- footnotes +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<hr/>
-<p>For feedback, questions and suggestions:
-<UL>
- <li><A HREF="http://github.com/LuaLanes/lanes">Lanes @ GitHub</A></li>
- <li><A HREF="mailto:bnt.germain@gmail.com">the maintainer</A></li>
- <li><A HREF="http://www.lua.org/lua-l.html">the lua mailing list</A></li>
-</UL>
+<p>
+ For feedback, questions and suggestions:
+ <ul>
+ <li><A HREF="http://github.com/LuaLanes/lanes">Lanes @ GitHub</A></li>
+ <li><A HREF="mailto:bnt.germain@gmail.com">the maintainer</A></li>
+ <li><A HREF="http://www.lua.org/lua-l.html">the lua mailing list</A></li>
+ </ul>
</p>
-<p><br/></p>
-
</body>
</html>
--
cgit v1.2.3-55-g6feb