* fixed potential crash at application shutdown when calling lua_close() on a killed thread's VM.

* exposed cancel_test() in the lanes to enable manual testing for cancellation requests. * removed kludgy {globals={threadName}} support, replaced with a new function set_debug_threadname().
author: Benoit Germain <bnt.germain@gmail.com> 2011-03-01 21:12:56 +0100
committer: Benoit Germain <bnt.germain@gmail.com> 2011-03-01 21:12:56 +0100
commit: e97adefde985e30fe31ffa036c74ffb0ce10ca26 (patch)
tree: 4465decc5f07e7399f9760d6302dbaf7163120d7 /docs
parent: 974aa4343cf900938b5d357d10798d91faf60f5a (diff)
download: lanes-e97adefde985e30fe31ffa036c74ffb0ce10ca26.tar.gz
lanes-e97adefde985e30fe31ffa036c74ffb0ce10ca26.tar.bz2
lanes-e97adefde985e30fe31ffa036c74ffb0ce10ca26.zip
1 files changed, 32 insertions, 40 deletions
diff --git a/docs/index.html b/docs/index.html
index 3d2ecf2..ba25515 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -56,7 +56,7 @@
 <p><br/><font size="-1"><i>Copyright &copy; 2007-11 Asko Kauppi. 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.
-    </p><p>This document was revised on 21-Feb-11, and applies to version 2.1.0.
+    </p><p>This document was revised on 1-Mar-11, and applies to version 2.1.0.
 </font></p>
 </center>
@@ -243,6 +243,7 @@ also in the new lanes.
    <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>
@@ -250,20 +251,21 @@ also in the new lanes.
    <td>
    Sets the globals table for the launched threads. This can be used for giving
    them constants.
-    </p><p>
+    <br>
    The global values of different lanes are in no manner connected;
-    modifying one will only affect the particular lane. Settings the variable 'threadName' in this table makes VS display the sent name instead of the normal thread name while debugging.
+    modifying one will only affect the particular lane.
    </td></tr>
    <tr valign=top><td width=40><td>
        <code>.priority</code> <br/><nobr>-2..+2</nobr></td>
        <td>The priority of lanes generated. -2 is lowest, +2 is highest.
-        <p>
+        <br>
    Implementation and dependability of priorities varies
    by platform. Especially Linux kernel 2.6 is not supporting priorities in user mode.
    </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>
 <h3>Free running lanes</h3>
@@ -374,10 +376,15 @@ that id over a Linda once that thread is done (as the last thing you do).
 <h2 id="cancelling">Cancelling</h2>
 <table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td>
-    <code>bool= lane_h:cancel( [timeout_secs=0.0,] [force_kill_bool=false] )</code>
+    <code>bool= lane_h:cancel( [timeout_secs=0.0,] [force_kill_bool=false] )
+    <br/>
+    <br/>
+      <code>
+     bool= cancel_test()
+      </code>
 </table>
-<p>Sends a cancellation request to the lane. If <tt>timeout_secs</tt> is non-zero, waits
+<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.
@@ -387,8 +394,9 @@ OS thread running the lane is forcefully killed. This means no GC, and should
 generally be the last resort.
 </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. A currently pending <tt>receive</tt>
+and after executing <tt>cancelstep</tt> Lua statements. A currently pending <tt>receive()</tt>
-or <tt>send</tt> call is currently not awakened, and may be a reason for a non-detected cancel.
+or <tt>send()</tt> call is currently not awakened, and may be a reason for a non-detected cancel.
+It is also possible to manually test for cancel requests with <tt>cancel_test()</tt>.
 </p>
@@ -799,7 +807,7 @@ 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),
+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">
@@ -817,12 +825,12 @@ can be used for custom userdata as well. Here's what to do.
      <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>
+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
+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
+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>
+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>
@@ -917,10 +925,10 @@ Here are some things one should consider, if best performance is vital:
    merged into one main timer state (see <tt>timer.lua</tt>); no OS side
    timers are utilized.
    </li>
