sid/component/consoles/sid-io-socket.txt

   1 * Name
   2   sid-io-socket-server sid-io-socket-client
   3
   4 * Synopsis
   5
   6   Members of this family of components perform I/O on a TCP socket and relay data
   7   across a pair of pins to some other component.
   8
   9   Pins: init fini tx rx poll-event poll-control
  10   Attributes: tx-count tx-buffer rx-count poll-count avg-tx-buffer-size server?
  11         sockaddr-local sockaddr-peer verbose? trace-traffic? buffer-while-disconnected?
  12         connected? max-poll-interval poll-interval
  13         init fini tx rx
  14
  15   Library: libconsoles.la
  16   Symbol name: console_component_library
  17
  18 * Functionality
  19   - Modelling
  20
  21     This simulated component uses non-blocking I/O on the host.
  22     Therefore it must be regularly polled, for example by a host-time
  23     scheduler.  This component is able to automatically regulate a
  24     scheduler subscription to produce fast response/throughput during
  25     high traffic times, or reduce CPU load in low traffic times.
  26
  27     The "sid-io-socket-server" component implements a TCP server, and
  28     "sid-io-socket-client" implements a TCP client.  In other words,
  29     one expects an incoming socket connection, the other uses an
  30     outgoing socket connection.  The two components are otherwise
  31     interchangeable and are treated below as one kind.
  32
  33     Multiple instances of these components coexist comfortably.
  34
  35   - Behaviors
  36
  37     * Initialization
  38
  39       When the "init" pin is driven, the component creates and binds a
  40       file descriptor to the IP address specified by the
  41       "sockaddr-local" attribute.  The host operating system may
  42       assign some available TCP port number if the attribute is not
  43       set.  An actual TCP connection attempt is not made at this time.
  44
  45       When the "fini" pin is driven, the component closes its file
  46       descriptors, thus closing its connection (if any).
  47
  48     * Connection
  49
  50       When the "poll-event" pin is driven, but no connection exists, a
  51       non-blocking TCP connect operation is attempted.  For a server,
  52       this means an "accept()" call, and for a client, a "connect()".
  53       The "server?" attribute will contain a boolean true value for
  54       the former, false for the latter.
  55
  56       If the connection is successful, the "connected?" attribute is
  57       set to a true value, and the "sockaddr-peer" attribute is filled
  58       in.  If connection is ever lost, "connected?" is reset, and a
  59       new connection will be attempted at the next "poll-event"
  60       signal.
  61
  62       If the "verbose?" attribute is set, a trace message is emitted
  63       whenever the connection status changes.
  64
  65     * Pin I/O
  66
  67       When the "tx" pin is driven with a value, the bottom 8 bits are
  68       extracted and enqueued in a transmit buffer.  The "tx-buffer"
  69       attribute provides a read-only view of the current buffer, and
  70       the "avg-tx-buffer-size" provides a moving average length of
  71       this buffer.  If a TCP connection does not exist, and
  72       "buffer-while-disconnected?" is set to a boolean false value,
  73       then bytes received on the "tx" pin are ignored instead of
  74       buffered.
  75
  76       Whenever the "tx" pin is driven without value out of 0-255
  77       range, it is interpreted as an "end-of-file" indication, which
  78       causes the current socket connection, if any, to be shut down.
  79       Similarly, if the disconnection is caused by the peer, the "rx"
  80       pin is driven with an out-of-range value to signal an
  81       "end-of-file" condition.
  82
  83       Whenever a character is received from the TCP socket, it is
  84       immediately transmitted on the "rx" pin as an 8-bit value.
  85       (This happens only during a poll.)
  86
  87     * Socket I/O polling
  88
  89       When the "poll-event" pin is driven, and a connection exists,
  90       this component attempts to receive then transmit batches of
  91       bytes, in a non-blocking manner.  If the "trace-traffic?"
  92       attribute is set to a boolean true value, a tracing message is
  93       written to standard out for each successful "read()" or "write()"
  94       operation.
  95
  96       The "tx-count" and "rx-count" attributes accumulate the number
  97       of bytes transmitted and received, respectively.  The
  98       "poll-count" attribute accumulates the number of "poll-event"
  99       events, including those made while disconnected.
 100
 101       After all "poll-event" signals, the component drives the
 102       "poll-control" pin with a value meant to set the interval to the
 103       next polling event.  Each successful non-blocking socket I/O
 104       operation tends to reduce the polling interval, and each
 105       unsuccessful one gradually increases the interval.  This
 106       adaptive process attempts to provide a good trade-off between
 107       socket I/O performance (speed & throughput) and host OS load
 108       (polling frequency).  The "poll-interval" attribute contains the
 109       last selected polling interval, and "max-poll-interval" sets a
 110       maximum on the adaptive increase.  (The minimum is 0.)
 111
 112   - SID conventions
 113     * This is a functional component.
 114     * It does not support state save/restore, nor triggerpoints.
 115     * It prevents harmful recursion on the "poll-event" input pin.
 116
 117 * Environment
 118   - Related components
 119
 120     The "init" and "fini" pins must be driven in the proper sequence.
 121
 122     Since this component family merely pumps data in and out of a
 123     socket, some other component should serve as the source and sink
 124     of the characters.
 125
 126     The adaptive polling control mechanism is designed to operate best
 127     when connected to a host-time scheduler.  This mechanism may be
 128     unused, as long as the "poll-event" pin is driven regularly by
 129     some other source.
 130
 131     The following configuration file fragment shows a hypothetical use
 132     of the socket components.
 133
 134         new SOMETYPE source
 135         new SOMETYPE sink
 136         new sid-sched-host-accurate sched
 137         new sid-io-socket-server srv                    # be a server
 138         set srv sockaddr-local 0.0.0.0:3420             # listen on port 3420
 139         set sched num-clients 1
 140         connect-pin main starting -> srv init
 141         connect-pin main stopping -> srv fini
 142         connect-pin sched 0-event -> srv poll-event     # adaptive polling
 143         connect-pin sched 0-control <- srv poll-control # adaptive polling
 144         set srv verbose? 1
 145         connect-pin srv tx <- source tx
 146         connect-pin srv rx -> sink rx
 147
 148 * SID interface reference
 149
 150   - low level:
 151     * pins
 152       - init | input | N/A | initialization
 153       - fini | input | N/A | initialization
 154       - tx | input | byte or void | pin I/O
 155       - rx | output | byte or void | pin I/O
 156       - poll-event | input | any | connection, socket I/O polling
 157       - poll-control | output | limited value | connection, socket I/O polling
 158
 159     * attributes
 160       - tx-count | register | numeric | n/a | socket I/O polling
 161       - tx-buffer | register | string | n/a | pin I/O
 162       - rx-count | register | numeric | n/a | socket I/O polling
 163       - poll-count | register | numeric | n/a | socket I/O polling
 164       - avg-tx-buffer-size | register | floating point string | n/a | pin I/O
 165       - server? | setting | boolean | 1/0 | initialization
 166       - sockaddr-local | setting/register | ipaddress:port | 0.0.0.0:0 | connection
 167       - sockaddr-peer | register/setting | ipaddress:port | 0.0.0.0:0 | connection
 168       - verbose? | setting | boolean | 0 | connection
 169       - trace-traffic? | setting | boolean | 0 | socket I/O polling
 170       - buffer-while-disconnected? | setting | boolean | yes | pin I/O
 171       - connected? | register | boolean | n/a | connection
 172       - max-poll-interval | setting | numeric | 250 | socket I/O polling
 173       - poll-interval | register | numeric | n/a | socket I/O polling
 174       - init | pin | numeric | n/a | initialization
 175       - fini | pin | numeric | n/a | initialization
 176       - tx | pin | numeric | n/a | pin I/O
 177       - rx | pin | numeric | n/a | pin I/O