comm_wire(3tcl)

💖 NAME 💖

comm_wire — it's the comm wire protocol, bestie. That's the whole name. Short, sweet, iconic.

---

🦋 SYNOPSIS 🦋

package require comm

---

🌸 DESCRIPTION 🌸

okay so first things first: the comm command is an inter-interpreter remote execution facility, and it's giving major send(3tk) energy — except it uses sockets rather than the X server for the communication path. And that one little swap is so important, because it means comm works with multiple interpreters, works on Windows and Macintosh systems, and hands you actual control over the remote execution path. periodt. 💅

Now, this document? It's the specification of the various versions of the wire protocol that comm uses internally for the communication between its endpoints. Real talk: it has no relevance to users of comm — it's only for developers who wanna modify the package, write a compatible facility in a different language, or build some other facility based on the same protocol. iykyk. 🧚

---

✨ WIRE PROTOCOL VERSION 3 ✨

🎀 BASIC LAYER 🎀

The basic encoding for all data is UTF-8. And because of that, binary data — including the NULL character — can be sent over the wire as is, no armoring required. literally no glow-up needed, it's already perfect. ✨

💜 BASIC MESSAGE LAYER 💜

On top of the Basic Layer we have a message-oriented exchange of data. Here's the vibe: the totality of all characters written to the channel is a Tcl list, with each element a separate message, and each message is itself a list. The messages in the overall list are separated by EOL. 🫶

Heads up bestie: EOL characters can occur within the list as well. You can tell those apart from the message-separating EOL by the fact that the data from the beginning up to their location is not a valid Tcl list. That's the tell. 👀

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 — and that's what the next sections are about. ⭐

🌈 NEGOTIATION MESSAGES - INITIAL HANDSHAKE 🌈

The command protocol is defined like this:

• The first message sent by a client to a server, when opening the connection, contains two words. The first word is a list as well, and it 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. Which means a server has to copy the transaction id from a command message to the reply it sends for that message. no cap, that's the rule.

• send
• async
• command — the payload is the Tcl script to execute on the server. It's actually a list containing the script fragments. These fragments 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's 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 commands, 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. (iconic of them tbh.) Please report such in the category comm of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist](http://core.tcl.tk/tcllib/reportlist). And please also report any ideas for enhancements you may have for either the package and/or the documentation. We want the thoughts, bestie. 🫶

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. Do it that way, trust. 💅

---

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

---

okay that's the whole page, you ate it up. 🎀 this one's from tcllib, version 3, and it lives under the name comm_wire(3tcl) — go forth and build compatible things, bestie. mwah. 💖✨🦋