-    <li>Lindas are hashed to a number of "keeper states", which are a locking entity.
+    <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
+    If you are using a lot of Linda objects,
-    these keeper states. By default, only one is used but this is an implementation detail.
+    it may be useful to try having more of these keeper states. By default,
-    It is possible to <tt>require( "lanes", N)</tt> to use more keeper states.
+    only one is used (see <tt>KEEPER_STATES_N</tt>), but this is an implementation detail.
    </li>
 </ul>
 </p>
@@ -952,31 +960,15 @@ its actual value.
 <h2 id="changes">Change log</h2>
 <p>
-Feb-2011 (2.1.0)
+Mar-2011 (2.1.0)
 <ul>
-  <li>Added an auto-require mechanism to ensure any deep userdata transiting in a lane causes its parent module to be required in that lane
+  <li>fixed potential crash at application shutdown when calling lua_close() on a killed thread's VM.</li>
-  <ul>
+  <li>exposed cancel_test() in the lanes to enable manual testing for cancellation requests.</li>
-    <li>Changed idfunc signature and contract to clarify the fact it is not lua-callable and to be able to require the module it was exported from in the target lanes</li>
+  <li>removed kludgy {globals={threadName}} support, replaced with a new function set_debug_threadname().</li>
-    <li>When a deep userdata idfunc requests a module to be required, manually check that it is not loaded before requiring it instead of relying on the require function's loop detection feature</li>
-    <li>When a module must be required, raise an error if the 'require' function is not found in the target state</li>
-    <li>We know Lanes is loaded in the master state, so we don't force it to be required in every lane too when a linda deep userdata is copied</li>
-  </ul>
-  </li>
-  <li>Fixed application hang-up because keeper state was not released in case of errors thrown by inter-state data copy for unsupported types</li>
-  <li>Refactor lane proxy implementation: it is now a full userdata instead of a table, and its methods are implemented in C instead of Lua
-    <ul>
-      <li>its metatable is no longer accessible</li>
-      <li>writing to the proxy raises an error</li>
-      <li>it is no longer possible to overwrite its join() and cancel() methods</li>
-    </ul>
-  </li>
-  <li>Moved keeper-related code in a separate source file</li>
-  <li>keeper.lua is now embedded in text form instead of bytecode to improve LuaJIT2-compatibility</li>
-  <li>Make the number of internal keeper states selctable by an optional parameter passed to require.</li>
 </ul>
 Feb-2011 (2.0.11):
-<ul>
+  <ul>
  <li>Fixed bug where reference to Linda object was dropped for a short time (crashing if GC was run during that time).</li>
  <li>Changed the atexit code to trip the timer thread's write signal.</li>
  <li>Changed lanes.c to export functions as a module rather than writing them directly to the globals table.</li>
author	Benoit Germain <bnt.germain@gmail.com>	2011-03-01 21:12:56 +0100
committer	Benoit Germain <bnt.germain@gmail.com>	2011-03-01 21:12:56 +0100
commit	e97adefde985e30fe31ffa036c74ffb0ce10ca26 (patch)
tree	4465decc5f07e7399f9760d6302dbaf7163120d7 /docs
parent	974aa4343cf900938b5d357d10798d91faf60f5a (diff)
download	lanes-e97adefde985e30fe31ffa036c74ffb0ce10ca26.tar.gz lanes-e97adefde985e30fe31ffa036c74ffb0ce10ca26.tar.bz2 lanes-e97adefde985e30fe31ffa036c74ffb0ce10ca26.zip

