comm - A remote communications facility for Tcl (7.6, 8.0, and later)
SYNOPSIS
package require Tcl 8.2
package require comm ?4.0?
|
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.
These commands work just like send and winfo interps :
::comm::comm send ?-async? id cmd ?arg arg ...? ::comm::comm interps |
This is all that is really needed to know in order to use
comm
The package initializes ::comm::comm as the default chan.
comm names communication endpoints with an id unique
to each machine. Before sending commands, the id of another
interpreter is needed. Unlike Tk's send, comm doesn't
implicitly know the id's of all the interpreters on the system.
The following four methods make up the basic comm interface.
The evaluation semantics of ::comm::comm send are intended to
match Tk's send exactly. This means that comm
evaluates arguments on the remote side.
If you find that ::comm::comm send doesn't work for a
particular command, try the same thing with Tk's send and see if the
result is different. If there is a problem, please report it. For
instance, there was had one report that this command produced an
error. Note that the equivalent send command also produces the
same error.
COMMANDS
EVAL SEMANTICS
% ::comm::comm send id llength {a b c} wrong # args: should be "llength list" % send name llength {a b c} wrong # args: should be "llength list" |
The eval hook (described below) can be used to change from
send's double eval semantics to single eval semantics.
More than one comm channel (or listener) can be created
in each Tcl interpeter. This allows flexibility to create full and
restricted channels. For instance, hook scripts are specific
to the channel they are defined against.
The default configuration parameters for a new channel are:
MULTIPLE CHANNELS
"-port 0 -local 1 -listen 0" |
The default channel ::comm::comm is created with:
"::comm::comm new ::comm::comm -port 0 -local 1 -listen 1" |
The config method acts similar to fconfigure in that it sets or queries configuration variables associated with a channel.
These configuration variables can be changed (descriptions of them are elsewhere in this manual page):
These configuration variables are readonly:
When config changes the parameters of an existing channel, it
closes and reopens the listening socket. An automatically assigned
channel id will change when this happens. Recycling the socket
is done by invoking ::comm::comm abort, which causes all
active sends to terminate.
comm uses a TCP port for endpoint id. The
interps (or ids) method merely lists all the TCP ports
to which the channel is connected. By default, each channel's
id is randomly assigned by the operating system (but usually
starts at a low value around 1024 and increases each time a new socket
is opened). This behavior is accomplished by giving the
-port config option a value of 0. Alternately, a specific
TCP port number may be provided for a given channel. As a special
case, comm contains code to allocate a a high-numbered TCP port
(>10000) by using -port {}. Note that a channel won't be
created and initialized unless the specific port can be allocated.
As a special case, if the channel is configured with
-listen 0, then it will not create a listening socket and
will use an id of 0 for itself. Such a channel is only good
for outgoing connections (although once a connection is established,
it can carry send traffic in both directions).
By default, each channel is restricted to accepting connections from
the local system. This can be overriden by using the
-local 0 configuration option For such channels, the
id parameter takes the form { id host }.
WARNING: The host must always be specified in the same
form (e.g., as either a fully qualified domain name, plain hostname or
an IP address).
These methods give control over closing connections:
When a remote connection is lost (because the remote exited or called
shutdown), comm can invoke an application callback.
This can be used to cleanup or restart an ancillary process, for
instance. See the lost callback below.
This is a mechanism for setting hooks for particular events:
These are the defined events:
ID/PORT ASSIGNMENTS
REMOTE INTERPRETERS
CLOSING CONNECTIONS
"::comm::comm destroy; ::comm::comm new ::comm::comm"
CALLBACKS
When an event occurs, the script associated with it is
evaluated with the listed variables in scope and available. The
return code ( not the return value) of the script is commonly
used decide how to further process after the hook.
Common variables include:
This hook is invoked before making a connection to the remote named in
id. An error return (via error) will abort the connection
attempt with the error. Example:
% ::comm::comm hook connecting {
if [lb]string match {*[lb]02468[rb]} $id[rb] {
error "Can't connect to even ids"
}
}
% ::comm::comm send 10000 puts ok
Connect to remote failed: Can't connect to even ids
%
This hook is invoked immediately after making a remote connection to
id, allowing arbitrary authentication over the socket named by
fid. An error return (via error ) will close the
connection with the error. host and port are merely
extracted from the id; changing any of these will have no effect
on the connection, however. It is also possible to substitute and
replace fid.
Hook invoked when receiving an incoming connection, allowing arbitrary
authentication over socket named by fid. An error return (via
error) will close the connection with the error. Note that the
peer is named by remport and addr but that the remote
id is still unknown. Example:
::comm::comm hook incoming {
if [lb]string match 127.0.0.1 $addr[rb] {
error "I don't talk to myself"
}
}
This hook is invoked after collecting a complete script from a remote
but before evalutating it. This allows complete control over
the processing of incoming commands. cmd contains either
send or async. buffer holds the script to
evaluate. At the time the hook is called, $chan remoteid is
identical in value to id.
By changing buffer, the hook can change the script to be
evaluated. The hook can short circuit evaluation and cause a value to
be immediately returned by using return result (or, from
within a procedure, return -code return result). An
error return (via error) will return an error result, as is if
the script caused the error. Any other return will evaluate the
script in buffer as normal. For compatibility with 3.2,
break and return -code break result is supported,
acting similarly to return {} and return -code return
result.
Examples:
% ::comm::comm send [lb]::comm::comm self[rb] pid
5013
% ::comm::comm hook eval {puts "going to execute $buffer"}
% ::comm::comm send [lb]::comm::comm self[rb] pid
going to execute pid
5013
% ::comm::comm hook eval {puts "would have executed $buffer"; return 0} % ::comm::comm send [lb]::comm::comm self[rb] pid would have executed pid 0 |
% ::comm::comm send [lb]::comm::comm self[rb] llength {a b c} wrong # args: should be "llength list" % ::comm::comm hook eval {return [uplevel #0 $buffer]} return [lb]uplevel #0 $buffer[rb] % ::comm::comm send [lb]::comm::comm self[rb] llength {a b c} 3 |
% interp create foo % ::comm::comm hook eval {return [lb]foo eval $buffer[rb]} % ::comm::comm send [lb]::comm::comm self[rb] set myvar 123 123 % set myvar can't read "myvar": no such variable % foo eval set myvar 123 |
% ::comm::comm hook eval {return [lb]eval foo eval $buffer[rb]} |
% ::comm::comm hook eval { switch -- $buffer { a {return A-OK} b {return B-OK} default {error "$buffer is a no-no"} } } % ::comm::comm send [lb]::comm::comm self[rb] pid pid is a no-no % ::comm::comm send [lb]::comm::comm self[rb] a A-OK |
::comm::comm hook lost { global myvar if {$myvar(id) == $id} { myfunc return } } |
These interfaces may change or go away in subsequence releases.
proc send {args} { eval ::comm::comm send $args } rename winfo tk_winfo proc winfo {cmd args} { if ![lb]string match in* $cmd[rb] {return [lb]eval [lb]list tk_winfo $cmd[rb] $args[rb]} return [lb]::comm::comm interps[rb] } |
Something here soon.
There is one outstanding difference between comm and
send. When blocking in a synchronous remote command, send
uses an internal C hook (Tk_RestrictEvents) to the event loop to look
ahead for send-related events and only process those without
processing any other events. In contrast, comm uses the
vwait command as a semaphore to indicate the return message has
arrived. The difference is that a synchronous send will block
the application and prevent all events (including window related ones)
from being processed, while a synchronous comm will block the
application but still allow other events will still get processed. In
particular, after idle handlers will fire immediately when
comm blocks.
What can be done about this? First, note that this behavior will come
from any code using vwait to block and wait for an event to
occur. At the cost of multiple channel support, comm could
be changed to do blocking I/O on the socket, giving send-like blocking
semantics. However, multiple channel support is a very useful feature
of comm that it is deemed too important to lose. The remaining
approaches involve a new loadable module written in C (which is
somewhat against the philosophy of comm) One way would be to
create a modified version of the vwait command that allow the
event flags passed to Tcl_DoOneEvent to be specified. For comm,
just the TCL_FILE_EVENTS would be processed. Another way would be to
implement a mechanism like Tk_RestrictEvents, but apply it to the Tcl
event loop (since comm doesn't require Tk). One of these
approaches will be available in a future comm release as an
optional component.
comm exports itself as a package. The package version number
is in the form major . minor, where the major version will
only change when a non-compatible change happens to the API or
protocol. Minor bug fixes and changes will only affect the minor
version. To load comm this command is usually used:
BLOCKING SEMANTICS
COMPATIBILITY
package require comm 3 |
Note that requiring no version (or a specific version) can also be done.
The revision history of comm includes these releases:
comm send id break catch {comm send id break} comm send id expr 1 / 0 |
http://www.opengroup.org/~loverso/tcl-tk/#comm
This license for comm, new as of version 3.2, allows it to be
used for free, without any licensing fee or royalty.
The following items can be implemented with the existing hooks and are
listed here as a reminder to provide a sample hook in a future
version.
The following are outstanding todo items.
This man page is bigger than the source file.
Tcl7.5 under Windows contains a bug that causes the interpreter to
hang when EOF is reached on non-blocking sockets. This can be
triggered with a command such as this:
COPYRIGHT
Copyright (C) 1995-1998 The Open Group. All Rights Reserved.
Please see the file comm.LICENSE that accompanied this source,
or
http://www.opengroup.org/www/dist_client/caubweb/COPYRIGHT.free.html.
BUGS
ON USING OLD VERSIONS OF TCL
"comm send $other exit" |
Always make sure the channel is quiescent before closing/exiting or use at least Tcl7.6 under Windows.
Tcl7.6 on the Mac contains several bugs. It is recommended you use at least Tcl7.6p2.
Tcl8.0 on UNIX contains a socket bug that can crash Tcl. It is recommended
you use Tcl8.0p1 (or Tcl7.6p2).
Tcl-DP provides an RPC-based remote execution interface, but is a
compiled Tcl extension. See
http://www.cs.cornell.edu/Info/Projects/zeno/Projects/Tcl-DP.html.
Michael Doyle <miked@eolas.com> has code that implements the Tcl-DP
RPC interface using standard Tcl sockets, much like comm
Andreas Kupries <andreas_kupries@users.sourceforge.net> uses
comm and has built a simple nameserver as part of his Pool
library. See http://www.purl.org/net/akupries/soft/pool/index.htm.
RELATED WORK
SEE ALSO
send(n)