Squashed commit of the following:

commit 37a07a1 Merge: a76c8a9 4e3111a Author: Thijs Schreijer <thijs@thijsschreijer.nl> Date: Fri Mar 6 10:04:58 2015 +0100 Merge pull request lunarmodules#26 from Tieske/fix_autoclose fixed autoclose not closing udp sockets. added docs for autoclose commit 4e3111a Author: Thijs Schreijer <thijs@thijsschreijer.nl> Date: Fri Mar 6 09:57:39 2015 +0100 fixed autoclose not closing udp sockets. added docs for autoclose commit a76c8a9 Merge: be58265 10f0485 Author: Thijs Schreijer <thijs@thijsschreijer.nl> Date: Thu Mar 5 17:34:25 2015 +0100 Merge pull request lunarmodules#25 from Tieske/exit Exit loop when all is done commit 10f0485 Author: Thijs Schreijer <thijs@thijsschreijer.nl> Date: Thu Mar 5 17:23:02 2015 +0100 fixed doc error commit e38972d Author: Thijs Schreijer <thijs@thijsschreijer.nl> Date: Thu Mar 5 17:19:06 2015 +0100 added doc updates commit b49f837 Author: Thijs Schreijer <thijs@thijsschreijer.nl> Date: Thu Mar 5 16:54:31 2015 +0100 Exit loop when all is done (now that more client support has been added). Added comments regarding the watchdog. commit be58265 Merge: 05eeb53 a69e851 Author: Thijs Schreijer <thijs@thijsschreijer.nl> Date: Tue Mar 3 09:40:14 2015 +0100 Merge pull request lunarmodules#24 from Tieske/master removed duplicate data from readme commit a69e851 Author: Thijs Schreijer <thijs@thijsschreijer.nl> Date: Tue Mar 3 09:37:55 2015 +0100 removed duplicate data commit 05eeb53 Merge: 00bcd5f 25ab0dd Author: Thijs Schreijer <thijs@thijsschreijer.nl> Date: Mon Mar 2 18:12:38 2015 +0100 Merge pull request lunarmodules#23 from Tieske/master Updated documentation, and support for wrapped sockets when removing a s... commit 25ab0dd Author: Thijs Schreijer <thijs@thijsschreijer.nl> Date: Mon Mar 2 18:11:40 2015 +0100 Updated documentation, and support for wrapped sockets when removing a server commit 00bcd5f Merge: c6492e5 ee77f93 Author: Thijs Schreijer <thijs@thijsschreijer.nl> Date: Mon Mar 2 17:30:57 2015 +0100 Merge pull request lunarmodules#17 from pkulchenko/remove-server Added ability to remove server after adding. commit c6492e5 Merge: b718ad1 218667f Author: Thijs Schreijer <thijs@thijsschreijer.nl> Date: Mon Mar 2 17:30:07 2015 +0100 Merge pull request lunarmodules#22 from Tieske/cleanup Cleanup commit 218667f Author: Thijs Schreijer <thijs@thijsschreijer.nl> Date: Sat Feb 28 09:07:18 2015 +0100 Cleanup. Marked some legacy Lua 5.1 code for future removal, removed some unused locals and deadcode commit b718ad1 Merge: d2474ab 17c21ef Author: Hisham Muhammad <hisham@gobolinux.org> Date: Thu Oct 9 12:26:47 2014 -0300 Merge pull request lunarmodules#20 from ignacio/patch-1 Change link to point to keplerproject.github.io/copas commit 17c21ef Author: Ignacio Burgueño <iburgueno@gmail.com> Date: Thu Oct 9 12:43:00 2014 -0200 Change link to point to keplerproject.github.io/copas Changes the link to point to keplerproject.github.io/copas The link in the description should be updated too.
Metastruct · Mar 25, 2015 · 7790a80 · 7790a80
1 parent ee77f93
commit 7790a80
Show file tree

Hide file tree

Showing 7 changed files with 197 additions and 118 deletions.
diff --git a/README b/README
@@ -1,5 +1,5 @@
 Copas 1.2.1