diff --git a/docs/index.html b/docs/index.html index 3d2ecf2..ba25515 100644 --- a/docs/index.html +++ b/docs/index.html
@@ -56,7 +56,7 @@
56		56
57	<p><br/><font size="-1"><i>Copyright © 2007-11 Asko Kauppi. All rights reserved.</i>	57	<p><br/><font size="-1"><i>Copyright © 2007-11 Asko Kauppi. All rights reserved.</i>
58	<br>Lua Lanes is published under the same <A HREF="http://en.wikipedia.org/wiki/MIT_License">MIT license</A> as Lua 5.1.	58	<br>Lua Lanes is published under the same <A HREF="http://en.wikipedia.org/wiki/MIT_License">MIT license</A> as Lua 5.1.
59	</p><p>This document was revised on 21-Feb-11, and applies to version 2.1.0.	59	</p><p>This document was revised on 1-Mar-11, and applies to version 2.1.0.
60	</font></p>	60	</font></p>
61		61
62	</center>	62	</center>
@@ -243,6 +243,7 @@ also in the new lanes.
243	<tt>:receive()</tt> or <tt>:send()</tt> call.	243	<tt>:receive()</tt> or <tt>:send()</tt> call.
244	With this option, one can set cancellation check to occur every <tt>N</tt>	244	With this option, one can set cancellation check to occur every <tt>N</tt>
245	Lua statements. The value <tt>true</tt> uses a default value (100).	245	Lua statements. The value <tt>true</tt> uses a default value (100).
		246	It is also possible to manually test for cancel requests with <tt>cancel_test()</tt>.
246	</td></tr>	247	</td></tr>
247		248
248	<tr valign=top><td/><td>	249	<tr valign=top><td/><td>
@@ -250,20 +251,21 @@ also in the new lanes.
250	<td>	251	<td>
251	Sets the globals table for the launched threads. This can be used for giving	252	Sets the globals table for the launched threads. This can be used for giving
252	them constants.	253	them constants.
253	</p><p>	254	<br>
254	The global values of different lanes are in no manner connected;	255	The global values of different lanes are in no manner connected;
255	modifying one will only affect the particular lane. Settings the variable 'threadName' in this table makes VS display the sent name instead of the normal thread name while debugging.	256	modifying one will only affect the particular lane.
256	</td></tr>	257	</td></tr>
257		258
258	<tr valign=top><td width=40><td>	259	<tr valign=top><td width=40><td>
259	<code>.priority</code> <br/><nobr>-2..+2</nobr></td>	260	<code>.priority</code> <br/><nobr>-2..+2</nobr></td>
260	<td>The priority of lanes generated. -2 is lowest, +2 is highest.	261	<td>The priority of lanes generated. -2 is lowest, +2 is highest.
261	<p>	262	<br>
262	Implementation and dependability of priorities varies	263	Implementation and dependability of priorities varies
263	by platform. Especially Linux kernel 2.6 is not supporting priorities in user mode.	264	by platform. Especially Linux kernel 2.6 is not supporting priorities in user mode.
264	</td></tr>	265	</td></tr>
265	</table>	266	</table>
266		267	<p>Each lane also gets a function <tt>set_debug_threadname()</tt> that it can use anytime to do as the name says.
		268	Supported debuggers are Microsoft Visual Studio (for the C side) and Decoda (for the Lua side).
267	</p>	269	</p>
268		270
269	<h3>Free running lanes</h3>	271	<h3>Free running lanes</h3>
@@ -374,10 +376,15 @@ that id over a Linda once that thread is done (as the last thing you do).
374	<h2 id="cancelling">Cancelling</h2>	376	<h2 id="cancelling">Cancelling</h2>
375		377
376	<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td>	378	<table border=1 bgcolor="#E0E0FF" cellpadding=10><tr><td>
377	<code>bool= lane_h:cancel( [timeout_secs=0.0,] [force_kill_bool=false] )</code>	379	<code>bool= lane_h:cancel( [timeout_secs=0.0,] [force_kill_bool=false] )
		380	<br/>
		381	<br/>
		382	<code>
		383	bool= cancel_test()
		384	</code>
