comm_wire - The comm wire protocol

       This  document,  and  the package it describes, will undoubtedly contain bugs and other problems.  Please
       report such in the category comm of the TcllibTrackers  [http://core.tcl.tk/tcllib/reportlist].   Please
       also report any ideas for enhancements you may have for either package and/or documentation.

       When proposing code changes, please provide unifieddiffs, i.e the output of diff-u.

       Note  further  that  attachments  are strongly preferred over inlined patches. Attachments can be made by
       going to the Edit form of the ticket immediately after its creation, and then using the left-most  button
       in the secondary navigation bar.

       Programming tools

       Copyright (c) 2005 Docs. Andreas Kupries <andreas_kupries@users.sourceforge.net>

tcllib                                                  3                                        comm_wire(3tcl)

       The comm command provides an inter-interpreter remote execution facility much like Tk's send(3tk), except
       that  it  uses sockets rather than the X server for the communication path.  As a result, comm works with
       multiple interpreters, works on Windows and Macintosh systems,  and  provides  control  over  the  remote
       execution path.

       This  document  contains  a  specification  of  the  various  versions  of the wire protocol used by comm
       internally for the communication between its endpoints. It has no relevance to users  of  comm,  only  to
       developers  who  wish to modify the package, write a compatible facility in a different language, or some
       other facility based on the same protocol.

       comm, communication, ipc, message, remote communication, remote execution, rpc, socket

       comm_wire - The comm wire protocol

       comm

       package require comm

________________________________________________________________________________________________________________

BASICLAYER
       The basic encoding for all data is UTF-8. Because of this binary data, including the NULL character,  can
       be sent over the wire as is, without the need for armoring it.

   BASICMESSAGELAYER
       On  top  of  the BasicLayer we have a messageoriented exchange of data.  The totality of all characters
       written to the channel is a Tcl list, with each element a separate  message,  each  itself  a  list.  The
       messages  in the overall list are separated by EOL. Note that EOL characters can occur within the list as
       well. They can be distinguished from the message-separating EOL by  the  fact  that  the  data  from  the
       beginning up to their location is not a valid Tcl list.

       EOL  is  signaled  through  the  linefeed  character,  i.e  LF,  or, hex 0x0a. This is following the unix
       convention for line-endings.

       As a list each message is composed of words. Their meaning depends on when the message was  sent  in  the
       overall exchange. This is described in the upcoming sections.

   NEGOTIATIONMESSAGES-INITIALHANDSHAKE
       The command protocol is defined like this:

       •      The  first  message send by a client to a server, when opening the connection, contains two words.
              The first word is a list as well, and contains the versions of the wire  protocol  the  client  is
              willing  to  accept,  with  the  most preferred version first. The second word is the TCP port the
              client is listening on for connections to itself. The value 0 is used  here  to  signal  that  the
              client  will  not  listen  for  connections,  i.e. that it is purely for sending commands, and not
              receiving them.

       •      The first message sent by the server to the client, in response to the message above contains only
              one word. This word is a list, containing the string vers as its first element, and the version of
              the wire protocol the server has selected from the offered versions as the second.

   SCRIPT/COMMANDMESSAGES
       All messages coming after the initialhandshake consist of three  words.  These  are  an  instruction,  a
       transaction  id, and the payload. The valid instructions are shown below. The transaction ids are used by
       the client to match any incoming replies to the command messages it sent. This means that a server has to
       copy the transaction id from a command message to the reply it sends for that message.

       sendasynccommand
              The payload is the Tcl script to execute on the server. It  is  actually  a  list  containing  the
              script  fragments.  These fragment are concatenated together by the server to form the full script
              to execute on the server side.  This emulates the Tcl "eval" semantics.  In most cases it is  best
              to have only one word in the list, a list containing the exact command.

              Examples:

                  (a)     {send 1 {{array get tcl_platform}}}
                  (b)     {send 1 {array get tcl_platform}}
                  (c)     {send 1 {array {get tcl_platform}}}

                  are all valid representations of the same command. They are
                  generated via

                  (a')    send {array get tcl_platform}
                  (b')    send array get tcl_platform
                  (c')    send array {get tcl_platform}

                  respectively

       Note that (a), generated by (a'), is the usual form, if only single commands are sent by the client.  For
       example constructed using list, if the command contains variable arguments. Like

                  send [list array get $the_variable]

       These  three  instructions all invoke the script on the server side. Their difference is in the treatment
       of result values, and thus determines if a reply is expected.

              send   A reply is expected. The sender is waiting for the result.

              async  No reply is expected, the sender has no interest in the result and is not waiting for any.

              command
                     A reply is expected, but the sender is not waiting  for  it.  It  has  arranged  to  get  a
                     process-internal notification when the result arrives.

       reply  Like  the  previous three command, however the tcl script in the payload is highly restricted.  It
              has to be a syntactically valid Tcl return command. This contains result code, value, error  code,
              and error info.

              Examples:

                  {reply 1 {return -code 0 {}}}
                  {reply 1 {return -code 0 {osVersion 2.4.21-99-default byteOrder littleEndian machine i686 platform unix os Linux user andreask wordSize 4}}}