Copas - Coroutine Oriented Portable Asynchronous Services for Lua

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.

### Getting started examples

Example for a server handling incoming connections:

    local copas = require("copas")
    local socket = require("socket")

    local address = "*"
    local port = 20000
    local ssl_params = {
        wrap = {
            mode = "server",
            protocol = "any",  -- not really secure...
        },
    }

    local server_socket = assert(socket.bind(address, port))

    local function connection_handler(skt)
        local data, err = skt:receive()

        -- do something

    end

    copas.addthread(function()
        copas.addserver(server_socket, copas.handler(connection_handler,
            ssl_params), "my_TCP_server")
        copas.waitforexit()
        copas.removeserver(server_socket)
    end)

    copas()

Example for a client making a connection to a remote server:

    local copas = require("copas")
    local socket = require("socket")

    copas.addthread(function()
        local port = 20000
        local host = "somehost.com"
        local ssl_params = {
            wrap = {
                mode = "client",
                protocol = "any",  -- not really secure...
            },
        }

        local sock = copas.wrap(socket.tcp(), ssl_params)
        copas.setsocketname("my_TCP_client", sock)
        assert(sock:connect(host, port))

        local data, err = sock:receive("*l")

        -- do something

    end)

    copas()

### 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([init_func, ][timeout])`

  This is a shortcut to `copas.loop`.

`copas.addserver(server, handler [, timeout [, name]])`

  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. The handler will be executed in parallel with other threads and registered handlers as long as it uses the Copas socket functions.

  `timeout` is the timeout in seconds. Upon accepting connections, the timeout will be inherited by TCP client sockets (only applies to TCP).

  `name` is the internal name to use for this socket. The handler threads and (in case of TCP) the incoming client connections will get a name derived from the server socket.

  - TCP: client-socket name: `"[server_name]:client_XX"` and the handler thread `"[server_name]:handler_XX"` where `XX` is a sequential number matching between the client-socket and handler.
  - UDP: the handler thread will be named `"[server_name]:handler"`
`coro = copas.addnamedthread(name, func [, ...])`

  Same as `copas.addthread`, but also names the new thread.

