1comm(n)                      Remote communication                      comm(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       comm - A remote communication facility for Tcl (8.3 and later)
9

SYNOPSIS

11       package require Tcl  8.3
12
13       package require comm  ?4.6.3?
14
15       ::comm::comm send ?-async? ?-command callback? id cmd ?arg arg ...?
16
17       ::comm::comm self
18
19       ::comm::comm interps
20
21       ::comm::comm connect ?id?
22
23       ::comm::comm new chan ?name value ...?
24
25       ::comm::comm channels
26
27       ::comm::comm config
28
29       ::comm::comm config name
30
31       ::comm::comm config ?name value ...?
32
33       ::comm::comm shutdown id
34
35       ::comm::comm abort
36
37       ::comm::comm destroy
38
39       ::comm::comm hook event ?+? ?script?
40
41       ::comm::comm remoteid
42
43       ::comm::comm_send
44
45       ::comm::comm return_async
46
47       $future return ?-code code? ?value?
48
49       $future configure ?-command ?cmdprefix??
50
51       $future cget -command
52
53______________________________________________________________________________
54

DESCRIPTION

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
62       These commands work just like send and winfo interps :
63
64                  ::comm::comm send ?-async? id cmd ?arg arg ...?
65                  ::comm::comm interps
66
67
68       This is all that is really needed to know in order to use comm
69
70   COMMANDS
71       The package initializes ::comm::comm as the default chan.
72
73       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
79       ::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
99       ::comm::comm self
100              Returns the id for this channel.
101
102       ::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
108       ::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
114   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
119       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
125                  % ::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
130
131       The eval hook (described below) can be used to change from send's  dou‐
132       ble eval semantics to single eval semantics.
133
134   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
140       ::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
147       ::comm::comm channels
148              This lists all the channels allocated in this Tcl interpreter.
149
150       The default configuration parameters for a new channel are:
151
152                  "-port 0 -local 1 -listen 0 -silent 0"
153
154
155       The default channel ::comm::comm is created with:
156
157                  "::comm::comm new ::comm::comm -port 0 -local 1 -listen 1 -silent 0"
158
159
160   CHANNEL CONFIGURATION
161       The config method acts similar to fconfigure in that it sets or queries
162       configuration variables associated with a channel.
163
164       ::comm::comm config
165
166       ::comm::comm config name
167
168       ::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
174       These configuration variables can be changed (descriptions of them  are
175       elsewhere in this manual page):
176
177       -listen ?0|1?
178
179       -local  ?0|1?
180
181       -port   ?port?
182
183       -silent ?0|1?
184
185       -socketcmd ?commandname?
186
187       -interp ?interpreter?
188
189       -events ?eventlist?
190
191       These configuration variables are read only:
192
193       -chan    chan
194
195       -serial  n
196
197       -socket  sockIn
198
199       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
205   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
217       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
226   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
231       This insecure setup can be changed by the user via the two options -in‐
232       terp, and -events.
233
234       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
246       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
251       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
259   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
265       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
268   CLOSING CONNECTIONS
269       These methods give control over closing connections:
270
271       ::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
277       ::comm::comm abort
278              This invokes shutdown on all open connections in this comm chan‐
279              nel.
280
281       ::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
290
291
292                  "::comm::comm destroy; ::comm::comm new ::comm::comm"
293
294
295       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
300   CALLBACKS
301       This is a mechanism for setting hooks for particular events:
302
303       ::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
310              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
315              Common variables include:
316
317              chan   the name of the comm channel (and command)
318
319              id     the id of the remote in question
320
321              fid    the file id for the socket of the connection
322
323       These are the defined events:
324
325       connecting
326              Variables: chan, id
327
328              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
332
333
334                  % ::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
343
344       connected
345              Variables: chan, fid, id, host, and port.
346
347              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
355       incoming
356              Variables: chan, fid, addr, and remport.
357
358              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
364
365
366                  ::comm::comm hook incoming {
367                      if {[string match 127.0.0.1 $addr]} {
368                          error "I don't talk to myself"
369                      }
370                  }
371
372
373       eval   Variables: chan, id, cmd, and buffer.
374
375              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
382              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
392              Examples:
393
394              [1]    augmenting a command
395
396
397
398                         % ::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
405
406              [2]    short circuiting a command
407
408
409
410                         % ::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
415
416              [3]    Replacing double eval semantics
417
418
419
420                         % ::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
427
428              [4]    Using a slave interpreter
429
430
431
432                         % 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
441
442              [5]    Using a slave interpreter (double eval)
443
444
445
446                         % ::comm::comm hook eval {return [eval foo eval $buffer]}
447
448
449              [6]    Subverting the script to execute
450
451
452
453                         % ::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
465
466       reply  Variables: chan, id, buffer, ret, and return().
467
468              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
473              •      return result
474
475              •      return -code code result
476
477              •      return -code code -errorinfo info -errorcode ecode msg
478
479       For  safety  reasons, this is decomposed.  The return result is in ret,
480       and the return switches are in the return array:
481
482return(-code)
483
484return(-errorinfo)
485
486return(-errorcode)
487
488       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
491       callback
492              Variables: chan, id, buffer, ret, and return().
493
494              Similar to reply, but used for callbacks.
495
496       lost   Variables: chan, id, and reason.
497
498              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
502
503
504                  ::comm::comm hook lost {
505                      global myvar
506                      if {$myvar(id) == $id} {
507                          myfunc
508                          return
509                      }
510                  }
511
512
513   UNSUPPORTED
514       These interfaces may change or go away in subsequence releases.
515
516       ::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
522       ::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
526
527
528                  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
539
540   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
546       The envisioned main use is the specification of  the  tls::socket  com‐
547       mand, see package tls, to secure the communication.
548
549                # Load and initialize tls
550                package require tls
551                tls::init  -cafile /path/to/ca/cert -keyfile ...
552
553                # Create secured comm channel
554                ::comm::comm new SECURE -socketcmd tls::socket -listen 1
555                ...
556
557
558       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
563   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
576       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
591   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
597       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
602       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
611       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
619       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
622       ::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
630              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
642              An example:
643
644
645              # Procedure invoked by remote clients to run database operations.
646              proc select {sql} {
647                  # Signal the async generation of the result
648
649                  set future [::comm::comm return_async]
650
651                  # Generate an async db operation and tell it where to deliver the result.
652
653                  set query [db query -command [list $future return] $sql]
654
655                  # Tell the database system which query to cancel if the connection
656                  # goes away while it is running.
657
658                  $future configure -command [list db cancel $query]
659
660                  # 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
668
669       The API of a future object is:
670
671              $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
677                     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
682              $future configure ?-command ?cmdprefix??
683
684              $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
689   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
696                  package require comm 3
697
698
699       Note that requiring no version (or a  specific  version)  can  also  be
700       done.
701
702       The revision history of comm includes these releases:
703
704       4.6.3  Fixed  ticket  [ced0d60fc9].  Added proper detection of eof on a
705              socket, properly closing it.
706
707       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
711       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
723       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
728       4.5.7  Changed handling of ports already in use to provide a proper er‐
729              ror message.
730
731       4.5.6  Bugfix in the replacement for  vwait,  made  robust  against  of
732              variable names containing spaces.
733
734       4.5.5  Bugfix in the handling of hooks, typo in variable name.
735
736       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
740              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
749       4.5.3  Bugfixes in the wrappers for the builtin update and  vwait  com‐
750              mands.
751
752       4.5.2  Bugfix in the wrapper for the builtin update command.
753
754       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
759       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
766       4.4.1  Bugfix in the execution of hooks.
767
768       4.4    Bugfixes  in  the  handling  of  -interp  for  regular  and hook
769              scripts. Bugfixes in channel cleanup.
770
771       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
774       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
778       4.2    Bugfixes,  and  most important, switched to utf-8 as default en‐
779              coding for full i18n without any problems.
780
781       4.1    Rewrite of internal code to remove old pseudo-object model.  Ad‐
782              dition of send -command asynchronous callback option.
783
784       4.0    Per  request  by  John  LoVerso.  Improved handling of error for
785              async invoked commands.
786
787       3.7    Moved into tcllib and placed in a proper namespace.
788
789       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
793       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
801       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
813
814
815                  comm send id break
816                  catch {comm send id break}
817                  comm send id expr 1 / 0
818
819
820       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
825       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
829       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
835       3.1    All the documented hooks were implemented.  commLostHook was re‐
836              moved.  A bug in comm new was fixed.
837
838       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
848       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
854       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
858       2.1    Unsupported method comm remoteid was added.
859
860       2.0    comm has been rewritten from scratch (but  is  fully  compatible
861              with Comm 1.0, without the requirement to use obTcl).
862

TLS SECURITY CONSIDERATIONS

864       This package uses the TLS package to handle the security for https urls
865       and other socket connections.
866
867       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
873       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
881
882                  package require tls
883                  tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
884
885                  ... your own application code ...
886
887

AUTHOR

889       John LoVerso, John@LoVerso.Southborough.MA.US
890
891       http://www.opengroup.org/~loverso/tcl-tk/#comm
892

LICENSE

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

BUGS

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
905       •      There should be a way to force a channel to quiesce when  chang‐
906              ing the configuration.
907
908       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
911       •      Allow easier use of a slave interp for actual command  execution
912              (especially when operating in "not local" mode).
913
914       •      Add  host  list  (xhost-like) or "magic cookie" (xauth-like) au‐
915              thentication to initial handshake.
916
917       The following are outstanding todo items.
918
919       •      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
923       •      Fix the {id host} form so as not to be dependent upon  canonical
924              hostnames.  This requires fixes to Tcl to resolve hostnames!
925
926       This man page is bigger than the source file.
927

ON USING OLD VERSIONS OF TCL

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
933                  "comm send $other exit"
934
935
936       Always make sure the channel is quiescent before closing/exiting or use
937       at least Tcl7.6 under Windows.
938
939       Tcl7.6 on the Mac contains several bugs.  It is recommended you use  at
940       least Tcl7.6p2.
941
942       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
950       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
955       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

BUGS, IDEAS, FEEDBACK

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
966       When proposing code changes, please provide unified diffs, i.e the out‐
967       put of diff -u.
968
969       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

SEE ALSO

975       send(n)
976

KEYWORDS

978       comm,  communication, ipc, message, remote communication, remote execu‐
979       tion, rpc, secure, send, socket, ssl, tls
980

CATEGORY

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>
988
989
990
991
992tcllib                               4.6.3                             comm(n)
Impressum