Class Models for Lua

# Cooperative Sockets

## `loop.thread.CoSocket`

Class of objects that implement a socket API integrated with an instance of `IOScheduler` similar to the one provided by the LuaSocket library. This class is useful to port or implement LuaSocket based applications with the cooperative multi-threading model provided by `Scheduler` class.

Each instance provides methods that correspond to the main functions of the LuaSocket API. Such methods creates wrappers for sockets that re-implement basic operations like `send` and `receive` in order to implicitly switch execution if the socket is not ready to perform the operation yet. When the socket becomes ready the execution is resumed and the operation is carried on transparently to the application. This implicit switch enables maximal use of the processing time transparently to the programmer.

## Behavior

### Initialization

`CoSocket([object])`
  Makes `object` an instance of `CoSocket`. If no `object` is provided, a new table is created. The initialization creates two tables used to store read/write locks for socket objects in order to avoid that two threads read/write the same socket at the same time.

### Fields

`scheduler`
  Instance of `IOScheduler` which threads execute this API. Every thread that may execute an operation of this API that might implicitly switch execution must be running under this scheduler instance.
`socketapi`
  Non-blocking socket API to be used to access operating system features. This API must be the same API provided by LuaSocket, or at least the equivalent subset provided by this class.

### Methods

`bind(host, port)`
  Method that provides the same signature and semantics of `socket.bind` of LuaSocket library. However, it returns a wrapped socket that provides operations that may implicitly switch execution to other scheduled thread of `self.scheduler` if the operation cannot be performed at the time..
`connect(host, port)`
  Method that provides the same signature and semantics of `socket.connect` of LuaSocket library. However, it returns a wrapped socket that provides operations that may implicitly switch execution to other scheduled thread of `self.scheduler` if the operation cannot be performed at the time..
`select(recv, send [, timeout])`
  Method that provides the same signature and semantics of `socket.select` of LuaSocket library. However, such method may implicitly switch execution to other scheduled thread of `self.scheduler` if the operation cannot be performed at the time.
`tcp()`
  Method that provides the same signature and semantics of `socket.tcp` of LuaSocket library. However, it returns a wrapped socket that provides operations that may implicitly switch execution to other scheduled thread of `self.scheduler` if the operation cannot be performed at the time.
`udp()`
  Method that provides the same signature and semantics of `socket.udp` of LuaSocket library. However, it returns a wrapped socket that provides operations that may implicitly switch execution to other scheduled thread of `self.scheduler` if the operation cannot be performed at the time.

## Remarks

- Wrapped sockets redefine the following methods of the API of the socket objects of the LuaSocket library:

  - `accept()`
  - `connect(host, port)`
  - `receive([pattern])`
  - `send(data [, i, j])`
  - `settimeout(timeout)`
  `accept`, `receive` and `send` operations cannot be called outside a scheduled thread and may implicitly switch execution to other scheduled thread of `self.scheduler` if the operation cannot be performed at the time.
- Two threads cannot attempt to read or write the same socket, thus only one thread can perform an `accept` or `receive` on a given socket. Similarly, only one thread can perform a `send` on a given socket. However, two different threads may access the same socket performing different operations, e.g. one perform a `send` and the other a `receive`.
- While porting LuaSocket based applications, a cumbersome difference is that this API offers methods instead of functions, therefore every call to the socket API should use the `:` operator.
- This class adds the message flag `cosocket` to the `verbose` field provided by class Scheduler that generates messages describing the actions related to the wrapped socket operations that implement the integration with the coroutine scheduler. To rip the verbose support from the source code follow the same instructions suggested for class Scheduler.

## Examples

### $ExampleName

    -- example missing

Copyright (C) 2004-2008 Tecgraf, PUC-Rio

This project is currently being maintained by Tecgraf at PUC-Rio.