`coro = copas.addthread(func [, ...])`

  Adds a function as a new coroutine/thread to the dispatcher. The optional parameters will be passed to the function `func`.

  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`

  Boolean that controls whether sockets are automatically closed (defaults to `true`). This only applies to incoming connections accepted on a TCP server socket.

  When a TCP handler function completes and terminates, then the client socket will automatically be closed when `copas.autoclose` is truthy.

`copas.exit()`

  Sets a flag that the application is intending to exit. After calling this function `copas.exiting()` will be returning `true`, and all threads blocked on `copas.waitforexit()` will be released.

  Copas itself will call this function when `copas.finished()` returns `true`.

`bool = copas.exiting()`

  Returns a flag indicating whether the application is supposed to exit. Returns `false` until after `copas.exit()` has been called, after which it will start returning `true`.

  Clients should check whether they are to cease their operation and exit. They can do this by checking this flag, or by registering a task waiting on `copas.waitforexit()`. Clients should cancel pending work and close sockets when an exit is announced, otherwise Copas will not exit.

`bool = copas.finished()`

  Checks whether anything remains to be done.

  Returns `false` when the socket lists for reading and writing are empty and there is not another (sleeping) task to execute.

  NOTE: when tasks or sockets have been scheduled/setup this function will return `true` even if the loop has not yet started. See also `copas.running`.

`func = copas.geterrorhandler([coro])`

  Returns the currently active errorhandler function for the coroutine (either the explicitly set errorhandler, or the default one). `coro` will default to the currently running coroutine if omitted.

`string = copas.getsocketname(skt)`

  Returns the name for the socket.

`string = copas.getthreadname([co])`

  Returns the name for the coroutine/thread. If not given defaults to the currently running coroutine.

`number = copas.gettime()`

  Returns the (fractional) number of seconds since the epoch. This directly maps to either the LuaSocket or LuaSystem implementation of `gettime()`.

`string = copas.gettraceback([msg], [co], [skt])`

  Creates a traceback (string). Can be used from custom errorhandlers to create a proper trace. See `copas.seterrorhandler`.

`func = 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`.

  See `sslparams` definition below.

`copas.loop([init_func, ][timeout])`

  Starts the Copas loop accepting client connections for the registered servers and handling those connections with the corresponding handlers. Calling on the module table itself is a shortcut to this function. Every time a server accepts a connection, Copas calls the associated handler passing the client socket returned by `socket.accept()`.

  The `init_func` function is an optional initialization function that runs as a Copas thread (with name `"copas_initializer"`). The `timeout` parameter is optional, and is passed to the `copas.step()` function.

  The loop returns when `copas.finished() == true`.

`result = copas.removeserver(skt [, keep_open])`

  Removes a server socket from the Copas scheduler. By default, the socket will be closed to allow the socket to be reused right away after removing the server. If `keep_open` is `true`, the socket is removed from the scheduler but it is not closed.

  Returns the result of `skt:close()` or `true` if the socket was kept open.

`copas.removethread(coroutine)`

  Removes a coroutine added to the Copas scheduler. Takes a `coroutine` created by `copas.addthread()` and removes it from the dispatcher the next time it tries to resume. If `coroutine` isn't registered, it does nothing.

`copas.running`

  A flag set to `true` when `copas.loop()` starts, and reset to `false` when the loop exits. See also `copas.finished()`.

`copas.seterrorhandler([func], [default])`

  Sets the error handling function for the current thread. Any errors will be forwarded to this handler, it will receive the error, coroutine, and socket as arguments; `function(err, co, skt)`. See the Copas source code on how to deal with the arguments when implementing your own, and check `copas.gettraceback`.

  If `func` is omitted, then the error handler is cleared (restores the default handler for this coroutine).

  If `default` is truthy, then the handler will become the new default, used for all threads that do not have their own set (in this case `func` must be provided).

`copas.setsocketname(name, skt)`

  Sets the name for the socket.

`copas.setthreadname(name [,co])`

  Sets the name for the coroutine/thread. `co` defaults to the currently running coroutine.

`copas.waitforexit()`

  This will block the calling coroutine until the `copas.exit()` function is called. Clients should check whether they are to cease their operation and exit. They can do this by waiting on this call, or by checking the `copas.exiting()` flag. Clients should cancel pending work and close sockets when an exit is announced, otherwise Copas will not exit.

`skt = 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 socket was already wrapped, then it will not wrap it again.

  If the `sslparams` is provided, then a call to the wrapped `sock:connect()` method will automatically include the handshake (and in that case `connect()` might throw an error instead of returning nil+error, see `copas.dohandshake()`).

  See `sslparams` definition below.

`sslparams`

  This is the data-structure that is passed to the `copas.handler`, and `copas.wrap` functions. Passing the structure will allow Copas to take care of the entire TLS handshake process.

  The structure is set up to mimic the LuaSec functions for the handshake.

      {
        wrap = table | context,    -- parameter to LuaSec 'wrap()'
        sni = {                    -- parameters to LuaSec 'sni()'
          names = string | table   --   1st parameter
          strict = bool            --   2nd parameter
        }
      }

### 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.

`number = copas.pause([delay])`

  Pauses the current co-routine. Parameter `delay` (in seconds) is optional and defaults to 0. If `delay <= 0` then it will pause for 0 seconds.

  Returns the time slept (in seconds).

`number = copas.pauseforever()`

  Pauses the current co-routine until explicitly woken by a call to `copas.wakeup()`.

  Returns the time slept (in seconds).

`copas.sleep([sleeptime])`

  Deprecated: use `copas.pause` and `copas.pauseforever` instead.

`ok, err = copas.wakeup(co)`

  Immediately wakes up a coroutine that was sleeping or sleeping-forever. `co` is the coroutine to wakeup, see `copas.pause()` and `copas.pauseforever()`.

  Returns `true` on success, or `nil + "not sleeping"` if the coroutine wasn't sleeping (eg. it already finished, was already woken up, or was canceled through `copas.removethread()`).

`bool = copas.issleeping(co)`

  Checks whether `co` is currently sleeping (paused or paused-forever), without waking it up. Useful for code that queues coroutines and later needs to tell a still-legitimately-waiting coroutine apart from one that was canceled in the meantime (eg. through `copas.removethread()`) while it was queued.

`sock:close()`

  Equivalent to the LuaSocket method (after `copas.wrap`).

