Copas
Coroutine Oriented Portable Asynchronous Services for Lua

## Reference

Copas functions are separated in two groups.

The first group 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(thrd[, ...])`
  Adds a new 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 functions.
`copas.loop(timeout)`
  Starts the Copas infinite 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.
`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).

The second group is used by the handler functions to exchange data with the clients, and by threads registered with `addthread` to exchange data with other services.

`copas.flush(skt)`
  Flushes a client write buffer. `copas.flush()` is called from time to time by `copas.loop()` but it may be necessary to call it from the handler function or one of the threads.
`copas.receive(skt, pattern)`
  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.
`copas.send(skt, data)`
  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.wrap(skt)`
  Wraps a LuaSocket socket and returns a Copas socket that implements LuaSocket's API but use Copas' methods `copas.send()` and `copas.receive()` automatically.

Valid XHTML 1.0!

$Id: reference.html,v 1.16 2009/04/07 21:34:52 carregal Exp $