Session

The Session module provides a communication channel respecting this set of properties:

• A Session instance obtained by Session.new represents one side of a communication.

• When two instances are connected together, they offer a bidirectional communication channel between these two points. Messages are received on a stream. There is only one reception stream per session instance that receives all messages from all successive connections of this instance.

• At maximum two instances can be connected together at any time.

• Any one of the two sides of a session communication channel can break the connection. Each side can then be connected back again together or to other session instances.

• Each session instance also provides a free-for-all communication channel where anyone can send messages freely without having to connect. These messages are received on a distinctive stream. For example, an application wants to provide a remote control to several remote clients, but only one at a time. With the Session module, the application can use a single session instance to let only one remote client connect at a time. When the client wants to stop working with the application, it can stop the session, and another client can then take over. If a client is already connected to the application and another one wants to connect to it also, it can use the free-for-all channel to notify the application so. If there are several applications the client wants to connect to successively, it can do so using a single session instance.

• Each session instance produces a link state stream. Connections, change of the communication link with the currently connected session and disconnections generate messages on that stream. This can be used to create fault-tolerant applications without using the Fault module. The possible messages on that stream are:

  • connect: this session instance has just been connected to another session instance. Messages can be sent to the other site.

  • disconnect: this session instance has been disconnected by the other session instance. No message can be sent while disconnected.

  • tempFail: there is a communication problem that temporarily prevents the messages from arriving to the other site. A tempFail may change into permFail or ok, or stays forever (until the site decides to break the session). Note that the application can still send messages in this state, they will be buffered and send correctly if the communication turns ok or dropped if the communication is broken.

  • permFail: the other site was detected crashed. It is the same as disconnect, except that there is no use to try and contact the other site anymore: it is dead forever.

  • ok: after a tempFail, this state means the communication is fine again, messages are normally arriving at the other site.

This module also offers a session gate, which is a single access point for spawning multiple sessions. Typically, a server can start a gate that will create a different session per client. When a client has finished to work with the server, the session is closed and no more communication is possible between them. However, the client can use the gate again to create a new session with the server.

This module doesn't provide an access control over the session instances and the gates. The application should define its own using the Connection and Ticket modules, or the SocketConnection module.