-(http://www.keplerproject.org/copas)
+(http://keplerproject.github.io/copas)
 
 Copas is a dispatcher based on coroutines that can be used by TCP/IP servers.
 It uses LuaSocket as the interface with the TCP/IP stack.
@@ -16,47 +16,4 @@ Copas can be downloaded from its GitHub page.
 You can also install Copas using LuaRocks:
 luarocks install copas
 
-Dependencies
-Copas depends on LuaSocket and Coxpcall 1.14.
-
-History
-
-Copas 1.2.1 [07/Jan/2014]
-* Fixed bad version constant
-* Fixed timer issue
-* Updated documentation
-
-Copas 1.2.0 [2013]
-* Support for Lua 5.2
-* UDP support
-* suspending threads
-* other minor updates
-
-Copas 1.1.6 [18/Mar/2010]
-* Now checks to see if socket.http was required before copas 
-
-Copas 1.1.5 [07/Apr/2009]
-* Fixed bug reported by Sam Roberts on the Kepler list
-
-Copas 1.1.4 [10/Dec/2008]
-* Fixed bug [#5372] - copas.connect is semi-broken (found by Gary ng)
-
-Copas 1.1.3 [19/May/2008]
-* Using copcall instead of pcall in socket.protect (feature request [#5274] by Gary NG)
-
-Copas 1.1.2 [15/May/2008]
-* Fixed Bug [#4249] - bugs in copas.receive (found by Gary NG)
-
-Copas 1.1.1 [13/Aug/2007]
-* Compatible with Lua 5.1
-* Refactored by Thomas Harning Jr. (for more details check Bug 766)
-* Patch by Gary NG concerning the handling of stopped sockets
-
-Copas 1.1 [20/Sep/2006]
-* copas.addthread() added
-
-Copas 1.0 [17/May/2005]
-* copas.step() added
-
-Copas 1.0 Beta[17/Feb/2005]
-* First public version
+For more details see the documentation at http://keplerproject.github.io/copas/
diff --git a/doc/us/index.html b/doc/us/index.html
@@ -40,6 +40,9 @@ <h1>Copas</h1>
             <li><a href="manual.html#introduction">Introduction</a></li>
             <li><a href="manual.html#why">Why use Copas?</a></li>
             <li><a href="manual.html#using">Using Copas</a></li>
+            <li><a href="manual.html#udp">UDP support</a></li>
+            <li><a href="manual.html#tasks">Adding tasks</a></li>
+            <li><a href="manual.html#timers">Creating timers</a></li>
             <li><a href="manual.html#control">Controlling Copas</a></li>
         </ul>
     </li>

diff --git a/doc/us/license.html b/doc/us/license.html
@@ -40,6 +40,9 @@ <h1>Copas</h1>
             <li><a href="manual.html#introduction">Introduction</a></li>
             <li><a href="manual.html#why">Why use Copas?</a></li>
             <li><a href="manual.html#using">Using Copas</a></li>
+            <li><a href="manual.html#udp">UDP support</a></li>
+            <li><a href="manual.html#tasks">Adding tasks</a></li>
+            <li><a href="manual.html#timers">Creating timers</a></li>
             <li><a href="manual.html#control">Controlling Copas</a></li>
         </ul>
     </li>

diff --git a/doc/us/manual.html b/doc/us/manual.html
@@ -40,6 +40,9 @@ <h1>Copas</h1>
             <li><a href="manual.html#introduction">Introduction</a></li>
             <li><a href="manual.html#why">Why use Copas?</a></li>
             <li><a href="manual.html#using">Using Copas</a></li>
+            <li><a href="manual.html#udp">UDP support</a></li>
+            <li><a href="manual.html#tasks">Adding tasks</a></li>
+            <li><a href="manual.html#timers">Creating timers</a></li>
             <li><a href="manual.html#control">Controlling Copas</a></li>
         </ul>
     </li>
@@ -314,16 +317,17 @@ <h2><a name="udp"></a>Using UDP servers</h2>
 luasocket UDP sockets. This limitation is removed when the socket is wrapped 
 (it then defaults to 8192, the max UDP datagram size luasocket supports).</p>
 
-<h2><a name="thread"></a>Adding threads</h2>
-<p>Additional threads may be added to the scheduler, as long as they use the Copas send and receive methods. Below an example of a thread being added to create an outgoing TCP connection using Copas;</p>
+<h2><a name="tasks"></a>Adding tasks</h2>
+<p>Additional threads may be added to the scheduler, as long as they use the Copas <code>send</code>, <code>receive</code> or <code>sleep</code> methods. Below an example of a thread being added to create an outgoing TCP connection using Copas;</p>
 <pre class="example">
 local socket = require("socket")
-local copas = require("copas.timer")
+local copas = require("copas")
 
 local host = "127.0.0.1"
 local port = 10000
 
 local skt = socket.connect(host, port)
+skt:settimeout(0)  -- important: make it non-blocking
 
 copas.addthread(function()
    while true do
@@ -341,6 +345,25 @@ <h2><a name="thread"></a>Adding threads</h2>
 </pre>
 <p>The example connects, echoes whatever it receives and exits upon receiving 'quit'.</p>
 
+<h2><a name="timers"></a>Creating timers</h2>
+<p>Timers can be created using the <code>addthread</code> method with the <code>sleep</code> method. 
+Below an example of a thread being added to create and used as a timer;</p>
+<pre class="example">
+local copas = require("copas")
+
+copas.addthread(function()
+   print("This will print immediately, upon adding the thread. So before the loop starts")
+   while true do
+      copas.sleep(1) -- 1 second interval
+      print("Hello there!")
+   end
+end)
+
+print("We're starting!")
+copas.loop()
+</pre>
+<p>The example simply prints a message once every second.</p>
+
 <h2><a name="control"></a>Controlling Copas</h2>
 
 <p>

diff --git a/doc/us/reference.html b/doc/us/reference.html
@@ -40,6 +40,9 @@ <h1>Copas</h1>
             <li><a href="manual.html#introduction">Introduction</a></li>
             <li><a href="manual.html#why">Why use Copas?</a></li>
             <li><a href="manual.html#using">Using Copas</a></li>
+            <li><a href="manual.html#udp">UDP support</a></li>
+            <li><a href="manual.html#tasks">Adding tasks</a></li>
+            <li><a href="manual.html#timers">Creating timers</a></li>
             <li><a href="manual.html#control">Controlling Copas</a></li>
         </ul>
     </li>
@@ -81,14 +84,33 @@ <h2>Reference</h2>
         registered handlers as long as it uses the Copas socket functions.
     </dd>
 
+    <dt><strong><code>copas.autoclose</code></strong></dt>
+    <dd>Constant that controls whether sockets are automatically closed.<br />
+        When a TCP handler function completes and terminates, then the client
+        socket will be automatically closed when <code>copas.autoclose</code> is 
+        truthy (neither <code>nil</code> nor <code>false</code>).
+    </dd>
+
+    <dt><strong><code>copas.finished()</code></strong></dt>
+    <dd>Checks whether anything remains to be done.<br />
+        Returns <code>false</code> when the sockets lists for reading and writing
+        are empty and there is no other (sleeping) task to execute.
+    </dd>
+
     <dt><strong><code>copas.loop(timeout)</code></strong></dt>
-    <dd>Starts the Copas infinite loop accepting client connections for the 
+    <dd>Starts the Copas loop accepting client connections for the 
         registered servers and handling those connections with the corresponding
         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>timeout</code> parameter is optional.
+        The loop returns when <code>copas.finished() == true</code>.
     </dd>
 
+    <dt><strong><code>copas.removeserver(skt)</code></strong></dt>
+    <dd>Removes a server socket from the Copas scheduler. 
+    The socket will be closed to allow the socket to be reused right away after removing the server.
+    </dd>
+
     <dt><strong><code>copas.step(timeout)</code></strong></dt>
     <dd>Executes one copas iteration accepting client connections for the 
         registered servers and handling those connections with the corresponding
@@ -103,7 +125,7 @@ <h2>Reference</h2>
     <dt><strong><code>copas.setErrorHandler(func)</code></strong></dt>
     <dd>Sets the error handling function for the current thread. Any socket
         errors will be forwarded to the handler, which will receive the
-        error message, the thread, and the socket as arguments.</dd>
+        error message, the thread, and the socket as arguments.
     </dd>
 </dl>
 
@@ -112,6 +134,11 @@ <h2>Reference</h2>
 exchange data with other services.</p>
 
 <dl class="reference">
+    <dt><strong><code>copas.connect(skt, address, port)</code></strong></dt>
+    <dd>Connects and transforms a master socket to a client just like LuaSocket
+    <code>socket:connect()</code>. The Copas version does not block and allows
+    the multitasking of the other handlers and threads.
+    </dd>
     <dt><strong><code>copas.flush(skt)</code></strong> (deprecated)</dt>
 
     <dt><strong><code>copas.receive(skt, pattern)</code></strong></dt>
@@ -125,14 +152,9 @@ <h2>Reference</h2>
     is buffered and does not block, allowing the multitasking of the other handlers and threads.
     </dd>
 
-    <dt><strong><code>copas.wrap(skt)</code></strong></dt>
-    <dd>Wraps a LuaSocket socket and returns a Copas socket that implements LuaSocket's API
-    but use Copas' methods <code>copas.send()</code> and <code>copas.receive()</code>
-    automatically.
-    </dd>
-
     <dt><strong><code>copas.sleep(sleeptime)</code></strong></dt>
-    <dd><code>sleeptime</code> (in seconds) is optional and defaults to 0. If <code>sleeptime &lt 0</code>
+    <dd>Pauses the current co-routine. Parameter <code>sleeptime</code> (in seconds) is optional 
+    and defaults to 0. If <code>sleeptime &lt 0</code>
     then it will sleep until explicitly woken by a call to <code>copas.wakeup()</code>.
     </dd>
 
@@ -141,6 +163,12 @@ <h2>Reference</h2>
     the handler function to get the value for <code>co</code>.
     </dd>
 
+    <dt><strong><code>copas.wrap(skt)</code></strong></dt>
+    <dd>Wraps a LuaSocket socket and returns a Copas socket that implements LuaSocket's API
+    but use Copas' methods <code>copas.send()</code> and <code>copas.receive()</code>
+    automatically.
+    </dd>
+
 </dl>
 
 </div> <!-- id="content" -->