`sock:connect(address, port)`

  Non-blocking equivalent to the LuaSocket method (after `copas.wrap`).

  If `sslparams` was provided when wrapping the socket, the `connect` method will also perform the full TLS handshake. So after `connect` returns the connection will be secured.

`sock:dohandshake(sslparams)`

  Non-blocking quivalent to the LuaSec method (after `copas.wrap`). Instead of using this method, it is preferred to pass the `sslparams` to the functions `copas.handler` (for incoming connections) and `copas.wrap` (for outgoing connections), which then ensures that the connection will automatically be secured when started.

  Unlike the LuaSec method, this does not return `nil + error` on failure; it throws an error instead (see `copas.dohandshake()`).

`sock:receive([pattern [, prefix]])`

  Non-blocking equivalent to the LuaSocket method (after `copas.wrap`). Please see `sock:receivepartial` for differences with LuaSocket, especially when using the `"*a"` pattern.

  Security note: the default pattern, `"*l"`, has no maximum line length. Just like LuaSocket and Lua's own file-io, it will keep buffering data until a newline, end-of-file, or a socket error is encountered. Because the Copas timeout resets on every chunk received (see the timeout note above), a peer that trickles in bytes without ever sending a newline is not timed out either, so the buffer keeps growing for as long as the peer stays connected. Do not use the default `receive()`/`"*l"` pattern directly on data from an untrusted or remote peer unless the protocol itself guarantees a bounded line length. For untrusted input, read a bounded/known size (a numeric pattern), or use `receivepartial` and enforce your own cumulative size limit, closing the connection when it is exceeded.

`sock:receivefrom([size])`

  Reads data from a UDP socket just like LuaSocket, but non-blocking. `socket:receivefrom()`.

`sock:receivepartial([pattern [, prefix]])`

  This method is the same as the `receive` method, the difference being that this method will return on any data received, even if the specified pattern was not yet satisfied.

  When using delimited formats or known byte-size (pattern is `"*l"` or a number) the regular `receive` method will usually be fine. But when reading a stream with the `"*a"` pattern the `receivepartial` method should be used.

  The reason for this is the difference in timeouts between Copas and LuaSocket. The Copas timeout will apply on each underlying socket read/write operation. So on every chunk received Copas will reset the timeout. So if reading pattern `"*a"` with a 10 second timeout, and the sender sends a stream of data (unlimited size), in 1kb chunks, with 5 seconds intervals, then there will never be a timeout when using `receive`, and hence the call would never return.

  If using `receivepartial` with the `"*a"` pattern, the (repeated) call would return the 1kb chunks, with a `"timeout"` error.

`sock:send(data [, i [, j]])`

  Non-blocking equivalent to the LuaSocket method (after `copas.wrap`).

`sock:settimeout([timeout])`

  Sets the timeouts (in seconds) for a socket (after `copas.wrap`). The default is to not have a timeout and wait indefinitely. If a timeout is hit, the operation will return `nil + "timeout"`. This method is compatible with LuaSocket, but sets all three timeouts to the same value.

  Behaviour:

  - `nil`: block indefinitely
  - `number < 0`: block indefinitely
  - `number >= 0`: timeout value in seconds
  Important: this behaviour is the same as LuaSocket, but different from `sock:settimeouts`, where `nil` means 'do not change' the timeout.
`sock:settimeouts([connect], [send], [receive])`

  Sets the timeouts (in seconds) for a socket (after `copas.wrap`). A positive number sets the timeout, a negative number removes the timeout, and `nil` will not change the currently set timeout. The default is to not have a timeout and wait indefinitely.

  Behaviour:

  - `nil`: do not change the current setting
  - `number < 0`: block indefinitely
  - `number >= 0`: timeout value in seconds
  Important: this behaviour is different from `sock:settimeout`, where `nil` means 'wait indefinitely'.

  If a timeout is hit, the operation will return `nil + "timeout"`.

`sock:sni(...)`

  Equivalent to the LuaSec method (after `copas.wrap`). Instead of using this method, it is preferred to pass the `sslparams` to the functions `copas.handler` (for incoming connections) and `copas.wrap` (for outgoing connections), which then ensures that the connection will automatically be secured when started.

`future:cancel()`

  Cancels a pending task. Returns `true` if the task was successfully cancelled, or `false` if the task had already completed.

  Any coroutines blocked on `future:get()` will be released immediately and return `false + "cancelled"`. Subsequent calls to `future:try()` will return `future.ERROR, "cancelled"`.

