Merge ec02841 into 2500eb5

docs/index.html

@@ -102,32 +102,43 @@ <h2><a name="history"></a>History</h2>
 <dl class="history">
     <dt><strong>Copas x.x.x</strong> [unreleased]</dt>
 	<dd><ul>
-        <li>Added: added sempahore:destroy()</li>
-        <li>Added: copas.settimeouts, to set separate timeouts for connect, send, receive</li>
+        <li>Added: added <code>sempahore:destroy()</code></li>
+        <li>Added: <code>copas.settimeouts</code>, to set separate timeouts for connect, send, receive</li>
         <li>Added: queue class, see module "copas.queue"</li>
+        <li>Added: names for sockets and coroutines:
+            <ul>
+                <li><code>copas.addserver()</code> has a 4th argument; name, to name the server socket</li>
+                <li><code>copas.addnamedthread()</code> is new and identical to <code>copas.addthread()</code>,
+                but also accepts a name</li>
+                <li><code>copas.setsocketname()</code>, <code>copas.getsocketname()</code>,
+                <code>copas.setthreadname()</code>, <code>copas.getthreadname()</code> added to manage names</li>
+                <li><code>copas.debug.start()</code> and <code>copas.debug.end()</code> to enable debug
+                logging for the scheduler itself.</li>
+            </ul>
+        </li>
 	</ul></dd>
 
     <dt><strong>Copas 3.0.0</strong> [12/Nov/2021]</dt>
 	<dd><ul>
-        <li>[breaking] Change: copas.addserver() now uses the timeout value as a copas timeout,
+        <li>[breaking] Change: <code>copas.addserver()</code> now uses the timeout value as a copas timeout,
             instead of a luasocket timeout. The client sockets for incoming connections will
             inherit the timeout from the server socket.</li>
         <li>Added: support for SNI on TLS connections #81 (@amyspark)</li>
-        <li>Added: copas.settimeout() so Copas can manage its own timeouts instead of spinning forever (Patrick Barrett )</li>
+        <li>Added: <code>copas.settimeout()</code> so Copas can manage its own timeouts instead of spinning forever (Patrick Barrett )</li>
         <li>Added: timer class, see module "copas.timer"</li>
         <li>Added: lock class, see module "copas.lock"</li>
         <li>Added: semaphore class, see module "copas.semaphore"</li>
-        <li>Added: timeout interface copas.timeout()</li>
+        <li>Added: timeout interface <code>copas.timeout()</code></li>
         <li>Added: option to override the default errorhandler, and fixes to the handler</li>
-        <li>Added: copas.removethread() added to be able to forcefully remove a previously added thread</li>
-        <li>Added: copas.loop() now takes an optional initialization function</li>
+        <li>Added: <code>copas.removethread()</code> added to be able to forcefully remove a previously added thread</li>
+        <li>Added: <code>copas.loop()</code> now takes an optional initialization function</li>
         <li>Fixed: closing sockets from another thread would make the read/write ops hang #104</li>
         <li>Fixed: coxpcall dependency in limit.lua #63 (Francois Perrad)</li>
         <li>Fixed: CI now generates the certificates for testing, on unix make can be used, on Windows generate them manually</li>
-        <li>Fixed: type in wrapped udp:setpeername was actually calling udp:getpeername</li>
+        <li>Fixed: type in wrapped <code>udp:setpeername</code> was actually calling <code>udp:getpeername</code></li>
         <li>Fixed: default error handler didn't print the stacktrace</li>
         <li>Fixed: small memory leak when sleeping until woken</li>
-        <li>Fixed: do not wrap udp:sendto() method, since udp send doesn't block</li>
+        <li>Fixed: do not wrap <code>udp:sendto()</code> method, since udp send doesn't block</li>
         <li>Change: performance improvement in big limit-sets (Francisco Castro)</li>
         <li>Change: update deprecated tls default to tls 1.2 in (copas.http)</li>
 	</ul></dd>

docs/reference.html

@@ -81,7 +81,8 @@ <h3>Getting started examples</h3>
 
 end
 
-copas.addserver(server_socket, copas.handler(connection_handler, ssl_params))
+copas.addserver(server_socket, copas.handler(connection_handler,
+    ssl_params), "my_TCP_server")
 
 copas.loop()
 </pre>
@@ -103,6 +104,7 @@ <h3>Getting started examples</h3>
     }
 
     local sock = copas.wrap(socket.tcp(), ssl_params)
+    copas.setsocketname("my_TCP_client", sock)
     assert(sock:connect(host, port))
 
     local data, err = sock:receive("*l")
@@ -121,17 +123,29 @@ <h3>Copas dispatcher main functions</h3>
 are used to register servers and to execute the main loop of Copas:</p>
 
 <dl class="reference">
-    <dt><strong><code>copas.addserver(server, handler[, timeout])</code></strong></dt>
+    <dt><strong><code>copas.addserver(server, handler[, timeout[, name]])</code></strong></dt>
     <dd>Adds a new <code>server</code> and its <code>handler</code> to the dispatcher
         using an optional <code>timeout</code>.<br />
         <code>server</code> is a LuaSocket server socket created using
         <code>socket.bind()</code>.<br />
         <code>handler</code> is a function that receives a LuaSocket client socket
-        and handles the communication with that client.<br />
+        and handles the communication with that client.
+        The handler will be executed in parallel with other threads and
+        registered handlers as long as it uses the Copas socket functions.<br />
         <code>timeout</code> is the timeout in seconds. Upon accepting connections,
         the timeout will be inherited by TCP client sockets (only applies to TCP).<br />
