Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

comm_wire(n)                                Remote communication                                comm_wire(n)



____________________________________________________________________________________________________________

NAME
       comm_wire - The comm wire protocol

SYNOPSIS
       package require comm

____________________________________________________________________________________________________________

DESCRIPTION
       The  comm  command  provides  an  inter-interpreter remote execution facility much like Tk's send(n),
       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.

WIRE PROTOCOL VERSION 3
   BASIC LAYER
       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.

   BASIC MESSAGE LAYER
       On top of the Basic Layer we have a message oriented exchange of data.  The totality of  all  charac-ters characters
       ters  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 con-vention convention
       vention 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.

   NEGOTIATION MESSAGES - INITIAL HANDSHAKE
       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/COMMAND MESSAGES
       All messages coming after the initial handshake 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.

       send

       async

       command
              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}}}



BUGS, IDEAS, FEEDBACK
       This document, and the package it describes,  will  undoubtedly  contain  bugs  and  other  problems.
       Please   report   such   in   the   category   comm   of   the  Tcllib  SF  Trackers  [http://source -
       forge.net/tracker/? group_id=12883].  Please also report any ideas for enhancements you may  have  for
       either package and/or documentation.

SEE ALSO
       comm

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

CATEGORY
       Programming tools

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




comm                                                  3                                         comm_wire(n)