`ok [, results...] = future:get()`

  Waits for the task to complete and returns its results. If the task has already completed, returns immediately. Can be called multiple times; subsequent calls return the cached result without blocking.

  Returns like `pcall`: on success returns `true` followed by the task's return values; on failure returns `false` followed by the error message.

  The future is also callable: `future()` is equivalent to `future:get()`.

`status [, results...] = future:try()`

  Non-blocking check on the future's status. Returns one of three outcomes:

  - `future.PENDING` (`false`) — the task has not yet completed.
  - `future.SUCCESS` (`true`), results... — the task completed successfully, followed by its return values.
  - `future.ERROR` (`"error"`), errmsg — the task failed or was cancelled, followed by the error message.

  `future.PENDING` is the only falsy value, so a simple truthiness check indicates whether the task is done (whether successfully or with an error).

`future.ERROR`, `future.PENDING`, `future.SUCCESS`

  Status constants for use with `future:try()`. Their values are `"error"`, `false`, and `true` respectively.

`future = copas.future.addnamedthread(name, func, ...)`

  Equivalent to `copas.addnamedthread` but returns a future instead of the coroutine.

`future = copas.future.addthread(func, ...)`

  Equivalent to `copas.addthread` but returns a future instead of the coroutine.

`lock:destroy()`

  Will destroy the lock and release all waiting threads. The result for those threads will be `nil + "destroyed" + wait_time`, any new call on any method will return `nil + "destroyed"` from here on.

`lock:get([timeout])`

  Will try and acquire the lock. The optional `timeout` can be used to override the timeout value set when the lock was created.

  If the lock is not available, the coroutine will yield until either the lock becomes available, or it times out. The one exception is when `timeout` is 0, then it will immediately return without yielding. If the timeout is set to `math.huge`, then it will wait forever.

  Upon success, it will return the `wait-time` in seconds. Upon failure it will return `nil + error + wait-time`. Upon a timeout the error value will be "timeout".

`copas.lock.new([timeout], [not_reentrant])`

  Creates and returns a new lock. The `timeout` specifies the default timeout for the lock in seconds, and defaults to 10 (set it to `math.huge` to wait forever).

  By default the lock is re-entrant, except if `not_reentrant` is set to a truthy value.

`lock:release()`

  Releases the currently held lock.

  Returns `true` or `nil + error`.

`queue:add_worker(func)`

  Adds a worker that will handle whatever is passed into the queue. Can be called multiple times to add more workers. The function `func` is wrapped and added as a copas thread. The threads automatically exit when the queue is destroyed.

  Worker function signature: `function(item)` (Note: worker functions run unprotected, so wrap code in an (x)pcall if errors are expected, otherwise the worker will exit on an error, and queue handling will stop).

  Returns the coroutine added, or `nil+"destroyed"`.

`queue:destroy()`

  Destroys a queue immediately. Abandons what is left in the queue. Releases all waiting calls to `queue:pop()` with `nil+"destroyed"`. Returns `true`, or `nil+"destroyed"`.

`queue:finish([timeout], [no_destroy_on_timeout])`

  Finishes a queue. Calls `queue:stop()` and then waits for the queue to run empty (and be destroyed) before returning.

  When using "workers" via `queue:add_worker()` then this method will return after the worker has finished processing the popped item. When using your own threads and calling `queue:pop()`, then this method will return after the last item has been popped, but not necessarily also processed.

  The `timeout` defaults to 10 seconds (the default timeout value for a lock), `math.huge` can be used to wait forever.

  Parameter `no_destroy_on_timeout` indicates if the queue is not to be forcefully destroyed on a timeout (abandonning what ever is left in the queue).

  Returns `true`, or `nil+"timeout"`, or `nil+"destroyed"`.

`queue:get_size()`

  Gets the number of items in the queue currently. Returns `number` or `nil + "destroyed"`.

`queue:get_workers()`

  Returns a list/array of current workers (coroutines) handling the queue (only the workers added by `queue:add_worker()`, and still active, will be in the list). Returns `list` or `nil + "destroyed"`.

`queue.name`

  A field set to name of the queue. See `copas.queue.new()`.

