sid-io-socket (libconsoles.la :: console_component_library)

Synopsis:

Members of this family of components perform I/O on a TCP socket and relay data across a pair of pins to some other component.

Functionality:

Modelling:

This simulated component uses non-blocking I/O on the host. Therefore it must be regularly polled, for example by a host-time scheduler. This component is able to automatically regulate a scheduler subscription to produce fast response/throughput during high traffic times, or reduce CPU load in low traffic times.

The sid-io-socket-server component implements a TCP server, and sid-io-socket-client implements a TCP client. In other words, one expects an incoming socket connection, the other uses an outgoing socket connection. The two components are otherwise interchangeable and are treated below as one kind.

Multiple instances of these components coexist comfortably.

Behaviors
initialization
When the init pin is driven, the component creates and binds a file descriptor to the IP address specified by the sockaddr-local attribute. The host operating system may assign some available TCP port number if the attribute is not set. An actual TCP connection attempt is not made at this time.

When the fini pin is driven, the component closes its file descriptors, thus closing its connection (if any).

connection
When the poll-event pin is driven, but no connection exists, a non-blocking TCP connect operation is attempted. For a server, this means an accept() call, and for a client, a connect(). The server? attribute will contain a boolean true value for the former, false for the latter.

If the connection is successful, the connected? attribute is set to a true value, and the sockaddr-peer attribute is filled in. If connection is ever lost, connected? is reset, and a new connection will be attempted at the next poll-event signal.

If the verbose? attribute is set, a trace message is emitted whenever the connection status changes.

pin i/o
When the tx pin is driven with a value, the bottom 8 bits are extracted and enqueued in a transmit buffer. The tx-buffer attribute provides a read-only view of the current buffer, and the avg-tx-buffer-size provides a moving average length of this buffer. If a TCP connection does not exist, and buffer-while-disconnected? is set to a boolean false value, then bytes received on the tx pin are ignored instead of buffered.

Whenever the tx pin is driven without value out of 0-255 range, it is interpreted as an "end-of-file" indication, which causes the current socket connection, if any, to be shut down. Similarly, if the disconnection is caused by the peer, the rx pin is driven with an out-of-range value to signal an "end-of-file" condition.

Whenever a character is received from the TCP socket, it is immediately transmitted on the rx pin as an 8-bit value. (This happens only during a poll.)

socket i/o polling
When the poll-event pin is driven, and a connection exists, this component attempts to receive then transmit batches of bytes, in a non-blocking manner. If the trace-traffic? attribute is set to a boolean true value, a tracing message is written to standard out for each successful read() or write() operation.

The tx-count and rx-count attributes accumulate the number of bytes transmitted and received, respectively. The poll-count attribute accumulates the number of poll-event events, including those made while disconnected.

After all poll-event signals, the component drives the poll-control pin with a value meant to set the interval to the next polling event. Each successful non-blocking socket I/O operation tends to reduce the polling interval, and each unsuccessful one gradually increases the interval. This adaptive process attempts to provide a good trade-off between socket I/O performance (speed & throughput) and host OS load (polling frequency). The poll-interval attribute contains the last selected polling interval, and max-poll-interval sets a maximum on the adaptive increase. (The minimum is 0.)

Behaviors
initialization	When the `init` pin is driven, the component creates and binds a file descriptor to the IP address specified by the `sockaddr-local` attribute. The host operating system may assign some available TCP port number if the attribute is not set. An actual TCP connection attempt is not made at this time. When the `fini` pin is driven, the component closes its file descriptors, thus closing its connection (if any).
connection	When the `poll-event` pin is driven, but no connection exists, a non-blocking TCP connect operation is attempted. For a server, this means an `accept()` call, and for a client, a `connect()`. The `server?` attribute will contain a boolean true value for the former, false for the latter. If the connection is successful, the `connected?` attribute is set to a true value, and the `sockaddr-peer` attribute is filled in. If connection is ever lost, `connected?` is reset, and a new connection will be attempted at the next `poll-event` signal. If the `verbose?` attribute is set, a trace message is emitted whenever the connection status changes.
pin i/o	When the `tx` pin is driven with a value, the bottom 8 bits are extracted and enqueued in a transmit buffer. The `tx-buffer` attribute provides a read-only view of the current buffer, and the `avg-tx-buffer-size` provides a moving average length of this buffer. If a TCP connection does not exist, and `buffer-while-disconnected?` is set to a boolean false value, then bytes received on the `tx` pin are ignored instead of buffered. Whenever the `tx` pin is driven without value out of 0-255 range, it is interpreted as an "end-of-file" indication, which causes the current socket connection, if any, to be shut down. Similarly, if the disconnection is caused by the peer, the `rx` pin is driven with an out-of-range value to signal an "end-of-file" condition. Whenever a character is received from the TCP socket, it is immediately transmitted on the `rx` pin as an 8-bit value. (This happens only during a poll.)
socket i/o polling	When the `poll-event` pin is driven, and a connection exists, this component attempts to receive then transmit batches of bytes, in a non-blocking manner. If the `trace-traffic?` attribute is set to a boolean true value, a tracing message is written to standard out for each successful `read()` or `write()` operation. The `tx-count` and `rx-count` attributes accumulate the number of bytes transmitted and received, respectively. The `poll-count` attribute accumulates the number of `poll-event` events, including those made while disconnected. After all `poll-event` signals, the component drives the `poll-control` pin with a value meant to set the interval to the next polling event. Each successful non-blocking socket I/O operation tends to reduce the polling interval, and each unsuccessful one gradually increases the interval. This adaptive process attempts to provide a good trade-off between socket I/O performance (speed & throughput) and host OS load (polling frequency). The `poll-interval` attribute contains the last selected polling interval, and `max-poll-interval` sets a maximum on the adaptive increase. (The minimum is 0.)

