1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
|
<!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.8.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 (or LuaSystem), <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.8.0</strong> [13/Mar/2025]</dt>
<dd><ul>
<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>
<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>
<li>Fix: <code>queue:finish</code> will return after the last item has been handled, not just popped
(if using workers).</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>
|