`copas.queue.new([options])`

  Creates and returns a new queue. The `options` table has the following fields:

  - `options.name`: (optional) the name for the queue, the default name will be `"copas_queue_XX"`. The name will be used to name any workers added to the queue using `queue:add_worker()`, their name will be `"[queue_name]:worker_XX"`
`queue:pop([timeout])`

  Will pop an item from the queue. If there are no items in the queue it will yield until there are or a timeout happens (exception is when `timeout == 0`, then it will not yield but return immediately, be careful not to create a hanging loop!).

  Timeout defaults to the default time-out of a semaphore. If the timeout is `math.huge` then it will wait forever.

  Returns an item, or `nil+"timeout"`, or `nil+"destroyed"`. Since an item can be `nil`, make sure to check for the error message to detect errors.

`queue:push(item)`

  Will push a new item in the queue. Item can be any type, including 'nil'.

  Returns `true` or `nil + "destroyed"`.

`queue:stop()`

  Instructs the queue to stop, and returns immediately. It will no longer accept calls to `queue:push()`, and will call `queue:destroy()` once the queue is empty.

  Returns `true` or `nil + "destroyed"`.

`semaphore:destroy()`

  Will destroy the sempahore and release all waiting threads. The result for those threads will be `nil + "destroyed"`, any new call on any method will return `nil + "destroyed"` from here on.

`semaphore:get_count()`

  Returns the number of resources currently available in the semaphore.

`semaphore:get_wait()`

  Returns the total number of resources requested by all currently waiting threads minus the available resources. Such that `sempahore:give(semaphore:get_wait())` will release all waiting threads and leave the semaphore with 0 resources (provided they are within the `max` limits). If there are no waiting threads then the result will be 0, and the number of resources in the semaphore will be greater than or equal to 0.

`semaphore:give([given])`

  Gives resources to the semaphore. Parameter `given` is the number of resources given to the semaphore, if omitted it defaults to 1. `given` must be a finite number greater than or equal to 0, otherwise an error is thrown.

  If the total resources in the semaphore exceed the maximum, then it will be capped at the maximum. In that case the result will be `nil + "too many"`. To release every currently waiting thread regardless of `max`, use `semaphore:release_all()` instead.

`copas.semaphore.new(max, [start], [timeout])`

  Creates and returns a new semaphore (fifo).

  `max` specifies the maximum number of resources the semaphore can hold. Use `math.huge` to not limit the number of resources. The optional `start` parameter (default 0) specifies the number of resources upon creation.

  The `timeout` specifies the default timeout for the semaphore in seconds, and defaults to 10 (`math.huge` can be used to wait forever).

`semaphore:release_all()`

  Releases every currently queued waiter, regardless of `max`. Unlike `semaphore:give(semaphore:get_wait())`, which is capped at `max` and can strand waiters beyond it, this feeds the required amount into `give()` in `max`-sized chunks until nobody is left waiting.

`semaphore:take([requested], [timeout])`

  Takes resources from the semaphore. Parameter `requested` is the number of resources requested from the semaphore, if omitted it defaults to 1. `requested` must be a number greater than or equal to 1, otherwise an error is thrown.

  If not enough resources are available it will yield and wait until enough resources are available, or a timeout occurs. The exception is when `timeout` is set to 0, in that case it will immediately return without yielding if there are not enough resources available.

  The optional `timeout` parameter can be used to override the default timeout as set upon semaphore creation. If the timeout is `math.huge` then it will wait forever.

  Returns `true` upon success or `nil + "timeout"` on a timeout. In case more resources are requested than maximum available the error will be `"too many"`.

