add docs

docs/index.html

@@ -104,6 +104,8 @@ <h2><a name="history"></a>History</h2>
         <li>Change: Copas no longer requires LuaSocket, if no sockets are needed, LuaSystem will be enough as a fallback.</li>
         <li>Feat: added <code>copas.gettime()</code>, which transparently maps to either LuaSockets or
         LuaSystems implementation, ensuring independence of the availability of either one of those.</li>
+        <li>Feat: Controlled exit of the Copas loop. Adding <code>copas.exit()</code>, <code>copas.exiting()</code>, and
+        <code>copas.waitforexit()</code>.</li>
     </ul></dd>
 
     <dt><strong>Copas 4.7.1</strong> [9/Mar/2024]</dt>

docs/reference.html

@@ -180,6 +180,29 @@ <h3>Copas dispatcher main functions</h3>
         truthy.</p>
     </dd>
 
+    <dt><strong><code>copas.exit()</code></strong></dt>
+    <dd>
+        <p>Sets a flag that the application is intending to exit. After calling
+        this function <code>copas.exiting()</code> will be returning <code>true</code>, add
+        all threads blocked on <code>copas.waitforexit()</code> will be released.</p>
+
+        <p>Copas itself will call this function when <code>copas.finished()</code> returns
+        <code>true</code>.</p>
+    </dd>
+
+    <dt><strong><code>bool = copas.exiting()</code></strong></dt>
+    <dd>
+        <p>Returns a flag indicating whether the application is supposed to exit.
+        Returns <code>false</code> until after <code>copas.exit()</code> has been called,
+        after which it will start returning <code>true</code>.</p>
+
+        <p>Clients should check whether they are to cease their operation and exit. They
+        can do this by checking this flag, or by registering a task waiting on
+        <code>copas.waitforexit()</code>. Clients should cancel pending work and close sockets
+        when an exit is announced, otherwise Copas will not exit.
+        </p>
+    </dd>
+
     <dt><strong><code>bool = copas.finished()</code></strong></dt>
     <dd>
         <p>Checks whether anything remains to be done.</p>
@@ -304,6 +327,15 @@ <h3>Copas dispatcher main functions</h3>
         currently running coroutine.</p>
     </dd>
 
+    <dt><strong><code>copas.waitforexit()</code></strong></dt>
+    <dd>
+        <p>This will block the calling coroutine until the <code>copas.exit()</code> function
+        is called. Clients should check whether they are to cease their operation and exit. They
+        can do this by waiting on this call, or by checking the <code>copas.exiting()</code> flag.
+        Clients should cancel pending work and close sockets when an exit is announced, otherwise
+        Copas will not exit.</p>
+    </dd>
+
     <dt><strong><code>skt = copas.wrap(skt [, sslparams] )</code></strong></dt>
     <dd>
         <p>Wraps a LuaSocket socket and returns a Copas socket that implements LuaSocket's API