-        The handler will be executed in parallel with other threads and the
-        registered handlers as long as it uses the Copas socket functions.
+        <code>name</code> is the internal name to use for this socket. The handler threads and
+        (in case of TCP) the incoming client connections will get a name derived from the server socket.<br />
+        <ul>
+            <li>TCP: client-socket name: <code>"[server_name]:client_XX"</code> and the handler thread
+            <code>"[server_name]:handler_XX"</code> where <code>XX</code> is a sequential number matching
+            between the client-socket and handler.</li>
+            <li>UDP: the handler thread will be named <code>"[server_name]:handler"</code></li>
+        </ul>
+    </dd>
+
+    <dt><strong><code>coro = copas.addnamedthread(func [, name [, ...]])</code></strong></dt>
+    <dd>Same as <code>copas.addthread</code>, but also names the new thread.
     </dd>
 
     <dt><strong><code>coro = copas.addthread(func [, ...])</code></strong></dt>
@@ -158,6 +172,15 @@ <h3>Copas dispatcher main functions</h3>
         See also <code>copas.running</code>.
     </dd>
 
+    <dt><strong><code>copas.getsocketname(skt)</code></strong></dt>
+        <dd>Returns the name for the socket.
+    </dd>
+
+    <dt><strong><code>copas.getthreadname([co])</code></strong></dt>
+        <dd>Returns the name for the coroutine/thread. If not given defaults to the
+        currently running coroutine.
+    </dd>
+
     <dt><strong><code>func = copas.handler(connhandler [, sslparams])</code></strong></dt>
         <dd>Wraps the <code>connhandler</code> function. Returns a new function that
         wraps the client socket, and (if <code>sslparams</code> is provided) performs
@@ -171,7 +194,8 @@ <h3>Copas dispatcher main functions</h3>
         handlers. Every time a server accepts a connection, Copas calls the
         associated handler passing the client socket returned by
         <code>socket.accept()</code>. The <code>init_func</code> function is an
-        optional initialization function that runs as a Copas thread.
+        optional initialization function that runs as a Copas thread
+        (with name <code>"copas_initializer"</code>).
         The <code>timeout</code> parameter is optional,
         and is passed to the <code>copas.step()</code> function.
         The loop returns when <code>copas.finished() == true</code>.
@@ -206,6 +230,15 @@ <h3>Copas dispatcher main functions</h3>
         on how to deal with the arguments when implementing your own.
     </dd>
 
+    <dt><strong><code>copas.setsocketname(name, skt)</code></strong></dt>
+        <dd>Sets the name for the socket.
+    </dd>
+
+    <dt><strong><code>copas.setthreadname(name [,co])</code></strong></dt>
+        <dd>Sets the name for the coroutine/thread. <code>co</code> defaults to the
+        currently running coroutine.
+    </dd>
+
     <dt><strong><code>copas.wrap(skt [, sslparams] )</code></strong></dt>
     <dd>Wraps a LuaSocket socket and returns a Copas socket that implements LuaSocket's API
         but use Copas' methods like <code>copas.send()</code> and <code>copas.receive()</code>
@@ -367,8 +400,19 @@ <h3>Non-blocking data exchange and timer/sleep functions</h3>
     Returns <code>list</code> or <code>nil + "destroyed"</code>.
     </dd>
 
-    <dt><strong><code>queue.new()</code></strong></dt>
-    <dd>Creates and returns a new queue.
+    <dt><strong><code>queue.name</code></strong></dt>
+    <dd>A field set to name of the queue. See <code>queue.new()</code>.
+    </dd>
+
+    <dt><strong><code>queue.new([options])</code></strong></dt>
+    <dd>Creates and returns a new queue. The <code>options</code> table has the following
+    fields:
+    <ul>
+        <li><code>options.name</code>: (optional) the name for the queue, the default name will be
+        <code>"copas_queue_XX"</code>. The name will be used to name any workers
+        added to the queue using <code>queue:add_worker()</code>, their name will be
+        <code>"[queue_name]:worker_XX"</code></li>
+    </ul>
     </dd>
 
     <dt><strong><code>queue:pop([timeout])</code></strong></dt>
@@ -438,6 +482,8 @@ <h3>Non-blocking data exchange and timer/sleep functions</h3>
     <dt><strong><code>timer.new(options)</code></strong></dt>
     <dd>Creates and returns an (armed) timer object. The <code>options</code> table has the following fields;
     <ul>
+        <li><code>options.name</code>: (optional) the name for the timer, the default name will be
+        <code>"copas_timer_XX"</code>. The name will be used to name the timer thread.</li>
         <li><code>options.recurring</code> boolean</li>
         <li><code>options.delay</code> expiry delay in seconds</li>
         <li><code>options.initial_delay</code> (optional) see <code>timer:arm()</code></li>
@@ -639,6 +685,26 @@ <h3>Low level Copas functions</h3>
 
 </dl>
 
+<h3>Copas debugging functions</h3>
+
+<p>These functions are mainly used for debugging Copas itself and should be considered experimental.</p>
+
+<dl class="reference">
+
+    <dt><strong><code>copas.debug.start([logger] [, core])</code></strong></dt>
+    <dd>This will internally replace coroutine handler functions to provide log output to
+    the provided <code>logger</code> function. The logger signature is <code>function(...)</code>
+    and the default value is the global <code>print()</code> function.<br />
+    If the <code>core</code> parameter is truthy, then also the Copas core timer will be
+    logged (very noisy).
+    </dd>
+
+    <dt><strong><code>copas.debug.stop()</code></strong></dt>
+    <dd>Stops the debug output being generated.
+    </dd>
+
+</dl>
+
 
 </div> <!-- id="content" -->