378	</table>	385	</table>
379		386
380	<p>Sends a cancellation request to the lane. If <tt>timeout_secs</tt> is non-zero, waits	387	<p><tt>cancel()</tt>sends a cancellation request to the lane. If <tt>timeout_secs</tt> is non-zero, waits
381	for the request to be processed, or a timeout to occur.	388	for the request to be processed, or a timeout to occur.
382	Returns <tt>true</tt> if the lane was already done (in <tt>"done"</tt>, <tt>"error"</tt> or <tt>"cancelled"</tt> status)	389	Returns <tt>true</tt> if the lane was already done (in <tt>"done"</tt>, <tt>"error"</tt> or <tt>"cancelled"</tt> status)
383	or if the cancellation was fruitful within timeout period.	390	or if the cancellation was fruitful within timeout period.
@@ -387,8 +394,9 @@ OS thread running the lane is forcefully killed. This means no GC, and should
387	generally be the last resort.	394	generally be the last resort.
388	</p>	395	</p>
389	<p>Cancellation is tested <u>before</u> going to sleep in <tt>receive()</tt> or <tt>send()</tt> calls	396	<p>Cancellation is tested <u>before</u> going to sleep in <tt>receive()</tt> or <tt>send()</tt> calls
390	and after executing <tt>cancelstep</tt> Lua statements. A currently pending <tt>receive</tt>	397	and after executing <tt>cancelstep</tt> Lua statements. A currently pending <tt>receive()</tt>
391	or <tt>send</tt> call is currently not awakened, and may be a reason for a non-detected cancel.	398	or <tt>send()</tt> call is currently not awakened, and may be a reason for a non-detected cancel.
		399	It is also possible to manually test for cancel requests with <tt>cancel_test()</tt>.
392	</p>	400	</p>
393		401
394		402
@@ -799,7 +807,7 @@ can be used for custom userdata as well. Here's what to do.
799	</p>	807	</p>
800	<ol>	808	<ol>
801	<li>Provide an <i>identity function</i> for your userdata, in C. This function is	809	<li>Provide an <i>identity function</i> for your userdata, in C. This function is
802	used for creation and deletion of your deep userdata (the shared resource),	810	used for creation and deletion of your deep userdata (the shared resource),
803	and for making metatables for the state-specific proxies for accessing it. The	811	and for making metatables for the state-specific proxies for accessing it. The
804	prototype is	812	prototype is
805	<table border="1" bgcolor="#E0E0FF" cellpadding="10">	813	<table border="1" bgcolor="#E0E0FF" cellpadding="10">
@@ -817,12 +825,12 @@ can be used for custom userdata as well. Here's what to do.
817	<tt>"delete"</tt>: receives this same pointer on the stack, and should cleanup the object.</li>	825	<tt>"delete"</tt>: receives this same pointer on the stack, and should cleanup the object.</li>
818	<li>	826	<li>
819	<tt>"metatable"</tt>: should build a metatable for the object. Don't cache the metatable	827	<tt>"metatable"</tt>: should build a metatable for the object. Don't cache the metatable
820	yourself, Lanes takes care of it ("metatable" should only be invoked once).</li>	828	yourself, Lanes takes care of it ("metatable" should only be invoked once).</li>
821	<li>	829	<li>
822	<tt>"module"</tt>: is the name of the module that exports the idfunc,	830	<tt>"module"</tt>: is the name of the module that exports the idfunc,
823	to be pushed on the stack as a string. It is necessary so that Lanes can require it in	831	to be pushed on the stack as a string. It is necessary so that Lanes can require it in
824	any Lane and keeper state that receives a userdata. This is to prevent crashes in situations	832	any Lane and keeper state that receives a userdata. This is to prevent crashes in situations
825	where the module could be unloaded while the idfunc pointer is still held.</li>	833	where the module could be unloaded while the idfunc pointer is still held.</li>
826	</ul>	834	</ul>
827	Take a look at <tt>linda_id</tt> in <tt>lanes.c</tt>.	835	Take a look at <tt>linda_id</tt> in <tt>lanes.c</tt>.
828	</li>	836	</li>
@@ -917,10 +925,10 @@ Here are some things one should consider, if best performance is vital:
917	merged into one main timer state (see <tt>timer.lua</tt>); no OS side	925	merged into one main timer state (see <tt>timer.lua</tt>); no OS side
918	timers are utilized.	926	timers are utilized.
919	</li>	927	</li>
920	<li>Lindas are hashed to a number of "keeper states", which are a locking entity.	928	<li>Lindas are hashed to a fixed number of "keeper states", which are a locking entity.
921	If you are using a lot of Linda objects, it may be useful to try having more of	929	If you are using a lot of Linda objects,
922	these keeper states. By default, only one is used but this is an implementation detail.	930	it may be useful to try having more of these keeper states. By default,
923	It is possible to <tt>require( "lanes", N)</tt> to use more keeper states.	931	only one is used (see <tt>KEEPER_STATES_N</tt>), but this is an implementation detail.
924	</li>	932	</li>
925	</ul>	933	</ul>
926	</p>	934	</p>
@@ -952,31 +960,15 @@ its actual value.
952	<h2 id="changes">Change log</h2>	960	<h2 id="changes">Change log</h2>
953		961
954	<p>	962	<p>
955	Feb-2011 (2.1.0)	963
		964	Mar-2011 (2.1.0)
