Ubuntu Manpage: comm_wire - The comm wire protocol

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(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.

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 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.

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 Trackers  [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 unified diffs, 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.

KEYWORDS

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

COPYRIGHT

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

tcllib                                                  3                                        comm_wire(3tcl)