Documentation improvements

* added an API cheat sheet
* improved documentation for lane:cancel()

1 files 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 />