1comm(n) Remote communication comm(n)
2______________________________________________________________________________
6
8 comm - A remote communication facility for Tcl (8.3 and later)
9
11 package require Tcl 8.3
12 package require comm ?4.6.3?
14 ::comm::comm send ?-async? ?-command callback? id cmd ?arg arg ...?
16 ::comm::comm self
18 ::comm::comm interps
20 ::comm::comm connect ?id?
22 ::comm::comm new chan ?name value ...?
24 ::comm::comm channels
26 ::comm::comm config
28 ::comm::comm config name
30 ::comm::comm config ?name value ...?
32 ::comm::comm shutdown id
34 ::comm::comm abort
36 ::comm::comm destroy
38 ::comm::comm hook event ?+? ?script?
40 ::comm::comm remoteid
42 ::comm::comm_send
44 ::comm::comm return_async
46 $future return ?-code code? ?value?
48 $future configure ?-command ?cmdprefix??
50 $future cget -command
52______________________________________________________________________________
54
56 The comm command provides an inter-interpreter remote execution facil‐
57 ity much like Tk's send(n), except that it uses sockets rather than the
58 X server for the communication path. As a result, comm works with mul‐
59 tiple interpreters, works on Windows and Macintosh systems, and pro‐
60 vides control over the remote execution path.
61 These commands work just like send and winfo interps :
63 ::comm::comm send ?-async? id cmd ?arg arg ...?
65 ::comm::comm interps
66 This is all that is really needed to know in order to use comm
69 COMMANDS
71 The package initializes ::comm::comm as the default chan.
72 comm names communication endpoints with an id unique to each machine.
74 Before sending commands, the id of another interpreter is needed. Un‐
75 like Tk's send, comm doesn't implicitly know the id's of all the inter‐
76 preters on the system. The following four methods make up the basic
77 comm interface.
78 ::comm::comm send ?-async? ?-command callback? id cmd ?arg arg ...?
80 This invokes the given command in the interpreter named by id.
81 The command waits for the result and remote errors are returned
82 unless the -async or -command option is given. If -async is
83 given, send returns immediately and there is no further notifi‐
84 cation of result. If -command is used, callback specifies a
85 command to invoke when the result is received. These options
86 are mutually exclusive. The callback will receive arguments in
87 the form -option value, suitable for array set. The options
88 are: -id, the comm id of the interpreter that received the com‐
89 mand; -serial, a unique serial for each command sent to a par‐
90 ticular comm interpreter; -chan, the comm channel name; -code,
91 the result code of the command; -errorcode, the errorcode, if
92 any, of the command; -errorinfo, the errorinfo, if any, of the
93 command; and -result, the return value of the command. If con‐
94 nection is lost before a reply is received, the callback will be
95 invoked with a connection lost message with -code equal to -1.
96 When -command is used, the command returns the unique serial for
97 the command.
98 ::comm::comm self
100 Returns the id for this channel.
101 ::comm::comm interps
103 Returns a list of all the remote id's to which this channel is
104 connected. comm learns a new remote id when a command is first
105 issued it, or when a remote id first issues a command to this
106 comm channel. ::comm::comm ids is an alias for this method.
107 ::comm::comm connect ?id?
109 Whereas ::comm::comm send will automatically connect to the
110 given id, this forces a connection to a remote id without send‐
111 ing a command. After this, the remote id will appear in
112 ::comm::comm interps.
113 EVAL SEMANTICS
115 The evaluation semantics of ::comm::comm send are intended to match
116 Tk's send exactly. This means that comm evaluates arguments on the re‐
117 mote side.
118 If you find that ::comm::comm send doesn't work for a particular com‐
120 mand, try the same thing with Tk's send and see if the result is dif‐
121 ferent. If there is a problem, please report it. For instance, there
122 was had one report that this command produced an error. Note that the
123 equivalent send command also produces the same error.
124 % ::comm::comm send id llength {a b c}
126 wrong # args: should be "llength list"
127 % send name llength {a b c}
128 wrong # args: should be "llength list"
129 The eval hook (described below) can be used to change from send's dou‐
132 ble eval semantics to single eval semantics.
133 MULTIPLE CHANNELS
135 More than one comm channel (or listener) can be created in each Tcl in‐
136 terpreter. This allows flexibility to create full and restricted chan‐
137 nels. For instance, hook scripts are specific to the channel they are
138 defined against.
139 ::comm::comm new chan ?name value ...?
141 This creates a new channel and Tcl command with the given chan‐
142 nel name. This new command controls the new channel and takes
143 all the same arguments as ::comm::comm. Any remaining arguments
144 are passed to the config method. The fully qualified channel
145 name is returned.
146 ::comm::comm channels
148 This lists all the channels allocated in this Tcl interpreter.
149 The default configuration parameters for a new channel are:
151 "-port 0 -local 1 -listen 0 -silent 0"
153 The default channel ::comm::comm is created with:
156 "::comm::comm new ::comm::comm -port 0 -local 1 -listen 1 -silent 0"
158 CHANNEL CONFIGURATION
161 The config method acts similar to fconfigure in that it sets or queries
162 configuration variables associated with a channel.
163 ::comm::comm config
165 ::comm::comm config name
167 ::comm::comm config ?name value ...?
169 When given no arguments, config returns a list of all variables
170 and their value With one argument, config returns the value of
171 just that argument. With an even number of arguments, the given
172 variables are set to the given values.
173 These configuration variables can be changed (descriptions of them are
175 elsewhere in this manual page):
176 -listen ?0|1?
178 -local ?0|1?
180 -port ?port?
182 -silent ?0|1?
184 -socketcmd ?commandname?
186 -interp ?interpreter?
188 -events ?eventlist?
190 These configuration variables are read only:
192 -chan chan
194 -serial n
196 -socket sockIn
198 When config changes the parameters of an existing channel (with the ex‐
200 ception of -interp and -events), it closes and reopens the listening
201 socket. An automatically assigned channel id will change when this
202 happens. Recycling the socket is done by invoking ::comm::comm abort,
203 which causes all active sends to terminate.
204 ID/PORT ASSIGNMENTS
206 comm uses a TCP port for endpoint id. The interps (or ids) method
207 merely lists all the TCP ports to which the channel is connected. By
208 default, each channel's id is randomly assigned by the operating system
209 (but usually starts at a low value around 1024 and increases each time
210 a new socket is opened). This behavior is accomplished by giving the
211 -port config option a value of 0. Alternately, a specific TCP port
212 number may be provided for a given channel. As a special case, comm
213 contains code to allocate a a high-numbered TCP port (>10000) by using
214 -port {}. Note that a channel won't be created and initialized unless
215 the specific port can be allocated.
216 As a special case, if the channel is configured with -listen 0, then it
218 will not create a listening socket and will use an id of 0 for itself.
219 Such a channel is only good for outgoing connections (although once a
220 connection is established, it can carry send traffic in both direc‐
221 tions). As another special case, if the channel is configured with
222 -silent 0, then the listening side will ignore connection attempts
223 where the protocol negotiation phase failed, instead of throwing an er‐
224 ror.
225 EXECUTION ENVIRONMENT
227 A communication channel in its default configuration will use the cur‐
228 rent interpreter for the execution of all received scripts, and of the
229 event scripts associated with the various hooks.
230 This insecure setup can be changed by the user via the two options -in‐
232 terp, and -events.
233 When -interp is set all received scripts are executed in the slave in‐
235 terpreter specified as the value of the option. This interpreter is ex‐
236 pected to exist before configuration. I.e. it is the responsibility of
237 the user to create it. However afterward the communication channel
238 takes ownership of this interpreter, and will destroy it when the com‐
239 munication channel is destroyed. Note that reconfiguration of the com‐
240 munication channel to either a different interpreter or the empty
241 string will release the ownership without destroying the previously
242 configured interpreter. The empty string has a special meaning, it re‐
243 stores the default behaviour of executing received scripts in the cur‐
244 rent interpreter.
245 Also of note is that replies and callbacks (a special form of reply)
247 are not considered as received scripts. They are trusted, part of the
248 internal machinery of comm, and therefore always executed in the cur‐
249 rent interpreter.
250 Even if an interpreter has been configured as the execution environment
252 for received scripts the event scripts associated with the various
253 hooks will by default still be executed in the current interpreter. To
254 change this use the option -events to declare a list of the events
255 whose scripts should be executed in the declared interpreter as well.
256 The contents of this option are ignored if the communication channel is
257 configured to execute received scripts in the current interpreter.
258 REMOTE INTERPRETERS
260 By default, each channel is restricted to accepting connections from
261 the local system. This can be overridden by using the -local 0 config‐
262 uration option For such channels, the id parameter takes the form { id
263 host }.
264 WARNING: The host must always be specified in the same form (e.g., as
266 either a fully qualified domain name, plain hostname or an IP address).
267 CLOSING CONNECTIONS
269 These methods give control over closing connections:
270 ::comm::comm shutdown id
272 This closes the connection to id, aborting all outstanding com‐
273 mands in progress. Note that nothing prevents the connection
274 from being immediately reopened by another incoming or outgoing
275 command.
276 ::comm::comm abort
278 This invokes shutdown on all open connections in this comm chan‐
279 nel.
280 ::comm::comm destroy
282 This aborts all connections and then destroys the this comm
283 channel itself, including closing the listening socket. Special
284 code allows the default ::comm::comm channel to be closed such
285 that the ::comm::comm command it is not destroyed. Doing so
286 closes the listening socket, preventing both incoming and outgo‐
287 ing commands on the channel. This sequence reinitializes the
288 default channel:
289 "::comm::comm destroy; ::comm::comm new ::comm::comm"
293 When a remote connection is lost (because the remote exited or called
296 shutdown), comm can invoke an application callback. This can be used
297 to cleanup or restart an ancillary process, for instance. See the lost
298 callback below.
299 CALLBACKS
301 This is a mechanism for setting hooks for particular events:
302 ::comm::comm hook event ?+? ?script?
304 This uses a syntax similar to Tk's bind command. Prefixing
305 script with a + causes the new script to be appended. Without
306 this, a new script replaces any existing script. When invoked
307 without a script, no change is made. In all cases, the new hook
308 script is returned by the command.
309 When an event occurs, the script associated with it is evaluated
311 with the listed variables in scope and available. The return
312 code (not the return value) of the script is commonly used de‐
313 cide how to further process after the hook.
314 Common variables include:
316 chan the name of the comm channel (and command)
318 id the id of the remote in question
320 fid the file id for the socket of the connection
322 These are the defined events:
324 connecting
326 Variables: chan, id
327 This hook is invoked before making a connection to the remote
329 named in id. An error return (via error) will abort the connec‐
330 tion attempt with the error. Example:
331 % ::comm::comm hook connecting {
335 if {[string match {*[02468]} $id]} {
336 error "Can't connect to even ids"
337 }
338 }
339 % ::comm::comm send 10000 puts ok
340 Connect to remote failed: Can't connect to even ids
341 %
342 connected
345 Variables: chan, fid, id, host, and port.
346 This hook is invoked immediately after making a remote connec‐
348 tion to id, allowing arbitrary authentication over the socket
349 named by fid. An error return (via error ) will close the con‐
350 nection with the error. host and port are merely extracted from
351 the id; changing any of these will have no effect on the connec‐
352 tion, however. It is also possible to substitute and replace
353 fid.
354 incoming
356 Variables: chan, fid, addr, and remport.
357 Hook invoked when receiving an incoming connection, allowing ar‐
359 bitrary authentication over socket named by fid. An error re‐
360 turn (via error) will close the connection with the error. Note
361 that the peer is named by remport and addr but that the remote
362 id is still unknown. Example:
363 ::comm::comm hook incoming {
367 if {[string match 127.0.0.1 $addr]} {
368 error "I don't talk to myself"
369 }
370 }
371 eval Variables: chan, id, cmd, and buffer.
374 This hook is invoked after collecting a complete script from a
376 remote but before evaluating it. This allows complete control
377 over the processing of incoming commands. cmd contains either
378 send or async. buffer holds the script to evaluate. At the
379 time the hook is called, $chan remoteid is identical in value to
380 id.
381 By changing buffer, the hook can change the script to be evalu‐
383 ated. The hook can short circuit evaluation and cause a value
384 to be immediately returned by using return result (or, from
385 within a procedure, return -code return result). An error re‐
386 turn (via error) will return an error result, as is if the
387 script caused the error. Any other return will evaluate the
388 script in buffer as normal. For compatibility with 3.2, break
389 and return -code break result is supported, acting similarly to
390 return {} and return -code return result.
391 Examples:
393 [1] augmenting a command
395 % ::comm::comm send [::comm::comm self] pid
399 5013
400 % ::comm::comm hook eval {puts "going to execute $buffer"}
401 % ::comm::comm send [::comm::comm self] pid
402 going to execute pid
403 5013
404 [2] short circuiting a command
407 % ::comm::comm hook eval {puts "would have executed $buffer"; return 0}
411 % ::comm::comm send [::comm::comm self] pid
412 would have executed pid
413 0
414 [3] Replacing double eval semantics
417 % ::comm::comm send [::comm::comm self] llength {a b c}
421 wrong # args: should be "llength list"
422 % ::comm::comm hook eval {return [uplevel #0 $buffer]}
423 return [uplevel #0 $buffer]
424 % ::comm::comm send [::comm::comm self] llength {a b c}
425 3
426 [4] Using a slave interpreter
429 % interp create foo
433 % ::comm::comm hook eval {return [foo eval $buffer]}
434 % ::comm::comm send [::comm::comm self] set myvar 123
435 123
436 % set myvar
437 can't read "myvar": no such variable
438 % foo eval set myvar
439 123
440 [5] Using a slave interpreter (double eval)
443 % ::comm::comm hook eval {return [eval foo eval $buffer]}
447 [6] Subverting the script to execute
450 % ::comm::comm hook eval {
454 switch -- $buffer {
455 a {return A-OK}
456 b {return B-OK}
457 default {error "$buffer is a no-no"}
458 }
459 }
460 % ::comm::comm send [::comm::comm self] pid
461 pid is a no-no
462 % ::comm::comm send [::comm::comm self] a
463 A-OK
464 reply Variables: chan, id, buffer, ret, and return().
467 This hook is invoked after collecting a complete reply script
469 from a remote but before evaluating it. This allows complete
470 control over the processing of replies to sent commands. The
471 reply buffer is in one of the following forms
472 • return result
474 • return -code code result
476 • return -code code -errorinfo info -errorcode ecode msg
478 For safety reasons, this is decomposed. The return result is in ret,
480 and the return switches are in the return array:
481 • return(-code)
483 • return(-errorinfo)
485 • return(-errorcode)
487 Any of these may be the empty string. Modifying these four variables
489 can change the return value, whereas modifying buffer has no effect.
490 callback
492 Variables: chan, id, buffer, ret, and return().
493 Similar to reply, but used for callbacks.
495 lost Variables: chan, id, and reason.
497 This hook is invoked when the connection to id is lost. Return
499 value (or thrown error) is ignored. reason is an explanatory
500 string indicating why the connection was lost. Example:
501 ::comm::comm hook lost {
505 global myvar
506 if {$myvar(id) == $id} {
507 myfunc
508 return
509 }
510 }
511 UNSUPPORTED
514 These interfaces may change or go away in subsequence releases.
515 ::comm::comm remoteid
517 Returns the id of the sender of the last remote command executed
518 on this channel. If used by a proc being invoked remotely, it
519 must be called before any events are processed. Otherwise, an‐
520 other command may get invoked and change the value.
521 ::comm::comm_send
523 Invoking this procedure will substitute the Tk send and winfo
524 interps commands with these equivalents that use ::comm::comm.
525 proc send {args} {
529 eval ::comm::comm send $args
530 }
531 rename winfo tk_winfo
532 proc winfo {cmd args} {
533 if {![string match in* $cmd]} {
534 return [eval [list tk_winfo $cmd] $args]
535 }
536 return [::comm::comm interps]
537 }
538 SECURITY
541 Starting with version 4.6 of the package an option -socketcmd is sup‐
542 ported, allowing the user of a comm channel to specify which command to
543 use when opening a socket. Anything which is API-compatible with the
544 builtin ::socket (the default) can be used.
545 The envisioned main use is the specification of the tls::socket com‐
547 mand, see package tls, to secure the communication.
548 # Load and initialize tls
550 package require tls
551 tls::init -cafile /path/to/ca/cert -keyfile ...
552 # Create secured comm channel
554 ::comm::comm new SECURE -socketcmd tls::socket -listen 1
555 ...
556 The sections Execution Environment and Callbacks are also relevant to
559 the security of the system, providing means to restrict the execution
560 to a specific environment, perform additional authentication, and the
561 like.
562 BLOCKING SEMANTICS
564 There is one outstanding difference between comm and send. When block‐
565 ing in a synchronous remote command, send uses an internal C hook
566 (Tk_RestrictEvents) to the event loop to look ahead for send-related
567 events and only process those without processing any other events. In
568 contrast, comm uses the vwait command as a semaphore to indicate the
569 return message has arrived. The difference is that a synchronous send
570 will block the application and prevent all events (including window re‐
571 lated ones) from being processed, while a synchronous ::comm::comm send
572 will block the application but still allow other events to get pro‐
573 cessed. In particular, after idle handlers will fire immediately when
574 comm blocks.
575 What can be done about this? First, note that this behavior will come
577 from any code using vwait to block and wait for an event to occur. At
578 the cost of multiple channel support, comm could be changed to do
579 blocking I/O on the socket, giving send-like blocking semantics. How‐
580 ever, multiple channel support is a very useful feature of comm that it
581 is deemed too important to lose. The remaining approaches involve a
582 new loadable module written in C (which is somewhat against the philos‐
583 ophy of comm) One way would be to create a modified version of the
584 vwait command that allow the event flags passed to Tcl_DoOneEvent to be
585 specified. For comm, just the TCL_FILE_EVENTS would be processed. An‐
586 other way would be to implement a mechanism like Tk_RestrictEvents, but
587 apply it to the Tcl event loop (since comm doesn't require Tk). One of
588 these approaches will be available in a future comm release as an op‐
589 tional component.
590 ASYNCHRONOUS RESULT GENERATION
592 By default the result returned by a remotely invoked command is the re‐
593 sult sent back to the invoker. This means that the result is generated
594 synchronously, and the server handling the call is blocked for the du‐
595 ration of the command.
596 While this is tolerable as long as only short-running commands are in‐
598 voked on the server long-running commands, like database queries make
599 this a problem. One command can prevent the processing requests of all
600 other clients for an arbitrary period of time.
601 Before version 4.5 of comm the only solution was to rewrite the server
603 command to use the Tcl builtin command vwait, or one of its relatives
604 like tkwait, to open a new event loop which processes requests while
605 the long-running operation is executed. This however has its own per‐
606 ils, as this makes it possible to both overflow the Tcl stack with a
607 large number of event loop, and to have a newer requests block the re‐
608 turn of older ones, as the eventloop have to be unwound in the order of
609 their creation.
610 The proper solution is to have the invoked command indicate to comm
612 that it cannot or will not deliver an immediate, synchronous result,
613 but will do so later. At that point the framework can put sending the
614 actual result on hold and continue processing requests using the main
615 event loop. No blocking, no nesting of event loops. At some future date
616 the long running operation delivers the result to comm, via the future
617 object, which is then forwarded to the invoker as usual.
618 The necessary support for this solution has been added to comm since
620 version 4.5, in the form of the new method return_async.
621 ::comm::comm return_async
623 This command is used by a remotely invoked script to notify the
624 comm channel which invoked it that the result to send back to
625 the invoker is not generated synchronously. If this command is
626 not called the default/standard behaviour of comm is to send the
627 synchronously generated result of the script itself to the in‐
628 voker.
629 The result of return_async is an object. This object, called a
631 future is where the result of the script has to be delivered to
632 when it becomes ready. When that happens it will take all the
633 necessary actions to deliver the result to the invoker of the
634 script, and then destroy itself. Should comm have lost the con‐
635 nection to the invoker while the result is being computed the
636 future will not try to deliver the result it got, but just de‐
637 stroy itself. The future can be configured with a command to
638 call when the invoker is lost. This enables the user to imple‐
639 ment an early abort of the long-running operation, should this
640 be supported by it.
641 An example:
643 # Procedure invoked by remote clients to run database operations.
646 proc select {sql} {
647 # Signal the async generation of the result
648 set future [::comm::comm return_async]
650 # Generate an async db operation and tell it where to deliver the result.
652 set query [db query -command [list $future return] $sql]
654 # Tell the database system which query to cancel if the connection
656 # goes away while it is running.
657 $future configure -command [list db cancel $query]
659 # Note: The above will work without problem only if the async
661 # query will nover run its completion callback immediately, but
662 # only from the eventloop. Because otherwise the future we wish to
663 # configure may already be gone. If that is possible use 'catch'
664 # to prevent the error from propagating.
665 return
666 }
667 The API of a future object is:
670 $future return ?-code code? ?value?
672 Use this method to tell the future that long-running op‐
673 eration has completed. Arguments are an optional return
674 value (defaults to the empty string), and the Tcl return
675 code (defaults to OK).
676 The future will deliver this information to invoker, if
678 the connection was not lost in the meantime, and then de‐
679 stroy itself. If the connection was lost it will do noth‐
680 ing but destroy itself.
681 $future configure ?-command ?cmdprefix??
683 $future cget -command
685 These methods allow the user to retrieve and set a com‐
686 mand to be called if the connection the future belongs to
687 has been lost.
688 COMPATIBILITY
690 comm exports itself as a package. The package version number is in the
691 form major . minor, where the major version will only change when a
692 non-compatible change happens to the API or protocol. Minor bug fixes
693 and changes will only affect the minor version. To load comm this com‐
694 mand is usually used:
695 package require comm 3
697 Note that requiring no version (or a specific version) can also be
700 done.
701 The revision history of comm includes these releases:
703 4.6.3 Fixed ticket [ced0d60fc9]. Added proper detection of eof on a
705 socket, properly closing it.
706 4.6.2 Fixed bugs 2972571 and 3066872, the first a misdetection of
708 quoted brace after double backslash, the other a blocking gets
709 making for an obvious (hinsight) DoS attack on comm channels.
710 4.6.1 Changed the implementation of comm::commCollect to emulate lin‐
712 dex's pre-Tcl 8 behaviour, i.e. it was given the ability to
713 parse out the first word of a list, even if the whole buffer is
714 not a well-formed list. Without this change the first word could
715 only be extracted if the whole buffer was a well-formed list
716 (ever since Tcl 8), and in a ver-high-load situation, i.e. a
717 server sending lots and/or large commands very fast, this may
718 never happen, eventually crashing the receiver when it runs out
719 of memory. With the change the receiver is always able to
720 process the first word when it becomes well-formed, regardless
721 of the structure of the remainder of the buffer.
722 4.6 Added the option -socketcmd enabling users to override how a
724 socket is opened. The envisioned main use is the specification
725 of the tls::socket command, see package tls, to secure the com‐
726 munication.
727 4.5.7 Changed handling of ports already in use to provide a proper er‐
729 ror message.
730 4.5.6 Bugfix in the replacement for vwait, made robust against of
732 variable names containing spaces.
733 4.5.5 Bugfix in the handling of hooks, typo in variable name.
735 4.5.4 Bugfix in the handling of the result received by the send
737 method. Replaced an after idle unset result with an immediate
738 unset, with the information saved to a local variable.
739 The after idle can spill into a forked child process if there is
741 no event loop between its setup and the fork. This may bork the
742 child if the next event loop is the vwait of comm's send a few
743 lines above the after idle, and the child used the same serial
744 number for its next request. In that case the parent's after
745 idle unset will delete the very array element the child is wait‐
746 ing for, unlocking the vwait, causing it to access a now missing
747 array element, instead of the expected result.
748 4.5.3 Bugfixes in the wrappers for the builtin update and vwait com‐
750 mands.
751 4.5.2 Bugfix in the wrapper for the builtin update command.
753 4.5.1 Bugfixes in the handling of -interp for regular scripts. The
755 handling of the buffer was wrong for scripts which are a single
756 statement as list. Fixed missing argument to new command comm‐
757 SendReply, introduced by version 4.5. Affected debugging.
758 4.5 New server-side feature. The command invoked on the server can
760 now switch comm from the standard synchronous return of its re‐
761 sult to an asynchronous (defered) return. Due to the use of snit
762 to implement the future objects used by this feature from this
763 version on comm requires at least Tcl 8.3 to run. Please read
764 the section Asynchronous Result Generation for more details.
765 4.4.1 Bugfix in the execution of hooks.
767 4.4 Bugfixes in the handling of -interp for regular and hook
769 scripts. Bugfixes in channel cleanup.
770 4.3.1 Introduced -interp and -events to enable easy use of a slave in‐
772 terp for execution of received scripts, and of event scripts.
773 4.3 Bugfixes, and introduces -silent to allow the user to force the
775 server/listening side to silently ignore connection attempts
776 where the protocol negotiation failed.
777 4.2 Bugfixes, and most important, switched to utf-8 as default en‐
779 coding for full i18n without any problems.
780 4.1 Rewrite of internal code to remove old pseudo-object model. Ad‐
782 dition of send -command asynchronous callback option.
783 4.0 Per request by John LoVerso. Improved handling of error for
785 async invoked commands.
786 3.7 Moved into tcllib and placed in a proper namespace.
788 3.6 A bug in the looking up of the remoteid for a executed command
790 could be triggered when the connection was closed while several
791 asynchronous sends were queued to be executed.
792 3.5 Internal change to how reply messages from a send are handled.
794 Reply messages are now decoded into the value to pass to return;
795 a new return statement is then cons'd up to with this value.
796 Previously, the return code was passed in from the remote as a
797 command to evaluate. Since the wire protocol has not changed,
798 this is still the case. Instead, the reply handling code de‐
799 codes the reply message.
800 3.4 Added more source commentary, as well as documenting config
802 variables in this man page. Fixed bug were loss of connection
803 would give error about a variable named pending rather than the
804 message about the lost connection. comm ids is now an alias for
805 comm interps (previously, it an alias for comm chans). Since
806 the method invocation change of 3.0, break and other exceptional
807 conditions were not being returned correctly from comm send.
808 This has been fixed by removing the extra level of indirection
809 into the internal procedure commSend. Also added propagation of
810 the errorCode variable. This means that these commands return
811 exactly as they would with send:
812 comm send id break
816 catch {comm send id break}
817 comm send id expr 1 / 0
818 Added a new hook for reply messages. Reworked method invocation to
821 avoid the use of comm:* procedures; this also cut the invocation time
822 down by 40%. Documented comm config (as this manual page still listed
823 the defunct comm init!)
824 3.3 Some minor bugs were corrected and the documentation was cleaned
826 up. Added some examples for hooks. The return semantics of the
827 eval hook were changed.
828 3.2 A new wire protocol, version 3, was added. This is backwards
830 compatible with version 2 but adds an exchange of supported pro‐
831 tocol versions to allow protocol negotiation in the future.
832 Several bugs with the hook implementation were fixed. A new
833 section of the man page on blocking semantics was added.
834 3.1 All the documented hooks were implemented. commLostHook was re‐
836 moved. A bug in comm new was fixed.
837 3.0 This is a new version of comm with several major changes. There
839 is a new way of creating the methods available under the comm
840 command. The comm init method has been retired and is replaced
841 by comm configure which allows access to many of the well-de‐
842 fined internal variables. This also generalizes the options
843 available to comm new. Finally, there is now a protocol version
844 exchanged when a connection is established. This will allow for
845 future on-wire protocol changes. Currently, the protocol ver‐
846 sion is set to 2.
847 2.3 comm ids was renamed to comm channels. General support for comm
849 hook was fully implemented, but only the lost hook exists, and
850 it was changed to follow the general hook API. commLostHook was
851 unsupported (replaced by comm hook lost) and commLost was re‐
852 moved.
853 2.2 The died hook was renamed lost, to be accessed by commLostHook
855 and an early implementation of comm lost hook. As such, com‐
856 mDied is now commLost.
857 2.1 Unsupported method comm remoteid was added.
859 2.0 comm has been rewritten from scratch (but is fully compatible
861 with Comm 1.0, without the requirement to use obTcl).
862
864 This package uses the TLS package to handle the security for https urls
865 and other socket connections.
866 Policy decisions like the set of protocols to support and what ciphers
868 to use are not the responsibility of TLS, nor of this package itself
869 however. Such decisions are the responsibility of whichever applica‐
870 tion is using the package, and are likely influenced by the set of
871 servers the application will talk to as well.
872 For example, in light of the recent POODLE attack [http://googleonli‐
874 nesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-
875 ssl-30.html] discovered by Google many servers will disable support for
876 the SSLv3 protocol. To handle this change the applications using TLS
877 must be patched, and not this package, nor TLS itself. Such a patch
878 may be as simple as generally activating tls1 support, as shown in the
879 example below.
880 package require tls
883 tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
884 ... your own application code ...
886
889 John LoVerso, John@LoVerso.Southborough.MA.US
890 http://www.opengroup.org/~loverso/tcl-tk/#comm
892
894 Please see the file comm.LICENSE that accompanied this source, or
895 http://www.opengroup.org/www/dist_client/caubweb/COPYRIGHT.free.html.
896 This license for comm, new as of version 3.2, allows it to be used for
898 free, without any licensing fee or royalty.
899
901 • If there is a failure initializing a channel created with
902 ::comm::comm new, then the channel should be destroyed. Cur‐
903 rently, it is left in an inconsistent state.
904 • There should be a way to force a channel to quiesce when chang‐
906 ing the configuration.
907 The following items can be implemented with the existing hooks and are
909 listed here as a reminder to provide a sample hook in a future version.
910 • Allow easier use of a slave interp for actual command execution
912 (especially when operating in "not local" mode).
913 • Add host list (xhost-like) or "magic cookie" (xauth-like) au‐
915 thentication to initial handshake.
916 The following are outstanding todo items.
918 • Add an interp discovery and name->port mapping. This is likely
920 to be in a separate, optional nameserver. (See also the related
921 work, below.)
922 • Fix the {id host} form so as not to be dependent upon canonical
924 hostnames. This requires fixes to Tcl to resolve hostnames!
925 This man page is bigger than the source file.
927
929 Tcl7.5 under Windows contains a bug that causes the interpreter to hang
930 when EOF is reached on non-blocking sockets. This can be triggered
931 with a command such as this:
932 "comm send $other exit"
934 Always make sure the channel is quiescent before closing/exiting or use
937 at least Tcl7.6 under Windows.
938 Tcl7.6 on the Mac contains several bugs. It is recommended you use at
940 least Tcl7.6p2.
941 Tcl8.0 on UNIX contains a socket bug that can crash Tcl. It is recom‐
943 mended you use Tcl8.0p1 (or Tcl7.6p2).
944
946 Tcl-DP provides an RPC-based remote execution interface, but is a com‐
947 piled Tcl extension. See http://www.cs.cor‐
948 nell.edu/Info/Projects/zeno/Projects/Tcl-DP.html.
949 Michael Doyle <miked@eolas.com> has code that implements the Tcl-DP RPC
951 interface using standard Tcl sockets, much like comm. The DpTcl pack‐
952 age is available at http://chiselapp.com/user/gwlester/reposi‐
953 tory/DpTcl.
954 Andreas Kupries <andreas_kupries@users.sourceforge.net> uses comm and
956 has built a simple nameserver as part of his Pool library. See
957 http://www.purl.org/net/akupries/soft/pool/index.htm.
958
960 This document, and the package it describes, will undoubtedly contain
961 bugs and other problems. Please report such in the category comm of
962 the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
963 also report any ideas for enhancements you may have for either package
964 and/or documentation.
965 When proposing code changes, please provide unified diffs, i.e the out‐
967 put of diff -u.
968 Note further that attachments are strongly preferred over inlined
970 patches. Attachments can be made by going to the Edit form of the
971 ticket immediately after its creation, and then using the left-most
972 button in the secondary navigation bar.
973
975 send(n)
976
978 comm, communication, ipc, message, remote communication, remote execu‐
979 tion, rpc, secure, send, socket, ssl, tls
980
982 Programming tools
983
985 Copyright (c) 1995-1998 The Open Group. All Rights Reserved.
986 Copyright (c) 2003-2004 ActiveState Corporation.
987 Copyright (c) 2006-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
988tcllib 4.6.3 comm(n)