956	<ul>	965	<ul>
957	<li>Added an auto-require mechanism to ensure any deep userdata transiting in a lane causes its parent module to be required in that lane	966	<li>fixed potential crash at application shutdown when calling lua_close() on a killed thread's VM.</li>
958	<ul>	967	<li>exposed cancel_test() in the lanes to enable manual testing for cancellation requests.</li>
959	<li>Changed idfunc signature and contract to clarify the fact it is not lua-callable and to be able to require the module it was exported from in the target lanes</li>	968	<li>removed kludgy {globals={threadName}} support, replaced with a new function set_debug_threadname().</li>
960	<li>When a deep userdata idfunc requests a module to be required, manually check that it is not loaded before requiring it instead of relying on the require function's loop detection feature</li>
961	<li>When a module must be required, raise an error if the 'require' function is not found in the target state</li>
962	<li>We know Lanes is loaded in the master state, so we don't force it to be required in every lane too when a linda deep userdata is copied</li>
963	</ul>
964	</li>
965	<li>Fixed application hang-up because keeper state was not released in case of errors thrown by inter-state data copy for unsupported types</li>
966	<li>Refactor lane proxy implementation: it is now a full userdata instead of a table, and its methods are implemented in C instead of Lua
967	<ul>
968	<li>its metatable is no longer accessible</li>
969	<li>writing to the proxy raises an error</li>
970	<li>it is no longer possible to overwrite its join() and cancel() methods</li>
971	</ul>
972	</li>
973	<li>Moved keeper-related code in a separate source file</li>
974	<li>keeper.lua is now embedded in text form instead of bytecode to improve LuaJIT2-compatibility</li>
975	<li>Make the number of internal keeper states selctable by an optional parameter passed to require.</li>
976	</ul>	969	</ul>
977
978	Feb-2011 (2.0.11):	970	Feb-2011 (2.0.11):
979	<ul>	971	<ul>
980	<li>Fixed bug where reference to Linda object was dropped for a short time (crashing if GC was run during that time).</li>	972	<li>Fixed bug where reference to Linda object was dropped for a short time (crashing if GC was run during that time).</li>
981	<li>Changed the atexit code to trip the timer thread's write signal.</li>	973	<li>Changed the atexit code to trip the timer thread's write signal.</li>
982	<li>Changed lanes.c to export functions as a module rather than writing them directly to the globals table.</li>	974	<li>Changed lanes.c to export functions as a module rather than writing them directly to the globals table.</li>