From fa89fef9db0435b4e2c017a1aa67f1b2467a07da Mon Sep 17 00:00:00 2001
From: Benoit Germain <bnt.germain@gmail.com>
Date: Mon, 21 Apr 2025 13:54:07 +0200
Subject: Documentation improvements

* added an API cheat sheet
* improved documentation for lane:cancel()
---
 docs/index.html | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 88 insertions(+), 10 deletions(-)

diff --git a/docs/index.html b/docs/index.html
index 116fc0a..3dfac70 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -38,6 +38,7 @@
 			<a href="#description">Description</a> &middot;
 			<a href="#systems">Supported systems</a> &middot;
 			<a href="#installing">Building and Installing</a> &middot;
+			<a href="#apicheatsheet">API Cheat sheet</a>
 			<a href="#embedding">Embedding</a>
 		</p>
 
@@ -70,7 +71,7 @@
 			</p>
 
 			<p>
-				This document was revised on 18-Apr-25, and applies to version <tt>4.0.0</tt>.
+				This document was revised on 21-Apr-25, and applies to version <tt>4.0.0</tt>.
 			</p>
 		</font>
 	</center>
@@ -169,6 +170,82 @@
 </pre>
 
 
+<!-- API reference +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+ <hr/>
+ <h2 id="apicheatsheet">API Cheat sheet</h2>
+ <ul>
+	<li>
+		<tt>require "lanes"</tt>: to require Lanes
+	</li>
+	<li>
+		The <tt>lanes</tt> module
+		<ul>
+			<li><tt>lanes.cancel_error</tt>: a special error value returned from cancelled lanes</li>
+			<li><tt>lanes.collectgarbage()</tt>: o trigger a GC cycle in all Keeper states</li>
+			<li><tt>lanes.configure()</tt>: to configure Lanes</li>
+			<li><tt>lanes.coro()</tt>: to start a coroutine-like lane</li>
+			<li><tt>lanes.finally()</tt>: to install a function called on Lanes shutdown</li>
+			<li><tt>lanes.gen()</tt>: to start a lane as a regular function</li>
+			<li><tt>lanes.genactomic()</tt>: to obtain an atomic counter</li>
+			<li><tt>lanes.genlock()</tt>: to obtain an atomic-like data stack</li>
+			<li><tt>lanes.linda()</tt>: to create a Linda</li>
+			<li><tt>lanes.nameof()</tt>: to find where a value exists</li>
+			<li><tt>lanes.now_secs()</tt>: to obtain the current clock value</li>
+			<li><tt>lanes.register()</tt>: to scan modules so that functions using them can be transferred</li>
+			<li><tt>lanes.set_thread_priority()</tt>: to change thread priority</li>
+			<li><tt>lanes.set_thread_affinity()</tt>: to change thread affinity</li>
+			<li><tt>lanes.threads()</tt>: to obtain a list of all lanes</li>
+			<li><tt>lanes.sleep()</tt>: to sleep for a given duration</li>
+			<li><tt>lanes.timer()</tt>: to start a timer</li>
+			<li><tt>lanes.timers()</tt>: to list active timers</li>
+		</ul>
+	</li>
+	<li>
+		Given some lane handle <tt>lane_h</tt>
+		<ul>
+			<li><tt>lane_h[]</tt>: to wait for, and read the values returned by the lane</li>
+			<li><tt>lane_h:cancel()</tt>: to request the lane to stop running</li>
+			<li><tt>lane_h.error_trace_level</tt>: current setting of error logging level</li>
+			<li><tt>lane_h:get_threadname()</tt>: to read the thread name</li>
+			<li><tt>lane_h:join()</tt>: to wait for the lane to terminate (or yield)</li>
+			<li><tt>lane_h:resume()</tt>: to resume a coroutine Lane</li>
+			<li><tt>lane_h.status</tt>: current status of the lane</li>
+		</ul>
+	</li>
+	<li>
+		Inside the lane
+		<ul>
+			<li><tt>lane_threadname()</tt>: to read or change the name of the thread</li>
+			<li><tt>set_finalizer()</tt>: to install a function called when the lane exits</li>
+		</ul>
+	</li>
+	<li>
+		Given some Linda <tt>l</tt>
+		<ul>
+			<li><tt>l:cancel()</tt>: to mark a Linda for cancellation</li>
+			<li><tt>l:collectgarbage()</tt>: to trigger a GC cycle in the Linda's Keeper state</li>
+			<li><tt>l:deep()</tt>: returns a light userdata uniquely representing the Linda</li>
+			<li><tt>l:dump()</tt>: to have information about slot contents</li>
+			<li><tt>l:count()</tt>: to count data items</li>
+			<li><tt>l:get()</tt>: to read data without consuming it</li>
+			<li><tt>l:limit()</tt>: to cap the amount of transiting data</li>
+			<li><tt>l:receive()</tt>: to read one item of data from multiple slots</li>
+			<li><tt>l:receive_batched()</tt>: to to read several item of data from a single slot</li>
+			<li><tt>l:restrict()</tt>: to place a restraint on the operations that can be done</li>
+			<li><tt>l:send()</tt>: to append data</li>
+			<li><tt>l:set()</tt>: to replace the data</li>
+			<li><tt>l:wake()</tt>: to manually wake blocking calls</li>
+		</ul>
+	</li>
+	<li>
+		embedding
+		<ul>
+			<li><tt>luaopen_lanes_embedded</tt>: to manually initialize Lanes</li>
+		</ul>
+	</li>
+ </ul>
+
+
 <!-- embedding +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 <hr/>
 <h2 id="embedding">Embedding</h2>
