About: Transporter
01 The Semys Library contains a transporter extension interface that abstracts the method of transportation for connections (and servers) used in Semys.
02 A connection is the simplest thing in the Semys Library to transport data.
03 While the common form of transporting data nowadays is via TCP/IP, Semys is intended to be used in systems where the paths of transportation may need to be backed up in different ways.
04 The transporter interface is designed to match the common properties of TCP/IP but has been held abstract enough to be implemented by other forms of transportation, too.
05 The Semys Library contains a full implementation of a TCP transporter that can be used as reference for other types if required. Also included is a 'simple' loopback transporter.
06 The transporter interface knows about Connection objects, that can transmit and receive data and Server objects that listen for incoming connections.
07 Connections need to be identifyable by a connection name so that they can be used properly in the link interface. This name furthermore consists of a 'local' and a 'remote' part, where the 'local' part matches the 'remote' part at the other connected party and vice versa.

Option Strings
08 Bot Server and Connection objects are configured using option strings. For example: 
Server: "tcp:0.0.0.0?port=10000"
Connection: "tcp:127.0.0.1?port=10000&reconnecting=1"
Specifies a TCP server that should listen on port 10000 on any IPv4 interface in the system and a TCP connection that should connect to the IPv4 address 127.0.0.1 on the port 10000 and try to reconnect every time the connection is lost.
09 The benefit of the TCP transporter option strings is that their base can be used for both server and connections to match properly: 
Server: "tcp:10.0.0.17?port=10000"
Connection: "tcp:10.0.0.17?port=10000&reconnecting=1"
Specifies a TCP server that should listen on port 10000 on the IPv4 interface 10.0.0.17 and a connection that should connect to exactly this server.
10 While it is not required to design option strings on such a symmetrical way, this behaviour of the TCP transporter is used to simplify the configuration of Semys Arch modules.
11 Although a transporter can define any form of options, connections are considered to have a common option "reconnecting" that specifies that the outgoing connection should be reestablished automatically after it has been lost.

Server Properties
12 A server works asynchronously to the user code.
13 A server can be in the state of listening for incoming connections or not.
14 An incoming connection request is notified to the user of the server. If the request is accepted, a corresponding connection object is created. If the request is rejected, the incmoning connection is closed immediately.

Connection Properties
15 A connection works asynchronously to the user code.
16 A connection can be in the connected or disconnected state. The connection state is symmetrical; This means that the connection partner either both are connected or both are not.
17 The connected state allows transportation of data as fast as possible.
18 Transportation of data shall be symmetrical (to the user) - Receive and transmit should be available simultaneously. How exactly the data is exchanged via the medium of the transporter is irrelevant to the user.
19 Any number of data bytes shall be able to be transported.
20 Transmission of data is reliable. If data is transmitted then it either will be received by the other partner or the connection is lost.
21 Transmission of data is strictly ordered. If data B is sent after data A, then data B will be received after data A has been received.
22 It is allowed for a transporter to receive data in different chunks as it was sent. For example, if "1234" and "ABCD" were sent, the receiver may receive "12", "34AB", "CD" separately (still fullfilling the requirement about strict ordering)
23 The loss of a connection (disconnected state) should be detected by the transporter by itself as best (and as soon) as possible. At least should the loss be detected the next time data should be transmitted.
24 The name of a connection is unique at any point of time during its lifetime.

Transporter TCP
25 As described above, the Semys Library contains a predefined TCP transporter. Both IPv4 and IPv6 interfaces are supported by it.
The type prefix for a connection string is "tcp:"
26 Host identification is based on IP addresses. Automatic name resolution has not been implemented because of difficulties at resolve errors and multi homed hosts. It shall be possible to exactly specify over which network a TCP connection should be established. Using names would make this difficult.
27 The servers Semys is intended to run on wont change their IP addresses often (or at all) and thus can be statically configured. If the clients still should allow configuration by name then the user code is in charge to resolve it.
28 TCP Server Option String:
Main: Local address, either IPv4 or IPv6 (if supported by OS) in numerical format. Options:
  • port: Decimal value of the port to (try to) listen on.
  • reuseaddr: Boolean (default: 0) if the SO_REUSEADDR option shall be set.
  • scopeid: Decimal value of the IPv6 scope id.
Examples: 
tcp:0.0.0.0?port=8000&reuseaddr=1
tcp:::1?port=8001
29 TCP Connection Option String:
Main: Remote address, either IPv4 or IPv6 (if supported by OS) in numerical format. Options:
  • port: Decimal value of the port to (try to) connect to at remote host.
  • reconnecting: Boolean (default: 0) if the connection should reconnect after a loss
  • scopeid: Decimal value of the IPv6 scope id
Examples: 
tcp:10.0.0.2?port=8000&reconnecting=1
tcp:::1?port=8001

Transporter LO (loopback)
30 A special and simple, yet important transporter is the 'loopback' transporter. Essentially, a loopback connection receives what it is given for transmission.
The type prefix for a connection string is "lo:"
31 Since a loopback connection is basically a mirror, both 'local' and 'remote' names are identical - this way a Link can be fed with it transparently.
32 If a Link is fed with a loopback connection, it can only be fed with this type of transporter, since the other connections can not be synchronized.
33 This loopback transporter is primarily used in groups for the links from each group member to itself.
34 LO Server Option String:
This transporter provides no server functionality.
34 LO Connection Option String:
Main: String that is taken for both local and remote connection names. Options:
  • reconnecting: Boolean (default: 0) if the connection should reconnect after a loss (which can only be caused via SemysConnCloseProt() )
Examples: 
lo:test?reconnecting=1
lo:mirror

Alternative Example
30 As an example (without going into details), the transporter using telephone modem is specified. The server side is configured on what telephone number it should listen for incoming connections and the client side is configured where to call to: 
Server: "tel:+431234567"
Connection: "tel:+43123456&reconnecting=1"
31 The connection name for example could consist of the telephone number of the server and the number of the caller (client). If several connections from the client to the server should be possible (e.g. by using ISDN) a further, call specific identification would be needed to be added.

Goto: Main Page; This page is part of the Semys software documentation. See About: Documentation for details.