1comm_wire(n) Remote communication comm_wire(n)
2______________________________________________________________________________
6
8 comm_wire - The comm wire protocol
9
11 package require comm_wire
12_________________________________________________________________
14
16 The comm command provides an inter-interpreter remote execution facil‐
17 ity much like Tk's send(n), except that it uses sockets rather than the
18 X server for the communication path. As a result, comm works with mul‐
19 tiple interpreters, works on Windows and Macintosh systems, and pro‐
20 vides control over the remote execution path.
21 This document contains a specification of the various versions of the
23 wire protocol used by comm internally for the communication between its
24 endpoints. It has no relevance to users of comm, only to developers who
25 wish to modify the package, write a compatible facility in a different
26 language, or some other facility based on the same protocol.
27
29 Basic Layer
30 The basic encoding for all data is UTF-8. Because of this binary data,
31 including the NULL character, can be sent over the wire as is, without
32 the need for armoring it.
33 Basic Message Layer
35 On top of the Basic Layer we have a message oriented exchange of data.
36 Each message is a syntactically valid Tcl list terminated with an addi‐
37 tional EOL. Note that EOL characters can occur within the list as well.
38 They can be distinguished from the terminating EOL by the fact that the
39 data from the beginning up to their location is not a valid Tcl list.
40 EOL is signaled through the character . This is following the unix con‐
42 vention for line-endings.
43 As a list each message is composed of words. Their meaning depends on
45 when the message was sent in the overall exchange. This is described in
46 the upcoming sections.
47 Negotiation Messages - Initial Handshake
49 The command protocol is defined like this:
50 · The first message send by a client to a server, when opening the
52 connection, contains two words. The first word is a list as
53 well, and contains the versions of the wire protocol the client
54 is willing to accept, with the most prefered version first. The
55 second word is the TCP port the client is listening on for con‐
56 nections to itself. The value 0 is used here to signal that the
57 client will not listen for connections, i.e. that it is purely
58 for sending commands, and not receiving them.
59 · The first message sent by the server to the client, in response
61 to the message above contains only one word. This word is a
62 list, containing the string vers as its first element, and the
63 version of the wire protocol the server has selected from the
64 offered versions as the second.
65 Script/Command Messages
67 All messages coming after the initial handshake consist of three words.
68 These are an instruction, a transaction id, and the payload. The valid
69 instructions are shown below. The transaction ids are used by the
70 client to match any incoming replies to the command messages it sent.
71 This means that a server has to copy the transaction id from a command
72 message to the reply it sends for that message.
73 send
75 async
77 command
79 The payload is the Tcl script to execute on the server. It is
80 actually a list containing the script fragments. These fragement
81 are concatenated together by the server to form the full script
82 to execute on the server side. This emulates the Tcl "eval"
83 semantics. In most cases it is best to have only one word in
84 the list, a list containing the exact command.
85 Examples:
87 (a) {send 1 {{array get tcl_platform}}}
90 (b) {send 1 {array get tcl_platform}}
91 (c) {send 1 {array {get tcl_platform}}}
92 are all valid representations of the same command. They are
94 generated via
95 (a') send {array get tcl_platform}
97 (b') send array get tcl_platform
98 (c') send array {get tcl_platform}
99 respectively
101 Note that (a), generated by (a'), is the usual form, if only
104 single commands are sent by the client. For example constructed
105 using list, if the command contains variable arguments. Like
106 send [list array get $the_variable]
109 These three instructions all invoke the script on the server
112 side. Their difference is in the treatment of result values, and
113 thus determines if a reply is expected.
114 send A reply is expected. The sender is waiting for the
116 result.
117 async No reply is expected, the sender has no interest in the
119 result and is not waiting for any.
120 command
122 A reply is expected, but the sender is not waiting for
123 it. It has arranged to get a process-internal notifica‐
124 tion when the result arrives.
125 reply Like the previous three command, however the tcl script in the
127 payload is highly restricted. It has to be a syntactically
128 valid Tcl return command. This contains result code, value,
129 error code, and error info.
130 Examples:
132 {reply 1 {return -code 0 {}}}
135 {reply 1 {return -code 0 {osVersion 2.4.21-99-default byteOrder littleEndian machine i686 platform unix os Linux user andreask wordSize 4}}}
136
139 comm
140
142 communication, ipc, message, remote communication, rpc, socket
143
145 Copyright (c) 2005 Docs. Andreas Kupries <andreas_kupries@users.sourceforge.net>
146comm 3 comm_wire(n)