@@ -1137,14 +1214,17 @@
 </pre></td></tr></table>
 
 <p>
-	<tt>timeout</tt> is an optional number &gt= 0. Defaults to infinite if left unspecified or <tt>nil</tt>.
-	<br />
 	<tt>cancel()</tt> sends a cancellation request to the lane.
-	<br />
-	First argument is a <tt>mode</tt> can be one of:
+	<p>
+		Returns <tt>true, lane_h.status</tt> if lane was already done (in <tt>"done"</tt>, <tt>"error"</tt> or <tt>"cancelled"</tt> status), or the cancellation was fruitful within <tt>timeout_secs</tt> timeout period.<br />
+		Returns <tt>false, "timeout"</tt> otherwise.
+	</p>
+	First argument is a <tt>mode</tt>. It can be one of:
 	<ul>
 		<li>
 			<tt>"soft"</tt>: Cancellation will only cause <tt>cancel_test()</tt> to return <tt>true</tt>, so that the lane can cleanup manually.
+			<br />
+			Lindas will also check for cancellation inside blocking calls to early out based on their <tt>wake_period</tt>.
 		</li>
 		<li>
 			<tt>"hard"</tt>: waits for the request to be processed, or a timeout to occur. <a href="#lindas">linda</a> operations detecting the cancellation request will raise a special cancellation error (meaning they won't return in that case).<br />
@@ -1160,15 +1240,13 @@
 	If <tt>mode</tt> is not specified, it defaults to <tt>"hard"</tt>.
 	If <tt>wake_lane</tt> is <tt>true</tt>, the lane is also signalled so that execution returns from any pending <a href="#lindas">linda</a> operation. <a href="#lindas">linda</a> operations detecting the cancellation request return <tt>lanes.cancel_error</tt>.
 </p>
-<p>
-	Returns <tt>true, lane_h.status</tt> if lane was already done (in <tt>"done"</tt>, <tt>"error"</tt> or <tt>"cancelled"</tt> status), or the cancellation was fruitful within <tt>timeout_secs</tt> timeout period.<br />
-	Returns <tt>false, "timeout"</tt> otherwise.
-</p>
+<tt>timeout</tt> is an optional number &gt= 0. Defaults to infinite if left unspecified or <tt>nil</tt>.
+<br />
 <p>
 	If the lane is still running after the timeout expired, there is a chance lanes will freeze forever at shutdown when failing to terminate all free-running lanes within the specified timeout.
 </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 pending <tt>receive()</tt>or <tt>send()</tt> call is awakened.
+	Cancellation is tested <u>before</u> going to sleep in <tt>receive()</tt>, <tt>receive_batched()</tt> or <tt>send()</tt> calls and after executing <tt>cancelstep</tt> Lua statements. 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 <a href="#lindas">linda</a> with infinite timeout).
 	<br />
-- 
cgit v1.2.3-55-g6feb