Design/sock_msg_notes

   1 Stem::Sock::Msg
   2
   3 This cell is the primary way of interfacing external programs to the
   4 Stem messaging system.  It is effectively a gateway with a standard
   5 socket on the outside and a message interface on the inside.  The
   6 socket side takes standard Stem socket parameters for configuration.
   7 The message side has a variety of message types and options to
   8 control buffering.
   9
  10 The socket parameters are directly passed to a Stem::Socket cell, and
  11 supports both client and server modes.  Multiple instances of this
  12 Stem::Sock::Msg cell are supported and can be created via socket
  13 connection or acceptance.  If a connected socket is externally shut
  14 down  it can optionally be reconnected automatically.
  15
  16 When the socket is connected or disconnected, a status message can be
  17 sent out.  This is used to trigger the addressed cell to be made
  18 aware of the new socket status and act accordingly.  For example, in
  19 an inetd emulation, the socket connected message would cause the
  20 address Stem::Proc cell to start a process and logically connect it
  21 to this Stem::Sock::Msg cell.  Similarly, the socket closed message
  22 would cause the process to shut down and the logical connection to be
  23 broken.
  24
  25 When data comes in from the socket, it is buffered and sent out via a
  26 data message to an addressed cell.  Optionally, all incoming data can
  27 be buffered and only sent out in a single message when the socket is
  28 closed.  This reduces the need for some cells to do their own
  29 buffering.
  30
  31 As with all Stem cells, various status information can be logged to
  32 logical logs using the Stem logging system.  Which status is logged
  33 can be controlled by the configuration of the cell.