`copas.timer.new(options)`

  Creates and returns an (armed) timer object. The `options` table has the following fields;

  - `options.name` (optional): the name for the timer, the default name will be `"copas_timer_XX"`. The name will be used to name the timer thread.
  - `options.recurring` (optional, default `false`): boolean
  - `options.delay`: expiry delay in seconds
  - `options.initial_delay` (optional): see `timer:arm()`
  - `options.params` (optional): an opaque value that is passed to the callback upon expiry
  - `options.callback`: is the function to execute on timer expiry. The callback function has `function(timer_obj, params)` as signature, where `params` is the value initially passed in `options.params`
  - `options.errorhandler` (optional): a Copas errorhandler function (see `copas.seterrorhandler` for the signature.
`timer:arm([initial_delay])`

  Arms a timer that was previously cancelled or exited (arming a non-recurring timer again from its own handler is explicitly supported). Returns the timer.

  The optional parameter `initial_delay`, determines the first delay. For example a recurring timer with `delay = 5`, and `initial_delay = 0` will execute immediately and then recur every 5 seconds.

`timer:cancel()`

  Will cancel the timer. If the callback is currently in progress then the callback won't be cancelled, just new invocations will be prevented.

### 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).

  Options:

  - `options.url`: the URL for the request.
  - `options.sink` (optional): the LTN12 sink to pass the body chunks to.
  - `options.method` (optional, default "GET"): the http request method.
  - `options.headers` (optional): any additional HTTP headers to send with the request. Hash-table, header-values by header-names.
  - `options.source` (optional): simple LTN12 source to provide the request body. If there is a body, you need to provide an appropriate "content-length" request header field, or the function will attempt to send the body as "chunked" (something few servers support). Defaults to the empty source
  - `options.step` (optional): LTN12 pump step function used to move data. Defaults to the LTN12 `pump.step` function.
  - `proxy` (optional, default none): The URL of a proxy server to use.
  - `options.redirect` (optional, default `true`): Set to `false` to prevent GET or HEAD requests from automatically following 301, 302, 303, and 307 server redirect messages.
    Note: https to http redirects are not allowed by default, but only when this option is set to a string value `"all"`.
  - `options.create` (optional): a function to be used instead of `socket.tcp` when the communications socket is created.
  - `options.maxredirects` (optional, default 5): An optional number specifying the maximum number of redirects to follow. A boolean `false` value means no maximum (unlimited).
  - `options.timeout` (optional, default 60): A number specifying the timeout for connect/send/receive operations. Or a table with keys `"connect"`, `"send"`, and `"receive"`, to specify individual timeouts (keys omitted from the table will get a default of 30).
`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.

### Low level Copas functions

Most of these are wrapped in the socket wrapper functions, and wouldn't need to be used by user code on a regular basis.

`copas.close(skt)`

  Closes the socket. Any read/write operations in progress will return with an error.

`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.receive(skt [, pattern [, prefix]])` (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.

  Security note: see the note under `sock:receive` above regarding the default `"*l"` pattern having no maximum length, which makes it unsafe to use directly on untrusted/remote input without an application-enforced size limit.

`copas.receivepartial(skt [, pattern [, prefix]])`

  The same as `receive`, except that this method will return on any data received. See `sock:receivepartial` for details.

`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.

  Note: only for TCP, UDP send doesn't block, hence doesn't require this function to be used.

`copas.settimeout(skt, [timeout])`

  Sets the timeout (in seconds) for a socket. A negative timout or absent timeout (`nil`) will wait indefinitely.

  Important: this behaviour is the same as LuaSocket, but different from `copas.settimeouts`, where `nil` means 'do not change' the timeout.

  If a timeout is hit, the operation will return `nil + "timeout"`. Timeouts are applied on: `receive, receivefrom, receivepartial, send, connect, dohandshake`.

  See `copas.usesockettimeouterrors()` below for alternative error messages.

`copas.settimeouts(skt, [connect], [send], [receive])`

  Sets the timeouts (in seconds) for a socket. The default is to not have a timeout and wait indefinitely.

  Important: this behaviour is different from `copas.settimeout`, where `nil` means 'wait indefinitely'.

  If a timeout is hit, the operation will return `nil + "timeout"`. Timeouts are applied on: `receive, receivefrom, receivepartial, send, connect, dohandshake`.

  See `copas.usesockettimeouterrors()` below for alternative error messages.

`t = copas.status([enable_stats])`

  Returns metadata about the current scheduler status. By default only number/type of tasks is being reported. If `enable_stats == true` then detailed statistics will be enabled. Calling it again later with `enable_stats == false` will disabled it again.

  - `t.running`: boolean, same as `copas.running`.
  - `t.read`: the number of tasks waiting to read on a socket.
  - `t.write`: the number of tasks waiting to write to a socket.
  - `t.active`: the number of tasks ready to resume.
  - `t.timer`: the number of timers for tasks (in the binary tree).
  - `t.inactive`: the number of tasks waiting to be woken up.
  - `t.timeout`: the number of timers for timeouts (in the timerwheel).
  - `t.time_start`*: measurement time started (seconds, previous call to status).
  - `t.time_end`*: measurement time ended (seconds, now, current call to status).
  - `t.time_avg`*: average time per step (millisec).
  - `t.steps`*: the number of loop steps executed.
  - `t.duration_tot`*: total time spent executing (millisec, processing tasks, excluding waiting for the network select call).
  - `t.duration_min`*: smallest execution time per step (millisec).
  - `t.duration_min_ever`*: smallest execution time per step ever (millisec).
  - `t.duration_max`*: highest execution time per step (millisec).
  - `t.duration_max_ever`*: highest execution time per step ever (millisec).
  - `t.duration_avg`*: average execution time per step (millisec).
  The properties marked with * will only be reported if detailed statistics are enabled. Every call to this function will reset the time and duration statistics (except for the "ever" ones).
`bool = 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).

  NOTE: the `copas.running` flag will not automatically be (un)set. So when using your own main loop, consider manually setting the flag.

`copas.timeout(delay [, callback])`

  Creates a timeout timer for the current coroutine. The `delay` is the timeout in seconds, and the `callback` will be called upon an actual timeout occuring.

  Calling it with `delay = 0` (or `math.huge`) will cancel the timeout.

  Calling it repeatedly will simply replace the timeout on the current coroutine and any previous callback set will no longer be called.

  NOTE: The timeouts are a low-level Copas feature, and should only be used to wrap an explicit yield to the Copas scheduler. They should not be used to wrap user code.

  Example usage:

      local copas = require "copas"
      local result = "nothing"

      copas(function()

        local function timeout_handler(co)  -- co will be the coroutine from which 'timeout()' was called
          print("executing timeout handler")
          result = "timeout"
          copas.removethread(co)            -- drop the thread, because we timed out
        end

        copas.addthread(function()
          copas.timeout(5, timeout_handler) -- timeout on the current coroutine after 5 seconds
          copas.pause(10)                   -- sleep for 10 seconds
          print("just woke up")
          result = "slept like a baby"
          copas.timeout(0)                  -- cancel the timeout on the current coroutine
        end)
      end)

      print("result: ", result)

  For usage examples see the `lock` and `semaphore` implementations.

`copas.usesockettimeouterrors([bool])`

  Sets the timeout errors to return for the current co-routine. The default is `false`, meaning that a timeout error will always return an error string `"timeout"`. If you are porting an existing application to Copas and want LuaSocket or LuaSec compatible error messages then set it to `true`.

  In case of using socket timeout errors, they can also be `"wantread"` or `"wantwrite"` when using ssl/tls connections. These can be returned at any point if during a read or write operation an ssl-renegotiation happens.

  Due to platform difference the `connect` method may also return `"Operation already in progress"` as a timeout error message.

### Copas debugging functions

These functions are mainly used for debugging Copas itself and should be considered experimental.

`copas.cancelall()`

  This will clear pending work (client sockets, server sockets, timers) to force the copas loop to exit immediately. This is useful for testing and debugging.

  Here's an example which, upon an error, cancels all pending work to ensure the test ends immediately instead of waiting for the long sleep to end:

      local failure

      copas(function()
        copas.seterrorhandler(function(msg, co, skt)
          failure = copas.gettraceback(msg, co, skt)
          copas.cancelall()   -- cancel all pending work to force exit
        end, true)            -- true -> set as default errorhandler

        copas.addthread(function()
          print("sleeping")
          copas.pause(3600)   -- would block copas loop from exiting
        end)

        copas.addthread(function()
          copas.pause(1)
          error("boom!!")     -- invokes the erorrhandler above
        end)
      end)

      assert(not failure, failure)

`copas.debug.start([logger] [, core])`

  This will internally replace coroutine handler functions to provide log output to the provided `logger` function. The logger signature is `function(...)` and the default value is the global `print()` function.

  If the `core` parameter is truthy, then also the Copas core timer will be logged (very noisy).

`copas.debug.stop()`

  Stops the debug output being generated.

`debug_socket = copas.debug.socket(socket)`

  This wraps the socket in a debug-wrapper. This will for each method call on the socket object print the method, the parameters and the return values. Check the source code on how to add additional introspection using extra callbacks etc.

  Extremely noisy and experimental!

  NOTE 1: for TLS you'll probably need to first do the TLS handshake.

  NOTE 2: this is separate from the other debugging functions.

Valid XHTML 1.0!

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