Copas - Coroutine Oriented Portable Asynchronous Services for Lua

Reference

NOTE: Some functions require DNS lookups, which is handled internally by LuaSocket. This is being done in a blocking manner. Hence every function that accepts a hostname as an argument (e.g. tcp:connect(), udp:sendto(), etc.) is potentially blocking on the DNS resolving part. So either provide IP addresses (assuming the underlying OS will detect those and resolve locally, non-blocking) or accept that the lookup might block.

Copas dispatcher main functions

The group of functions is relative to the use of the dispatcher itself and are used to register servers and to execute the main loop of Copas:

copas.addserver(server, handler[, timeout]): Adds a new server and its handler to the dispatcher using an optional timeout.
server is a LuaSocket server socket created using socket.bind().
handler is a function that receives a LuaSocket client socket and handles the communication with that client.
timeout is the timeout for blocking I/O in seconds. The handler will be executed in parallel with other threads and the registered handlers as long as it uses the Copas socket functions.
copas.addthread(func [, ...]): Adds a function as a new coroutine/thread to the dispatcher using optional parameters.
The thread will be executed in parallel with other threads and the registered handlers as long as it uses the Copas socket/sleep functions. It returns the created coroutine.
copas.autoclose: Constant that controls whether sockets are automatically closed.
When a TCP handler function completes and terminates, then the client socket will be automatically closed when copas.autoclose is truthy (neither nil nor false).
copas.finished(): Checks whether anything remains to be done.
Returns false when the sockets lists for reading and writing are empty and there is no other (sleeping) task to execute.
copas.loop([timeout]): 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 socket.accept(). The timeout parameter is optional, and is passed to the copas.step() function. The loop returns when copas.finished() == true.
copas.removeserver(skt): 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.
copas.step([timeout]): Executes one copas iteration accepting client connections for the registered servers and handling those connections with the corresponding handlers. When a server accepts a connection, Copas calls the associated handler passing the client socket returned by socket.accept(). The timeout parameter is optional. It returns false when no data was handled (timeout) or true if there was data handled (or alternatively nil + error message in case of errors).
copas.setErrorHandler(func): 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.

Non-blocking data exchange and timer/sleep functions

These are used by the handler functions to exchange data with the clients, and by threads registered with addthread to exchange data with other services.

copas.connect(skt, address, port): Connects and transforms a master socket to a client just like LuaSocket socket:connect(). The Copas version does not block and allows the multitasking of the other handlers and threads.
copas.dohandshake(skt, sslparams): Performs an ssl handshake on an already connected TCP client socket. It returns the new ssl-socket on success, or throws an error on failure.
copas.flush(skt): (deprecated)
copas.handler(connhandler [, sslparams]): Wraps the connhandler function. Returns a new function that wraps the client socket, and (if sslparams is provided) performs the ssl handshake, before calling connhandler.
copas.receive(skt [, pattern]) (TCP) or
copas.receive(size) (UDP): Reads data from a client socket according to a pattern just like LuaSocket socket:receive(). The Copas version does not block and allows the multitasking of the other handlers and threads.
Note: for UDP sockets the size parameter is NOT optional. For the wrapped function socket:receive([size]) it is optional again.
copas.receivefrom(skt [, size]): Reads data from a UDP socket just like LuaSocket socket:receivefrom(). The Copas version does not block and allows the multitasking of the other handlers and threads.
copas.send(skt, data [, i [, j]]) (TCP) or
copas.send(skt, datagram) (UDP): Sends data to a client socket just like socket:send(). The Copas version is buffered and does not block, allowing the multitasking of the other handlers and threads.
copas.sendto(skt, datagram, ip, port): Sends data over a UDP socket just like LuaSocket socket:sendto(). The Copas version does not block and allows the multitasking of the other handlers and threads.
copas.sleep([sleeptime]): Pauses the current co-routine. Parameter sleeptime (in seconds) is optional and defaults to 0. If sleeptime < 0 then it will sleep until explicitly woken by a call to copas.wakeup().
copas.wakeup(co): co is the coroutine to wakeup.
copas.wrap(skt [, sslparams] ): Wraps a LuaSocket socket and returns a Copas socket that implements LuaSocket's API but use Copas' methods like copas.send() and copas.receive() automatically. If the sslparams is provided, then a call to the wrapped skt:connect() method will automatically include the handshake (and in that case connect() might throw an error instead of returning nil+error, see copas.dohandshake()). To use ssl with defaults; provide an empty table.

High level request functions

The last ones are the higher level client functions to perform requests to (remote) servers.

copas.http.request(url [, body]) or
copas.http.request(requestparams)

Performs an http or https request, identical to the LuaSocket and LuaSec implementations, but wrapped in an async operation. As opposed to the original implementations, this one also allows for redirects cross scheme (http to https and viceversa).
Note: https to http redirects are not allowed by default, but only when requestparams.redirect == "all"

copas.ftp.put(url, content) or
copas.ftp.put(requestparams)

Performs an ftp request, identical to the LuaSocket implementation, but wrapped in an async operation.

copas.ftp.get(url) or
copas.ftp.get(requestparams)

Performs an ftp request, identical to the LuaSocket implementation, but wrapped in an async operation.

copas.smtp.send(msgparams)

Sends an smtp request, identical to the LuaSocket implementation, but wrapped in an async operation.

copas.smtp.message(msgt)

Just points to socket.smtp.message, provided so the copas.smtp module is a drop-in replacement for the socket.smtp module

copas.limit.new(max)

Creates and returns a `limitset` that limits the concurrent tasks to max number of running tasks. Eg. 100 http requests, in a set with max == 10, then no more than 10 requests will be performed simultaneously. Only when a request finishes, the next will be started.

limitset:addthread(func [, ...])

Identical to copas.addthread, except that it operates within the limits of the set of running tasks.

limitset:wait()

Will yield until all tasks in the set have finished.