summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBenoit Germain <bnt period germain arrobase gmail period com>2014-01-22 12:28:45 +0100
committerBenoit Germain <bnt period germain arrobase gmail period com>2014-01-22 12:28:45 +0100
commit8580d8ee6913a1fa5378dd6196feba86df1d6f44 (patch)
treeeb725706d0b7a99cf17ff9cb64ae6a9fd38a9c3f
parent2348fbb83afe70842a62cc9c033dd303f590bd80 (diff)
downloadlanes-8580d8ee6913a1fa5378dd6196feba86df1d6f44.tar.gz
lanes-8580d8ee6913a1fa5378dd6196feba86df1d6f44.tar.bz2
lanes-8580d8ee6913a1fa5378dd6196feba86df1d6f44.zip
new lane launcher option gc_cb
* bumped version to 3.8.2 * new lane launcher option gc_cb to set a callback that is invoked when a lane is garbage collected * Fix more invalid memory accesses when fetching the name of a joined lane with lanes:threads() (because its lua_State is closed)
-rw-r--r--index.html81
1 files changed, 45 insertions, 36 deletions
diff --git a/index.html b/index.html
index 7078b13..c662a14 100644
--- a/index.html
+++ b/index.html
@@ -63,14 +63,14 @@
63 63
64 <font size="-1"> 64 <font size="-1">
65 <p> 65 <p>
66 <br> 66 <br/>
67 <i>Copyright &copy; 2007-14 Asko Kauppi, Benoit Germain. All rights reserved.</i> 67 <i>Copyright &copy; 2007-14 Asko Kauppi, Benoit Germain. All rights reserved.</i>
68 <br> 68 <br/>
69 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 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.
70 </p> 70 </p>
71 71
72 <p> 72 <p>
73 This document was revised on 20-Jan-14, and applies to version <tt>3.8.1</tt>. 73 This document was revised on 22-Jan-14, and applies to version <tt>3.8.2</tt>.
74 </p> 74 </p>
75 </font> 75 </font>
76 </center> 76 </center>
@@ -386,7 +386,7 @@
386 386
387<p> 387<p>
388 (Since v3.5.0) Once Lanes is configured, one should register with Lanes the modules exporting functions that will be transferred either during lane generation or through <a href="#lindas">lindas</a>. 388 (Since v3.5.0) Once Lanes is configured, one should register with Lanes the modules exporting functions that will be transferred either during lane generation or through <a href="#lindas">lindas</a>.
389 <br> 389 <br/>
390 Use <tt>lanes.require()</tt> for this purpose. This will call the original <tt>require()</tt>, then add the result to the lookup databases. 390 Use <tt>lanes.require()</tt> for this purpose. This will call the original <tt>require()</tt>, then add the result to the lookup databases.
391</p> 391</p>
392 392
@@ -418,7 +418,7 @@
418 </td> 418 </td>
419 </tr> 419 </tr>
420</table> 420</table>
421<br> 421<br/>
422<table border=1 bgcolor="#E0E0FF" cellpadding="10" style="width:50%"> 422<table border=1 bgcolor="#E0E0FF" cellpadding="10" style="width:50%">
423 <tr> 423 <tr>
424 <td> 424 <td>
@@ -596,10 +596,19 @@
596 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. 596 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.
597 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. 597 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.
598 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). 598 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).
599 <br> 599 <br/>
600 ATTEMPTING TO TRANSFER A FUNCTION REGISTERED BY A MODULE NOT LISTED HERE WILL RAISE AN ERROR. 600 ATTEMPTING TO TRANSFER A FUNCTION REGISTERED BY A MODULE NOT LISTED HERE WILL RAISE AN ERROR.
601 </td> 601 </td>
602 </tr> 602 </tr>
603 <tr id="Tr1" valign=top>
604 <td>
605 <code>.gc_cb</code>
606 </td>
607 <td>function</td>
608 <td>
609 (Since version 3.8.2) Callback that gets invoked when the lane is garbage collected. The function receives two arguments (the lane name and a string, either <tt>"closed"</tt> or <tt>"selfdestruct"</tt>).
610 </td>
611 </tr>
603 <tr valign=top> 612 <tr valign=top>
604 <td> 613 <td>
605 <code>.priority</code> 614 <code>.priority</code>
@@ -608,9 +617,9 @@
608 <td> 617 <td>
609 The priority of lanes generated in the range -3..+3 (default is 0). 618 The priority of lanes generated in the range -3..+3 (default is 0).
610 These values are a mapping over the actual priority range of the underlying implementation. 619 These values are a mapping over the actual priority range of the underlying implementation.
611 <br> 620 <br/>
612 Implementation and dependability of priorities varies by platform. Especially Linux kernel 2.6 is not supporting priorities in user mode. 621 Implementation and dependability of priorities varies by platform. Especially Linux kernel 2.6 is not supporting priorities in user mode.
613 <br> 622 <br/>
614 A lane can also change its own thread priority dynamically with <a href="#priority"><tt>lanes.set_thread_priority()</tt></a>. 623 A lane can also change its own thread priority dynamically with <a href="#priority"><tt>lanes.set_thread_priority()</tt></a>.
615 </td> 624 </td>
616 </tr> 625 </tr>
@@ -621,9 +630,9 @@
621 <td> table</td> 630 <td> table</td>
622 <td> 631 <td>
623 Introduced at version 3.0. 632 Introduced at version 3.0.
624 <br> 633 <br/>
625 Specifying it when <code>libs_str</code> doesn't cause the <code>package</code> library to be loaded will generate an error. 634 Specifying it when <code>libs_str</code> doesn't cause the <code>package</code> library to be loaded will generate an error.
626 <br> 635 <br/>
627 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. 636 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.
628 </td> 637 </td>
629 </tr> 638 </tr>
@@ -678,7 +687,7 @@
678 </table> 687 </table>
679<p> 688<p>
680 Besides setting a default priority in the generator <a href="#generator_settings">settings</a>, each thread can change its own priority at will. This is also true for the main Lua state. 689 Besides setting a default priority in the generator <a href="#generator_settings">settings</a>, each thread can change its own priority at will. This is also true for the main Lua state.
681 <br> 690 <br/>
682 The priority must be in the range <tt>[-3,+3]</tt>. 691 The priority must be in the range <tt>[-3,+3]</tt>.
683</p> 692</p>
684 693
@@ -793,7 +802,7 @@
793 802
794<p> 803<p>
795 Only available if lane tracking feature is compiled (see <tt>HAVE_LANE_TRACKING</tt> in <tt>lanes.c</tt>) and <a href="#track_lanes"><tt>track_lanes</tt></a> is set. 804 Only available if lane tracking feature is compiled (see <tt>HAVE_LANE_TRACKING</tt> in <tt>lanes.c</tt>) and <a href="#track_lanes"><tt>track_lanes</tt></a> is set.
796 <br> 805 <br/>
797 Returns a table where keys are a lane's name and values are the lane's status. Returns <tt>nil</tt> if no lane is running. 806 Returns a table where keys are a lane's name and values are the lane's status. Returns <tt>nil</tt> if no lane is running.
798</p> 807</p>
799 808
@@ -820,7 +829,7 @@
820 829
821<p> 830<p>
822 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. 831 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.
823 <br> 832 <br/>
824 If the lane ended in an error, it is propagated to master state at this place. 833 If the lane ended in an error, it is propagated to master state at this place.
825</p> 834</p>
826 835
@@ -835,9 +844,9 @@
835 844
836<p> 845<p>
837 <tt>stack_tbl</tt> is a table describing where the error was thrown. 846 <tt>stack_tbl</tt> is a table describing where the error was thrown.
838 <br> 847 <br/>
839 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>). 848 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>).
840 <br> 849 <br/>
841 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). 850 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).
842</p> 851</p>
843 852
@@ -908,11 +917,11 @@
908 917
909<p> 918<p>
910 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. 919 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.
911 <br> 920 <br/>
912 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 <a href="#lindas">linda</a> with infinite timeout). 921 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 <a href="#lindas">linda</a> with infinite timeout).
913 <br> 922 <br/>
914 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). 923 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).
915 <br> 924 <br/>
916 It is also possible to manually test for cancel requests with <tt>cancel_test()</tt>. 925 It is also possible to manually test for cancel requests with <tt>cancel_test()</tt>.
917</p> 926</p>
918 927
@@ -1103,13 +1112,13 @@
1103 1112
1104<p> 1113<p>
1105 Returns some information about the contents of the linda. 1114 Returns some information about the contents of the linda.
1106 <br> 1115 <br/>
1107 If no key is specified, and the linda is empty, returns nothing. 1116 If no key is specified, and the linda is empty, returns nothing.
1108 <br> 1117 <br/>
1109 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. 1118 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.
1110 <br> 1119 <br/>
1111 If a single key is specified, returns the number of pending items, or nothing if the key is unknown. 1120 If a single key is specified, returns the number of pending items, or nothing if the key is unknown.
1112 <br> 1121 <br/>
1113 If more than one key is specified, return a table of key/count pairs for the known keys. 1122 If more than one key is specified, return a table of key/count pairs for the known keys.
1114</p> 1123</p>
1115 1124
@@ -1125,17 +1134,17 @@
1125 1134
1126<p> 1135<p>
1127 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. 1136 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.
1128 <br> 1137 <br/>
1129 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. 1138 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.
1130 <br> 1139 <br/>
1131 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. 1140 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.
1132 <br> 1141 <br/>
1133 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. 1142 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.
1134 <br> 1143 <br/>
1135 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. 1144 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.
1136 <br> 1145 <br/>
1137 If the thread is woken but the condition is not yet fulfilled, it goes back to sleep, until the timeout expires. 1146 If the thread is woken but the condition is not yet fulfilled, it goes back to sleep, until the timeout expires.
1138 <br> 1147 <br/>
1139 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. 1148 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.
1140</p> 1149</p>
1141 1150
@@ -1264,9 +1273,9 @@ events to a common Linda, but... :).</font>
1264 1273
1265<p> 1274<p>
1266 The generated function acquires M tokens 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). 1275 The generated function acquires M tokens 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).
1267 <br> 1276 <br/>
1268 When passsing <tt>"try"</tt> as second argument when acquiring, then <tt>lock_func</tt> operates on the linda with a timeout of 0 to emulate a TryLock() operation. If locking fails, <tt>lock_func</tt> returns <tt>false</tt>. <tt>"try"</tt> is ignored when releasing (as it it not expected to ever have to wait unless the acquisition/release pairs are not properly matched). 1277 When passsing <tt>"try"</tt> as second argument when acquiring, then <tt>lock_func</tt> operates on the linda with a timeout of 0 to emulate a TryLock() operation. If locking fails, <tt>lock_func</tt> returns <tt>false</tt>. <tt>"try"</tt> is ignored when releasing (as it it not expected to ever have to wait unless the acquisition/release pairs are not properly matched).
1269 <br> 1278 <br/>
1270 Upon successful lock/unlock, <tt>lock_func</tt> returns <tt>true</tt> (always the case when block-waiting for completion). 1279 Upon successful lock/unlock, <tt>lock_func</tt> returns <tt>true</tt> (always the case when block-waiting for completion).
1271</p> 1280</p>
1272 1281
@@ -1364,7 +1373,7 @@ events to a common Linda, but... :).</font>
1364 1373
1365<p> 1374<p>
1366 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 <tt>NULL</tt> for them. 1375 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 <tt>NULL</tt> for them.
1367 <br> 1376 <br/>
1368 Therefore, Lanes no longer transfers functions that way. Instead, functions are transfered as follows (more or less): 1377 Therefore, Lanes no longer transfers functions that way. Instead, functions are transfered as follows (more or less):
1369</p> 1378</p>
1370 1379
@@ -1385,15 +1394,15 @@ events to a common Linda, but... :).</font>
1385 1394
1386<p> 1395<p>
1387 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. 1396 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.
1388 <br> 1397 <br/>
1389 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. 1398 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.
1390 <br> 1399 <br/>
1391 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. 1400 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.
1392 <br> 1401 <br/>
1393 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 and lanes states). 1402 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 and lanes states).
1394 <br> 1403 <br/>
1395 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. 1404 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.
1396 <br> 1405 <br/>
1397 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 <tt>lua_CFunction</tt> pointer). 1406 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 <tt>lua_CFunction</tt> pointer).
1398</p> 1407</p>
1399 1408