SID Conventions
functional supported -
save/restore not supported -
triggerpoints not supported -
inhibit-recursion supported
It prevents harmful recursion on the poll-event input pin.

SID Conventions
functional	supported	-
save/restore	not supported	-
triggerpoints	not supported	-
inhibit-recursion	supported	It prevents harmful recursion on the `poll-event` input pin.

Environment:

Related components

The init and fini pins must be driven in the proper sequence.

Since this component family merely pumps data in and out of a socket, some other component should serve as the source and sink of the characters.

The adaptive polling control mechanism is designed to operate best when connected to a host-time scheduler. This mechanism may be unused, as long as the poll-event pin is driven regularly by some other source.

The following configuration file fragment shows a hypothetical use of the socket components.

new SOMETYPE source new SOMETYPE sink new sid-sched-host-accurate sched new sid-io-socket-server srv # be a server set srv sockaddr-local 0.0.0.0:3420 # listen on port 3420 set sched num-clients 1 connect-pin main starting -> srv init connect-pin main stopping -> srv fini connect-pin sched 0-event -> srv poll-event # adaptive polling connect-pin sched 0-control <- srv poll-control # adaptive polling set srv verbose? 1 connect-pin srv tx <- source tx connect-pin srv rx -> sink rx

Component Reference:

Component: sid-io-socket

pins
name direction legalvalues behaviors
init in N/A initialization
fini in N/A initialization
tx in byte or void pin i/o
rx out byte or void pin i/o
poll-event in any connection, socket i/o polling
poll-control out limited value connection, socket i/o polling

pins
name	direction	legalvalues	behaviors
init	in	N/A	initialization
fini	in	N/A	initialization
tx	in	byte or void	pin i/o
rx	out	byte or void	pin i/o
poll-event	in	any	connection, socket i/o polling
poll-control	out	limited value	connection, socket i/o polling

attributes
name category legal values default value behaviors
tx-count register numeric - socket i/o polling
tx-buffer register string - pin i/o
rx-count register numeric - socket i/o polling
poll-count register numeric - socket i/o polling
avg-tx-buffer-size register floating point string - pin i/o
server? setting boolean 1/0 initialization
sockaddr-local setting/register ipaddress:port 0.0.0.0:0 connection
sockaddr-peer register/setting ipaddress:port 0.0.0.0:0 connection
verbose? setting boolean 0 connection
trace-traffic? setting boolean 0 socket i/o polling
buffer-while-disconnected? setting boolean yes pin i/o
connected? register boolean - connection
max-poll-interval setting numeric 250 socket i/o polling
poll-interval register numeric - socket i/o polling
init pin numeric - initialization
fini pin numeric - initialization
tx pin numeric - pin i/o
rx pin numeric - pin i/o

attributes
name	category	legal values	default value	behaviors
tx-count	register	numeric	-	socket i/o polling
tx-buffer	register	string	-	pin i/o
rx-count	register	numeric	-	socket i/o polling
poll-count	register	numeric	-	socket i/o polling
avg-tx-buffer-size	register	floating point string	-	pin i/o
server?	setting	boolean	1/0	initialization
sockaddr-local	setting/register	ipaddress:port	0.0.0.0:0	connection
sockaddr-peer	register/setting	ipaddress:port	0.0.0.0:0	connection
verbose?	setting	boolean	0	connection
trace-traffic?	setting	boolean	0	socket i/o polling
buffer-while-disconnected?	setting	boolean	yes	pin i/o
connected?	register	boolean	-	connection
max-poll-interval	setting	numeric	250	socket i/o polling
poll-interval	register	numeric	-	socket i/o polling
init	pin	numeric	-	initialization
fini	pin	numeric	-	initialization
tx	pin	numeric	-	pin i/o
rx	pin	numeric	-	pin i/o

Variant: sid-io-socket-client

Same as sid-io-socket

Variant: sid-io-socket-server

Same as sid-io-socket