395 lines
18 KiB
HTML
395 lines
18 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
<head>
|
|
<title>Copas - Coroutine Oriented Portable Asynchronous Services for Lua</title>
|
|
<link rel="stylesheet" href="doc.css" type="text/css"/>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
|
|
</head>
|
|
<body>
|
|
<div id="container">
|
|
|
|
<div id="product">
|
|
<div id="product_logo"><a href="http://www.keplerproject.org">
|
|
<img alt="Copas logo" src="copas.png"/>
|
|
</a></div>
|
|
<div id="product_name"><big><strong>Copas</strong></big></div>
|
|
<div id="product_description">Coroutine Oriented Portable Asynchronous Services for Lua</div>
|
|
</div> <!-- id="product" -->
|
|
|
|
|
|
<div id="main">
|
|
|
|
<div id="navigation">
|
|
<h1>Copas</h1>
|
|
<ul>
|
|
<li><strong>Home</strong>
|
|
<ul>
|
|
<li><a href="index.html#status">Status</a></li>
|
|
<li><a href="index.html#download">Download</a></li>
|
|
<li><a href="index.html#dependencies">Dependencies</a></li>
|
|
<li><a href="index.html#history">History</a></li>
|
|
<li><a href="index.html#credits">Credits</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="manual.html">Manual</a>
|
|
</li>
|
|
<li><a href="reference.html">Reference</a></li>
|
|
<li><a href="http://github.com/lunarmodules/copas/">Project</a>
|
|
<ul>
|
|
<li><a href="http://github.com/lunarmodules/copas/issues">Bug Tracker</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="license.html">License</a></li>
|
|
</ul>
|
|
</div> <!-- id="navigation" -->
|
|
|
|
<div id="content">
|
|
|
|
<h2><a name="over"></a>Overview</h2>
|
|
|
|
<p>
|
|
Copas is a dispatcher based on coroutines that can be used for asynchroneous
|
|
networking. For example TCP or UDP based servers. But it also features timers
|
|
and client support for http(s), ftp and smtp requests.
|
|
</p>
|
|
|
|
<p>
|
|
It uses <a href="http://www.cs.princeton.edu/~diego/professional/luasocket/">LuaSocket</a>
|
|
as the interface with the TCP/IP stack and <a href="https://github.com/brunoos/luasec">LuaSec</a> for ssl
|
|
support.
|
|
</p>
|
|
|
|
<p>
|
|
A server or thread registered with Copas should provide a handler for requests and use
|
|
Copas socket functions to send the response.
|
|
Copas loops through requests and invokes the corresponding handlers.
|
|
For a full implementation of a Copas HTTP server you can refer to
|
|
<a href="http://keplerproject.github.io/xavante">Xavante</a> as an example.
|
|
</p>
|
|
|
|
<p>Copas is free software and uses the same <a href="license.html">license</a>
|
|
as Lua 5.1 to 5.4</p>
|
|
|
|
|
|
<h2><a name="status"></a>Status</h2>
|
|
|
|
<p>Current version is 4.7.0 and was developed for Lua 5.1 to 5.4.</p>
|
|
|
|
<h2><a name="download"></a>Download</h2>
|
|
|
|
<p>
|
|
Copas can be downloaded from its
|
|
<a href="http://github.com/lunarmodules/copas">Github</a> page, in
|
|
the "Downloads" tab.
|
|
</p>
|
|
|
|
<p>You can also install Copas using <a href="http://www.luarocks.org">LuaRocks</a>:</p>
|
|
|
|
<pre class="example">
|
|
luarocks install copas
|
|
</pre>
|
|
|
|
|
|
<h2><a name="dependencies"></a>Dependencies</h2>
|
|
|
|
<p>Copas depends on
|
|
LuaSocket, <a href="http://keplerproject.github.io/coxpcall/">Coxpcall</a> (only when using Lua 5.1), and (optionally) LuaSec.
|
|
</p>
|
|
|
|
<h2><a name="history"></a>History</h2>
|
|
|
|
<dl class="history">
|
|
<dt><strong>Copas 4.7.x</strong> [unreleased]</dt>
|
|
<dd><ul>
|
|
<li>Fix: <code>copas.removethread</code> would not remove a sleeping thread immediately (it would not execute, but
|
|
would prevent the Copas loop from exiting until the timer expired).</li>
|
|
</ul></dd>
|
|
|
|
<dt><strong>Copas 4.7.0</strong> [15/Jan/2023]</dt>
|
|
<dd><ul>
|
|
<li>Fix: windows makefile didn't include all submodules.</li>
|
|
<li>Fix: creating a new timer with a bad delay setting would throw a bad error message.</li>
|
|
<li>Refactor: submodules are now part of copas (lazily loaded) and do not need to be required anymore</li>
|
|
<li>Feat: runtime script added to directly run copas based code</li>
|
|
<li>Fix: improved socket wrapper for lacking LuaSec methods (<code>setoption, getoption, getpeername, getsockname</code>)</li>
|
|
<li>Feat: added LuaSec methods to wrapper (<code>getalpn, getsniname</code>)</li>
|
|
</ul></dd>
|
|
|
|
<dt><strong>Copas 4.6.0</strong> [30/Dec/2022]</dt>
|
|
<dd><ul>
|
|
<li>Added: for timeouts in copas, lock, semaphore, and queue, allow <code>math.huge</code>
|
|
to specify no timeout/wait forever. Using <code>math.huge</code> over long timeouts will
|
|
reduce pressure on the timer-wheel.</li>
|
|
<li>Refactor: increase ringsize (timer-wheel) from 1 minute to 1 day to reduce timer-wheel pressure.</li>
|
|
</ul></dd>
|
|
|
|
<dt><strong>Copas 4.5.0</strong> [18/Dec/2022]</dt>
|
|
<dd><ul>
|
|
<li>Added: <code>copas.status</code> got an extra parameter to track more detailed stats.</li>
|
|
<li>Fix: queue workers would not properly handle falsy items in the queue. The worker would
|
|
exit instead of handle the item.</li>
|
|
<li>Fix: a non-reentrant lock should block instead of returning an error when entered again.</li>
|
|
<li>Fix: finishing a queue would not honour the timeout.</li>
|
|
<li>Refactor: more manual cleanup instead of relying on weak-tables.</li>
|
|
</ul></dd>
|
|
|
|
<dt><strong>Copas 4.4.0</strong> [23/Oct/2022]</dt>
|
|
<dd><ul>
|
|
<li>Fix: an error in the timer callback would kill the timer.</li>
|
|
<li>Added: <code>copas.geterrorhandler</code> to retrieve the active errorhandler.</li>
|
|
<li>Added: option <code>errorhandler</code> for timer objects.</li>
|
|
<li>Added: <code>copas.pause</code> and <code>copas.pauseforever</code> to replace <code>copas.sleep</code>. The latter
|
|
method can accidentally sleep-forever if time arithmetic returns a negative result.</li>
|
|
<li>Added: <code>copas.status</code> which returns an object with number of tasks/timers/sockets.</li>
|
|
<li>Change: renamed <code>copas.setErrorHandler</code> to <code>copas.seterrorhandler</code>.</li>
|
|
<li>Change: renamed <code>copas.useSocketTimeoutErrors</code> to <code>copas.usesockettimeouterrors</code>.</li>
|
|
</ul></dd>
|
|
|
|
<dt><strong>Copas 4.3.2</strong> [03/Oct/2022]</dt>
|
|
<dd><ul>
|
|
<li>Fix: error handler for timeouts. Underlying <a href="https://github.com/keplerproject/coxpcall/issues/18">
|
|
bug is in coxpcall</a>, and hence this only applies to PuC Lua 5.1.</li>
|
|
</ul></dd>
|
|
|
|
<dt><strong>Copas 4.3.1</strong> [21/Sep/2022]</dt>
|
|
<dd><ul>
|
|
<li>Fix: with Lua 5.1 the timeouts would resume the wrapped (by coxpcall)
|
|
coroutines, instead of the original ones. Causing errors to bubble up one
|
|
level too many.
|
|
</li>
|
|
</ul></dd>
|
|
|
|
<dt><strong>Copas 4.3.0</strong> [19/Sep/2022]</dt>
|
|
<dd><ul>
|
|
<li>Fix: when the loop is idle, do an occasional GC to clean out any lingering
|
|
non-closed sockets. This could prevent the loop from exiting.</li>
|
|
<li>Fix: in debug mode very large data is now truncated when displayed.</li>
|
|
<li>Fix: the receive methods could starve other threads on high-throughput.</li>
|
|
<li>Change: order of <code>copas.addnamedthread</code> args.</li>
|
|
<li>Fix: <code>copas.receivepartial</code> could return early with no data received
|
|
if the `prefix` parameter was specified.</li>
|
|
<li>Change: renamed <code>copas.receivePartial</code> to <code>copas.receivepartial</code>.</li>
|
|
<li>Added: <code>sock:receivepartial</code> to better process streaming TCP data.</li>
|
|
<li>fix: <code>copas.receivepartial</code> is now documented.</li>
|
|
<li>fix: <code>copas.http</code> was missing some error handling.</li>
|
|
<li>fix: Copas timeouts when receiving/sending would not return partial results,
|
|
or last bytes sent.</li>
|
|
</ul></dd>
|
|
|
|
<dt><strong>Copas 4.2.0</strong> [06/Sep/2022]</dt>
|
|
<dd><ul>
|
|
<li>Change: pick up datagram size from newer LuaSocket versions.</li>
|
|
<li>Fix: non-recurring timer can now be armed again from its own handler.</li>
|
|
<li>Added: calling on the module table now invokes the <code>copas.loop</code> method.</li>
|
|
</ul></dd>
|
|
|
|
<dt><strong>Copas 4.1.0</strong> [25/Aug/2022]</dt>
|
|
<dd><ul>
|
|
<li>Fix: handle errors thrown by the error handlers themselves.</li>
|
|
<li>Deps: Bump timerwheel to 1.0 (no changes, just a small fix)</li>
|
|
<li>Added: <code>copas.gettraceback</code>, previously internal to the default error handler,
|
|
now exposed to make it easier to write proper error handlers</li>
|
|
<li>Added: http-request now takes a timeout setting, previously it would always use the default value
|
|
of 30 seconds.</li>
|
|
<li>Added: the previously internal function for generating a TCP socket in the http-request module,
|
|
is now exported as <code>http.getcreatefunc()</code>. This allows to capture the socket used by the
|
|
request. When using streaming responses, for example with server-sent events, this can be used to modify
|
|
the timeouts, or for closing the stream.</li>
|
|
<li>Fix: empty queues were not destroyed properly and could prevent Copas from exiting</li>
|
|
</ul></dd>
|
|
|
|
<dt><strong>Copas 4.0.0</strong> [29/Jul/2022]</dt>
|
|
<dd><ul>
|
|
<li>[breaking] Change: removed the "limitset". Its functionality can easily be recreated with
|
|
the new "queue" class, which is a better abstraction.</li>
|
|
<li>[breaking] Change: threads added through <code>copas.addthread</code> or
|
|
<code>copas.addnamedthread</code> will now be "scheduled", instead of immediately started.</li>
|
|
<li>Fixed: yielding to the Copas scheduler from user-code now throws a proper error and
|
|
no longer breaks the loop. Breaking the loop could also happen if a thread returned with
|
|
at least 2 return values.</li>
|
|
<li>Fixed: wrongly auto-closing sockets. Upon exiting a coroutine, sockets would be automatically
|
|
closed. This should only be the case for accepted TCP connections on a TCP server socket. This caused issues
|
|
for sockets shared between threads.<br />
|
|
[breaking]: this changes behavior, auto-close is now determined when accepting the connection, and no longer when
|
|
terminating the handler thread. This will only affect users that dynamically change <code>copas.autoclose</code>
|
|
at runtime.</li>
|
|
<li>Fixed: http requests would not set SNI defaults. Setting fields <code>protocol</code>,
|
|
<code>options</code>, and <code>verify</code> directly on the http options table is now deprecated. Instead
|
|
specify <code>sslparams</code>, similar to other SSL/TLS functions.</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>
|
|
<li><code>copas.debug.socket()</code> to enable debug logging for socket methods (experimental).</li>
|
|
</ul>
|
|
</li>
|
|
</ul></dd>
|
|
|
|
<dt><strong>Copas 3.0.0</strong> [12/Nov/2021]</dt>
|
|
<dd><ul>
|
|
<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: <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 <code>copas.timeout()</code></li>
|
|
<li>Added: option to override the default errorhandler, and fixes to the handler</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 <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 <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>
|
|
|
|
<dt><strong>Copas 2.0.2</strong> [2017]</dt>
|
|
<dd><ul>
|
|
<li>Added: <code>copas.running</code> flag</li>
|
|
<li>Fixed: fix for http request #53 (Peter Melnichenko)</li>
|
|
<li>Added: extra parameter <code>keep_open</code> for the <code>removeserver()</code> method (Hisham Muhammad)</li>
|
|
<li>Change: tweaked makefile with a <code>DESTDIR</code> variable (Richard Leitner)</li>
|
|
</ul></dd>
|
|
|
|
<dt><strong>Copas 2.0.1</strong> [2016]</dt>
|
|
<dd><ul>
|
|
<li>Added: support for Lua 5.3 (no code changes, just rockspec update)</li>
|
|
<li>Fixed: yield across c boundary error (by Peter Melnichenko)</li>
|
|
<li>Fixed: bug in wrappers for <code>setoption()</code> and <code>shutdown()</code> (reported by Rob Probin)</li>
|
|
</ul></dd>
|
|
|
|
<dt><strong>Copas 2.0.0</strong> [2015]</dt>
|
|
<dd><ul>
|
|
<li>Added: <code>removeserver()</code> function to remove servers from the scheduler (by Paul Kulchenko)</li>
|
|
<li>Added: client requests for http(s), ftp, and smtp (like LuaSocket/LuaSec, but async)</li>
|
|
<li>Added: transparent async support (handshake, and send/receive) for ssl using LuaSec</li>
|
|
<li>Added: <code>handler()</code> as a convenience for full copas and ssl wrapping</li>
|
|
<li>[breaking] Change: the loop now exits when there is nothing more to do</li>
|
|
<li>[breaking] Change: dummy first argument to new tasks removed</li>
|
|
<li>Fixed: completed the socket wrappers, missing functions were added</li>
|
|
<li>Fixed: connect issue, <code>step()</code> errorring out instead of returning <code>nil + error</code></li>
|
|
<li>Fixed: UDP sockets being auto closed</li>
|
|
<li>Fixed: the <code>receivePartial</code> function for http request support (by Paul Kulchenko)</li>
|
|
</ul></dd>
|
|
|
|
<dt><strong>Copas 1.2.1</strong> [2013]</dt>
|
|
<dd><ul>
|
|
<li>Fixed bad version constant</li>
|
|
<li>Fixed timer issue</li>
|
|
<li>updated documentation</li>
|
|
</ul></dd>
|
|
|
|
<dt><strong>Copas 1.2.0</strong> [2013]</dt>
|
|
<dd><ul>
|
|
<li>Support for Lua 5.2</li>
|
|
<li>UDP support</li>
|
|
<li>suspending threads</li>
|
|
<li>other minor updates</li>
|
|
</ul></dd>
|
|
|
|
<dt><strong>Copas 1.1.6</strong> [18/Mar/2010]</dt>
|
|
<dd><ul>
|
|
<li>Now checks to see if socket.http was required before copas
|
|
</li>
|
|
</ul></dd>
|
|
|
|
<dt><strong>Copas 1.1.5</strong> [07/Apr/2009]</dt>
|
|
<dd><ul>
|
|
<li>Fixed bug reported by Sam Roberts on the
|
|
Kepler list
|
|
(found due to Xavante locking up on some POST requests)
|
|
</li>
|
|
</ul></dd>
|
|
|
|
<dt><strong>Copas 1.1.4</strong> [10/Dec/2008]</dt>
|
|
<dd><ul>
|
|
<li>Fixed bug [#5372]
|
|
- copas.connect is semi-broken (found by Gary NG)</li>
|
|
</ul></dd>
|
|
|
|
<dt><strong>Copas 1.1.3</strong> [19/May/2008]</dt>
|
|
<dd><ul>
|
|
<li>Using <code>copcall</code> instead of <code>pcall</code> in <code>socket.protect</code>
|
|
(feature request [#5274] by Gary NG)</li>
|
|
</ul></dd>
|
|
|
|
<dt><strong>Copas 1.1.2</strong> [15/May/2008]</dt>
|
|
<dd><ul>
|
|
<li>Fixed Bug [#4249]
|
|
- bugs in copas.receive (found by Gary NG)</li>
|
|
</ul></dd>
|
|
|
|
<dt><strong>Copas 1.1.1</strong> [13/Aug/2007]</dt>
|
|
<dd>
|
|
<ul>
|
|
<li>Compatible with Lua 5.1</li>
|
|
<li>Refactored by Thomas Harning Jr. (for more details check
|
|
Bug 766)</li>
|
|
<li>Patch by Gary NG concerning the handling of stopped sockets</li>
|
|
</ul>
|
|
|
|
</dd>
|
|
|
|
<dt><strong>Copas 1.1</strong> [20/Sep/2006]</dt>
|
|
<dd><ul>
|
|
<li><a href="reference.html">copas.addthread()</a> added</li>
|
|
</ul></dd>
|
|
|
|
<dt><strong><a href="http://www.keplerproject.org/copas/1.0">Copas 1.0</a></strong> [17/May/2005]</dt>
|
|
<dd><ul>
|
|
<li><a href="reference.html">copas.step()</a> added</li>
|
|
</ul></dd>
|
|
|
|
<dt><strong>Copas 1.0 Beta</strong>[17/Feb/2005]</dt>
|
|
<dd><ul>
|
|
<li>First public version</li>
|
|
</ul></dd>
|
|
</dl>
|
|
|
|
<h2><a name="credits"></a>Credits</h2>
|
|
|
|
<p>Copas was designed and implemented by André Carregal and
|
|
Javier Guerra as part of the
|
|
<a href="http://www.keplerproject.org">Kepler Project</a> which
|
|
holds its copyright. Copas development had significative contributions from Diego Nehab,
|
|
Mike Pall, David Burgess, Leonardo Godinho, Thomas Harning Jr. and Gary NG.</p>
|
|
|
|
|
|
<h2><a name="contact"></a>Contact us</h2>
|
|
|
|
<p>For more information please
|
|
<a href="mailto:info-NO-SPAM-THANKS@keplerproject.org">contact us</a>.
|
|
Comments are welcome!</p>
|
|
|
|
<p>
|
|
You can also reach other Kepler developers and users on the Kepler Project
|
|
<a href="https://groups.google.com/forum/#!forum/kepler-project">mailing list</a>.
|
|
</p>
|
|
|
|
</div> <!-- id="content" -->
|
|
|
|
</div> <!-- id="main" -->
|
|
|
|
<div id="about">
|
|
<p><a href="http://validator.w3.org/check?uri=referer">Valid XHTML 1.0!</a></p>
|
|
</div> <!-- id="about" -->
|
|
|
|
</div> <!-- id="container" -->
|
|
</body>
|
|
</html>
|