1% BEGIN LICENSE BLOCK 2% Version: CMPL 1.1 3% 4% The contents of this file are subject to the Cisco-style Mozilla Public 5% License Version 1.1 (the "License"); you may not use this file except 6% in compliance with the License. You may obtain a copy of the License 7% at www.eclipse-clp.org/license. 8% 9% Software distributed under the License is distributed on an "AS IS" 10% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See 11% the License for the specific language governing rights and limitations 12% under the License. 13% 14% The Original Code is The ECLiPSe Constraint Logic Programming System. 15% The Initial Developer of the Original Code is Cisco Systems, Inc. 16% Portions created by the Initial Developer are 17% Copyright (C) 2006 Cisco Systems, Inc. All Rights Reserved. 18% 19% Contributor(s): Kish Shen, IC-Parc 20% 21% END LICENSE BLOCK 22% 23%% $Id: embremote.tex,v 1.2 2008/09/17 18:13:00 kish_shen Exp $ 24% 25% Author: Kish Shen, IC-Parc 26% 27 28%---------------------------------------------------------------------- 29\chapter{Remote Tcl Interface} 30\label{chapremote} 31%HEVEA\cutdef[1]{section} 32%---------------------------------------------------------------------- 33 34This chapter describes the remote Tcl interface, which allows a separate 35external Tcl program to interact with {\eclipse} in much the same fashion as 36the embedding Tcl interface (see chapter~\ref{chaptcl}). Like the embedding 37interface, Tcl and {\eclipse} code communicates by sending and receiving 38streams of bytes via I/O queues (the {\bf ec_rpc} mechanism is 39implemented on top of these queues). 40The interface can thus be 41used in similar fashion to the embedding interface, e.g.\ for the 42development of graphical user interfaces to an ECLiPSe application, with the 43difference that the {\eclipse} program is a separate program and not 44embedded into the Tcl program. 45 46The main features of the interface are: 47\begin{itemize} 48\item The connection between the Tcl and {\eclipse} processes are established 49via sockets using TCP network protocol. Thus the Tcl process can be run on 50a different machine and platform from the {\eclipse} process. 51\item The Tcl process can be attached to any running {\eclipse} process, 52including an {\eclipse} embedded into another host language. 53\item More than one Tcl (or other remote) process can be attached to a 54single {\eclipse} via the remote interface. 55\item For the programmer, the embedding and remote interfaces are largely 56similar, and once the connection is established in the remote interface, 57the same code on the {\eclipse} and Tcl sides can be used for both interfaces. 58\end{itemize} 59 60The remote interface thus offers more flexibility than an embedding 61interface in how the Tcl code can be connected to an {\eclipse} 62program. However, as the Tcl and {\eclipse} processes are not as tightly 63coupled as in an embedded interface, the speed of communications between 64the Tcl and {\eclipse} processes is likely to be slower. 65 66\section{Basic Concepts of the Interface} 67 68The interface is used by starting separate {\eclipse} and Tcl processes, and 69then {\bf attaching} the Tcl process to the {\eclipse} process. Once 70attached, the Tcl and {\eclipse} processes can communicate much as in the 71embedded interface: {\eclipse} goals can be sent from the Tcl side to the 72{\eclipse} side via the remote predicate call ({\bf ec_rpc}) mechanism, 73and further I/O queues can be established between the {\eclipse} and Tcl 74processes to allow streams of bytes to sent from one side to the other. 75 76The attached Tcl 77process can also be detached from the {\eclipse} process. This 78disconnection will terminate and clean-up the links between the two 79processes. Thus, typically, if the programmer wants to allow a particular 80application to be usable through both the Tcl remote and embedding 81interfaces, the only code that needs to be specific to one or the other 82interface is the code associated with starting and termination of the 83application (the attach and detach operations in the case of the remote 84interface). 85 86The interaction between the Tcl and {\eclipse} is mediated by a version of 87thread-like control flow of the embedded interface. The 88interface distinguishes two `sides': the Tcl side, which is the Tcl 89process, and the {\eclipse} side, which is generally the {\eclipse} 90process\footnote{The {\eclipse} side may be more complicated than a simple {\eclipse}, as it can be 91an embedded {\eclipse}, or the {\eclipse} process and other attached remote 92processes.}. At any given time, 93either the {\eclipse} side or the Tcl side has `control'. When the Tcl side 94has control, execution of the {\eclipse} process is suspended. When the 95{\eclipse} side has control, the Tcl side cannot initiate the execution of 96ec_rpc goals. The interface can implicitly transfer control from one side 97to the other (e.g.\ when processing synchronous I/O), or it can be 98explicitly transferred. 99 100An {\eclipse} process can have several attached remote processes. Each 101remote process is identified by a {\bf control} name, which is the 102{\eclipse} name for a special control connection between the two sides. 103 104\section{Loading the Interface} 105{\sloppy 106Before using the interface, 107the Tcl program must first load a Tcl-package called {\bf 108remote_eclipse}, which can be loaded as follows: 109\index{remote_eclipse} 110 111\begin{quote}\begin{verbatim} 112lappend auto_path "/location/of/my/eclipse/lib_tcl" 113package require remote_eclipse 114\end{verbatim}\end{quote} 115% It might also be necessary to provide information about where the 116% DLLs or shared library files can be found. The details are 117% platform-specific: 118% 119% \begin{itemize} 120% \item On UNIX systems, the {\tt LD\_LIBRARY\_PATH} 121% environment variable must include the path: 122% \begin{quote} 123% {\tt <eclipse\_dir>/lib/<architecture\_os>/} 124% \end{quote} 125% where {\tt <architecture\_os>} is for example {\tt i386\_linux} or 126% {\tt sparc\_sunos5}. 127% \item On Windows NT, the {\tt PATH} environment variable must contain the path: 128% \begin{quote} 129% \begin{verbatim} 130% <eclipse_dir>\lib\i386_nt\ 131% \end{verbatim} 132% \end{quote} 133% \end{itemize} 134 135An {\eclipse} program, onto which the Tcl program will attach, also needs to 136be started. 137} 138 139\section{Attaching and Initialising the Interface} 140 141To use the interface, the Tcl program needs to be 142attached to the {\eclipse} program. The attach request is initiated on the 143{\eclipse} side, by calling the predicate 144\bipref{remote_connect/3}{../bips/kernel/externals/remote_connect-3.html} \footnote{Instead of {\bf remote_connect/3}, the more 145flexible \bipref{remote_connect_setup/3}{../bips/kernel/externals/remote_connect_setup-3.html} and \bipref{remote_connect_accept/6}{../bips/kernel/externals/remote_connect_accept-6.html} 146pair of predicates can be used. See the reference manual entries for these predicates for more 147details.} from {\eclipse}. The Tcl program is then attached to the 148{\eclipse} program by executing the procedure {\bf 149ec_remote_init}\index{ec_remote_init (Tcl command)} from Tcl. If no error 150occurs, then the connection is established and the interface is set up. 151 152 153In more detail, the {\eclipse} predicate remote_connect/3 establishes a 154socket listening for the connection from the Tcl side. It prints out, on 155the stream {\tt log_output}, the 156hostname and the port number that the Tcl side should connect to: 157 158\begin{verbatim} 159[eclipse 1]: remote_connect(Host/Port, Control, _InitGoal). 160Socket created at address chicken.icparc.ic.ac.uk/25909 161\end{verbatim} 162 163On the Tcl side, ec_remote_init is called with the hostname and port number 164given by remote_connect/3: 165 166\begin{verbatim} 167ec_remote_init chicken.icparc.ic.ac.uk 25909 168\end{verbatim} 169 170\begin{description} 171\item[\index{ec_remote_init (Tcl remote interface)}{\bf ec_remote_init} {\it host port ?init_command? ?pass? ?format?}]\ \\ 172 Initialise the remote Tcl interface on the Tcl side. A 173 corresponding {\bf remote_connect/3} must have been started on the 174 {\eclipse} side, which specifies the hostname ({\it host}) and port 175 number ({\it port}) to connect to. The optional {\it 176 init_command\/} is an is a Tcl command that will be invoked at the 177 end of the attachment, before control is handed over to the 178 {\eclipse} side (see section~\ref{remote-control} for more 179 details). {\it pass\/} and {\it format\/} are optional arguments for a simple 180 security check: they specify an {\eclipse} term that will be 181 matched against a corresponding term (using \txtbipref{==/2}{(==)/2}{../bips/kernel/termcomp/EE-2.html}) on the 182 {\eclipse} side before the connection is allow to proceed ({\it pass\/} 183 will be sent to the {\eclipse} side in EXDR format\footnote{See 184 section~\ref{secexdrtcl} for more on EXDR format}; the default is 185 an empty string, which is what \bipref{remote_connect_setup/3}{../bips/kernel/externals/remote_connect_setup-3.html} 186 expects). 187 188\end{description} 189 190If successful, some initial links are established between the two sides, 191such as the control connection and the connection to allow rpc goals to be 192sent from the Tcl to the {\eclipse} side. 193After the attachment, optional user-defined 194initialisations are performed on both sides (via the InitGoal argument on 195the {\eclipse} side, and the init_command on the Tcl side), and the two 196sides can then interact. Initially, the control is given to the Tcl side, 197and {\it remote_connect/3} returns only when control is handed over to the 198{\eclipse} side. 199 200As part of the attachment process, the {\eclipse} name of the control 201connection is passed to the Tcl side. This can be accessed by the user 202using the command: 203 204\begin{description} 205\item[\index{ec_control_name (Tcl remote interface)}{\bf ec_control_name}]\ \\ returns the {\eclipse} name of the control 206connection. An error is raised if this procedure is called before 207an attachment to {\eclipse} is made. 208\end{description} 209 210Unimplemented functionality error will be raised if the Tcl or 211{\eclipse} side are incompatible with each other. This can happen if 212one side is outdated, e.g.\ if the remote Tcl interface used and the {\eclipse} 213being connected to are not from the same version of {\eclipse}. In this 214case, it is best to update both sides to the latest version of {\eclipse}. 215 216\subsection{A Note on Security} 217 218Once a Tcl side is attached to an {\eclipse}, the Tcl side can execute 219{\eclipse} goals on the {\eclipse} side via the {\bf ec_rpc} mechanism. This 220may be a security concern as 221this gives the Tcl side as much access to the resources on the {\eclipse} 222side as the {\eclipse} process itself, even though the Tcl side can 223potentially be anywhere reachable from the {\eclipse} side via TCP. 224However, the connection must be initiated from the {\eclipse} side, and the 225attachment process must follow a protocol in order for a successful 226attachment. Nevertheless, 227if a third party somehow knew which Address to connect to, and follows the 228protocol, it can `steal' the connection to {\eclipse}. No 229authentication is performed by the simple \verb'remote_connect_setup/3', 230but \bipref{remote_connect_accept/6}{../bips/kernel/externals/remote_connect_accept-6.html} does allow a simple authentication 231where it can require the Tcl side to send an {\eclipse} term that matches 232the one specified in calling the predicate. This is done before the Tcl 233side is given the ability to run rpc goals on the {\eclipse} side. 234 235It is also possible to limit the remote connection to the same machine as the 236{\eclipse} process by specifying `localhost' as the host name in the 237Host/Port address of \verb'remote_connect/3'. The Tcl side must also 238use `localhost' for the Host name in its client connection. 239 240Each peer queue is created by creating a new server socket on the 241{\eclipse} side and then accepting a client connection from the Tcl 242side. The accept command is told where the client connection is from, and 243the client host is checked against the client's host from the attachment, 244to ensure that the same host has been connected. If not, the {\eclipse} 245side will reject the particular connection. At this point, the security has 246probably been compromised, and the two side should disconnect. 247 248Note also that by default, none of the information sent through the queues 249between the remote side and the {\eclipse} side is encrypted. If the 250programmer requires these communication channels to be secure, then such 251encryptions need to be provided by the programmer. 252 253\section{Type Conversion Between Tcl and {\eclipse}} 254 255The EXDR ({\eclipse} External Data Representation, see 256chapter~\ref{chapexdr}) representation is fully supported by the 257interface. The same type conversions commands as in the embedding Tcl 258interface, described in section~\ref{secexdrtcl} 259(ec_write_exdr, ec_read_exdr, ec_tcl2exdr, ec_exdr2tcl), are available. 260 261\section{Executing an {\eclipse} Goal From Tcl} 262 263An {\eclipse} predicate can be invoked from the Tcl side using the 264remote {\eclipse} predicate call (ec_rpc) facility. This should be the 265main method of interacting and communicating with {\eclipse} in the remote 266interface. Information can be sent to {\eclipse} via bindings for (input) 267arguments when the call is made; and 268results returned from {\eclipse} via the bindings made to (output) 269arguments: 270 271\begin{description} 272\item[\index{ec_rpc (Tcl remote interface)}{\bf ec_rpc} {\it goal ?format?}]\ \\ 273 Remote {\eclipse} predicate call. 274 It calls goal in the default module. The goal should be simple 275 in the sense that it can only succeed, fail or throw. 276 Any choice-points the goal leaves will be discarded. 277 278 Calls to {\bf ec_rpc} can be nested 279 and can be used from within Tcl queue event handlers. However, an 280 {\bf ec_rpc} cannot be issued while {\eclipse} side has control. 281 282 If no format argument is given, the goal is assumed to be in 283 {\eclipse} syntax. If a {\it format} argument is provided, 284 the {\eclipse} goal is constructed from {\it goal} and {\it format}, 285 according to the conversion rules explained in section \ref{secexdrtcl}. 286 287 On success, {\bf ec_rpc} returns the (possibly more instantiated) 288 goal as a Tcl data structure (in EXDR format), otherwise "fail" or 289 "throw" respectively. 290\end{description} 291 292\section{Communication via Queues} 293 294Queues should be used to set up long-term I/O links between {\eclipse} and 295Tcl. An example would be the main output from an application that is to be 296displayed by a Tcl window. Streams of bytes can be sent along the queue 297from one side to the other: on one side, data is written to the queue; and 298when the queue is flushed, the data is sent to the other side, which can 299now read the data. The data can either be sent as normal strings (where 300each byte represents a character) using the normal I/O calls, or they can 301be in EXDR format, in which case both sides need to read and write using 302EXDR. 303 304On the Tcl side, the queue is seen as a Tcl I/O 305channel. On the {\eclipse} side, a queue is 306seen as an {\eclipse} I/O stream, which has a unique (numeric) ID, the 307stream number, and has a user supplied symbolic 308name. These all refer to the same queue. Queues are created using the symbolic names, and the Tcl side 309maintains tables of the correspondence between Tcl channel names, symbolic 310names and stream numbers. The built-in Tcl I/O commands accepts the Tcl 311channel name for operating on the queue, and for 312compatibility with the embedding interface, many of the Tcl remote 313interface commands refer to the queue using the stream number. The 314interface provides commands to inter-convert the various names so that the 315right name can be used for a particular command. 316 317 318There are two types of queues: 319 320\begin{description} 321\item[synchronous] These queues are unidirectional, 322i.e.\ either for sending data from {\eclipse} to Tcl (from-{\eclipse}), or 323from Tcl to {\eclipse} (to-{\eclipse}). 324These streams are synchronous because the interface ensures that the 325sending and receiving of data across the queue are synchronised. This is 326achieved by transferring control between 327{\eclipse} and Tcl in a coroutine-like manner to ensure that data that is 328sent from one side is processed on the other. 329 330 331{\sloppy 332These queues are designed to be compatible with the queues 333created via ec_queue_create of the embedded interface 334(see section~\ref{ecqueueconnect}). Their actual implementations are 335different, in that the queues in the embedded case are memory queues and 336the synchronous queue use socket connections. The interface tries to 337minimise the difference by buffering where 338possible at either ends of the socket connection. However, there is an overhead for doing 339this, and not all differences can be hidden. This is discussed in more detail in section~\ref{remotediff}. 340} 341 342 343\item[asynchronous] These are bi-directional -- 344data can be sent both ways. Sending or receiving data on these queues does 345not necessarily transfer control between {\eclipse} and 346Tcl. In particular, it is not possible to request data from the other side 347if the queue is empty: such an operation would simply block. 348This is because such queues map 349directly to the socket connections with no buffering, and there is no concept of a socket 350being empty. Generally, it is up to the programmer to co-ordinate the 351transfer and processing of the data. 352 353They have no direct 354equivalent in the embedding Tcl interface, but some uses of the embedding 355Tcl interface queues, such as writing data from one side without a 356corresponding reader on the other side, are better approximated by the 357asynchronous queues than the synchronous queues. They can also be more 358efficient in that there is no buffering of the data is performed by the 359interface. 360 361\end{description} 362 363\subsection{Queue Data Handlers} 364\label{remotehandles} 365 366The processing of data on queues (synchronous and to some extent 367asynchronous) can be performed via {\it handlers}. A handler is a piece of 368code (a procedure in Tcl, a goal in {\eclipse}) whose execution is 369data-driven: it is invoked to deal 370with the transfer of data on a queue on their respective sides. 371 372In {\eclipse}, the handler goal is invoked using the events mechanism. That 373 is, an event is raised, and the event handler goal associated with the event 374 (see \bipref{set_event_handler/2}{../bips/kernel/event/set_event_handler-2.html}) is then executed when {\eclipse} has control. 375 376A handler can be called under two situations: 377 378\begin{description} 379\item[Data consumer] To consume data that has been sent over from the other 380side. Here, the other side has sent data over the queue, invoking the handler. 381The handler is expected to read the data off the queue and process it. 382An example of a data consumer handler is a Tcl handler which is invoked 383when the {\eclipse} side sends data that is intended to be displayed on a Tcl 384window. The handler would be 385invoked to read the data off the queue and display it on the window. 386 387\item[Data provider] To provide data that has been requested by the other side. In this 388 case, the handler is expected to generate the data and write the data onto 389 the queue, and send it to the other side. For example, on the Tcl side, a 390 Tcl handler might be invoked to ask for inputs from the user via the GUI. 391 Note that these data providers can only exist for the synchronous 392 queues. 393 394\end{description} 395 396For each queue and for a particular direction of data flow, a 397handler can be defined on either the Tcl or the {\eclipse} side, but not 398both. The handler either consumes or provides data as described above. The 399reason that handlers cannot be defined on both sides 400is that this avoids possible infinite loop of alternately 401triggering the data provider and the data consumer. 402 403\subsection{Synchronous Queues} 404 405 406These queues can be created on the Tcl side. This is done with 407the {\bf ec_queue_create} command from within Tcl code: 408 409\begin{description} 410\item[\index{ec_queue_create (Tcl remote interface)}ec_queue_create {\it 411eclipse_stream_name mode ?command? ?event?}]\ \\ 412 Creates a synchronous queue between Tcl and {\eclipse} sides. On 413 the Tcl side, a Tcl channel is created. On the {\eclipse} side, the 414 queue would be given the symbolic name {\it eclipse_stream_name}. 415 The {\it mode} argument indicates the direction of the queue, and 416 can either be fromec or toec\footnote{For compatibility with previous 417 versions of the embedded Tcl interface, the mode can also be 418 specified as r (equivalent to fromec) or w (equivalent to 419 toec). These can be somewhat confusing as read/write status depends 420 on from which side the queue is viewed (a read queue in {\eclipse} is a 421 write queue in Tcl).}. 422 The procedure returns a channel identifier for use in commands 423 like {\bf puts}, {\bf read}, {\bf ec_read_exdr}, 424 {\bf ec_write_exdr} or {\bf close}. The optional arguments {\it 425 command\/} and {\it event\/} specifies the data handler for the 426 queue: {\it command\/} is the name 427 of the Tcl 428 procedure for handling the data, with its user defined arguments. 429 {\it event} is the name of the event that will be 430 raised on the {\eclipse} side (see the section~\ref{remotehandles} 431 for more details). As a handler can only be defined for one side, 432 either {\it event\/} or {\it command\/} should be undefined 433 (\verb'{}'). 434\item[\index{ec_queue_close (Tcl remote interface)}ec_queue_close {\it 435eclipse_stream_name}]\ \\ 436 Closes the (synchronous or asynchronous) queue with the {\eclipse} name of {\it 437 ec_stream_name}. The queue is closed on both the Tcl and {\eclipse} 438 sides, and bookkeeping information for the queue is removed. 439 440\end{description} 441 442It is strongly recommended that the queues should be used for long-term I/O 443connections between the two sides, and so the queues should not be created 444and closed on a short-term basis. For quick interchange of data, it is 445recommended that the user use the {\bf ec_rpc} mechanism. 446 447\subsubsection{Handlers for a Synchronous From-{\eclipse} Queue} 448 449\paragraph{Tcl Handler for From-{\eclipse} Queue} 450 451For a from-{\eclipse} queue, the Tcl handler {\it command\/} would be a 452data consumer. This handler is initiated when 453{\eclipse} side initially has control and flushes 454the queue (by calling \bipref{flush/1}{../bips/kernel/iostream/flush-1.html}). With a Tcl handler defined, 455control is transferred to the Tcl 456side, where {\it command\/} is invoked to consume the data. When the 457handler finishes, control is returned to the {\eclipse} side. The general 458sequence of actions are: 459 460\vspace{0.5cm} 461\begin{center} 462\begin{tabular}{l|l} 463{\eclipse} side & Tcl side\\ 464\hline 465\parbox{6.5cm}{Writes to the from-{\eclipse} queue} &\\ 466 467\parbox{6.5cm}{Flush the from-{\eclipse} queue} &\\ 468 469 & \parbox{6.5cm}{Handler invoked to handle data on the from-{\eclipse} queue}\\ 470\parbox{6.5cm}{{\eclipse} returns from flush, and continue executing the following code}&\\ 471\end{tabular} 472\end{center} 473\vspace{0.5cm} 474 475The Tcl handler is specified by {\it command\/} in {\bf 476ec_queue_create}. {\it command\/} includes the name of the Tcl procedure to 477invoke, and any user defined arguments. When the handler is invoked, two 478additional arguments are appended: 479the {\eclipse} stream number for the queue, and the number 480of bytes that has been sent on the queue. This command should read the data 481off the queue and process it. The following predefined Tcl 482data consumer handlers are provided: 483 484\begin{description} 485\item[\index{ec_stream_to_window_sync (Tcl remote interface)}ec_stream_to_window_sync {\it tag text_widget stream_nr length}]\ \\ 486 Read {\it length\/} bytes from the specified queue and insert the data 487 at the end of the existing {\it text_widget}, using {\it tag} as the tag 488 for the text. If this is invoked as a handler for a from-{\eclipse} 489 queue, {\it length\/} and {\it stream_nr\/} would be supplied when 490 the handler is invoked. 491 492 493\item[\index{ec_stream_output_popup (Tcl remote interface)}ec_stream_output_popup {\it label_text stream_nr length}]\ \\ 494 Pops up a window displaying the {\it label_text}, 495 a text field displaying the contents of the specified queue stream, 496 and an ok-button for closing. The data is read as normal 497 strings. This is the default Tcl fromec handler that will be called 498 if {\bf ec_create_queue} did not define one. 499 500\end{description} 501 502\paragraph{An example from-{\eclipse} queue with Tcl handler} 503 504To create the queue on the Tcl side with a Tcl handler: 505 506\begin{verbatim} 507Tcl code : ec_queue_create myqueue fromec {ec_stream_to_window_sync red textwin} {} 508\end{verbatim} 509 510Note that the last \verb'{}' specifies that there is no {\eclipse} 511handler. This is the actual default for this argument, so it could be 512missed out. After creating the queue, it can be used on the {\eclipse} 513side. The programmer can write to the queue, and to send the data to the 514Tcl side, the queue should be flushed: 515 516\begin{verbatim} 517ECLiPSe code : 518 ... 519 write(myqueue, hello), 520 flush(myqueue), 521 ... 522\end{verbatim} 523 524When the queue is flushed as shown above, then control is handed over to 525Tcl, and the Tcl handler, in this case {\bf ec_stream_to_window_sync}, 526would be invoked. This reads the data on the queue (hello, and anything 527else that has been written since the last flush), and puts it into the text 528widget textwin, with the tag red. The procedure is also called with the 529{\eclipse} stream number for the queue and the number of bytes sent as extra 530arguments. The textwin widget and the tag red must 531be defined already in the Tcl program (presumably `red' means printing the 532text in red colour); if no tag is desired, \verb'{}' can be used. 533 534The procedure {\bf ec_stream_to_window_sync} is predefined in the 535interface, but here is a slightly 536simplified version of it: 537 538\begin{verbatim} 539proc ec_stream_to_window_sync {Tag Window Stream Length} { 540 541 set channel [ec_streamnum_to_channel $Stream] 542 set data [read $channel $Length] 543 544 $Window insert end $data $Tag 545 $Window see end 546} 547\end{verbatim} 548 549\paragraph{{\eclipse} Handler for From-{\eclipse} Queue} 550 551Currently, the Tcl remote interface does not support {\eclipse} handlers 552(which will be a data provider) for from-{\eclipse} queues. Thus, the {\it 553event\/} argument for {\bf ec_queue_create} is currently a dummy argument 554that is ignored. The available alternative is to use {\bf ec_rpc} to obtain 555the required information: instead of reading from a from-\eclipse queue, an 556ec_rpc should be called with argument(s) left to be filled in by the 557{\eclipse} side with the required data. 558 559\subsubsection{Handlers for a Synchronous To-{\eclipse} Queue} 560 561\paragraph{Tcl Handler for a To-{\eclipse} Queue} 562 563\label{toeclipse-tclhandler} 564 565For a to-{\eclipse} queue, the Tcl handler {\it command\/} defined in {\bf 566ec_queue_create} would be a data 567producer. This handler is initiated when {\eclipse} side has control, and 568reads from the to-{\eclipse} queue, which is initially empty. With a Tcl 569handler defined, control is transferred to the Tcl side, where {\it 570command\/} is invoked to provide the data. The handler should write the 571data to the queue, and call the Tcl remote interface command {\bf ec_flush} 572to send the data to {\eclipse} side. When the handler finishes, 573control is returned to the {\eclipse} side, and the read operation is 574performed to read the now available data. The general sequence of actions are: 575 576\vspace{0.5cm} 577\begin{center} 578\begin{tabular}{l|l} 579{\eclipse} side & Tcl side\\ 580\hline 581\parbox{6.5cm}{Reads an empty to-{\eclipse} queue} &\\ 582 & \parbox{6.5cm}{Handler invoked to supply data to the 583 to-{\eclipse} queue. The data is written to the queue and flushed 584 with {\bf ec_flush}}\\ 585\parbox{6.5cm}{{\eclipse} returns from the initial read operation, reading 586 the data supplied by the Tcl handler, and continue execution the following code}&\\ 587\end{tabular} 588\end{center} 589\vspace{0.5cm} 590 591The Tcl remote interface command {\bf ec_flush}, instead of the standard 592Tcl {\bf flush} command, should be used to flush a 593queue so that the data would be transferred and processed on the {\eclipse} 594side. {\bf ec_flush} should be used both inside the Tcl data provider 595handler, and also to invoke an {\eclipse} data consumer handler (see the 596next section). 597 598\begin{description} 599\item[\index{ec_flush (Tcl remote interface)}{\bf ec_flush} {\it 600eclipse_streamnum ?nbytes?}]\ \\ 601 If the Tcl side has control, flushes the (synchronous or asynchronous) queue 602 with the {\eclipse} stream number {\it eclipse_streamnum} and hands over 603 control briefly to {\eclipse} to read the data. Control is 604 then returned to Tcl. {\it nbyte\/} is an optional argument that specifies the 605 number of bytes being sent. If this argument is missing, the data sent 606 must be a single EXDR term in the case of the synchronous queue. There 607 is no restriction for the asynchronous queues, but it is the 608 programmer's responsibility that the read operation does not block. 609\end{description} 610 611Normally, data is written to the queue using standard Tcl output commands, 612and the amount of data written is not known. However, the programmer may 613have kept track of the number of bytes written inside the handler, and thus 614know how many bytes will be sent. In this case, {\bf ec_flush} can be 615called with the number of bytes supplied as a parameter. It is the 616programmer's responsibility to ensure that this information is accurate. 617Without nbytes, the output is restricted to EXDR terms for synchronous 618queues. The reason for this is because the data is sent through a socket 619connection, and without knowing the amount of data, it is not possible in 620general to know when the data ends, unless the data sent has implicit 621boundaries, like an EXDR term. 622 623For the use of {\bf ec_flush} inside a Tcl data provider handler, the 624sequence of events that appears to the user is that the {\bf ec_flush} 625flushes the data, and the Tcl side then continues executing Tcl code 626until the handler's execution is finished. Control is then returned to 627{\eclipse}, where the original read operation can now read the available 628data. The actual sequence of event is slightly more complex for synchronous 629queues: when {\bf 630ec_flush} is invoked, control is actually transferred to {\eclipse}, and 631the data flushed is then read into a buffer by {\eclipse}, which then 632returns control to Tcl to continue the execution of the handler. When the 633handler finally finishes, control returns to {\eclipse}, and the original 634read operation reads the data from the buffer and continues. This extra 635complexity should be transparent to the programmer except when the 636intermediate {\eclipse} read to buffer does not complete (e.g.\ because 637{\it nbytes\/} is greater than the actual amount of data sent). 638 639The Tcl handler is specified by {\it command\/} in {\bf 640ec_queue_create}. {\it command\/} includes the name of the Tcl procedure to 641invoke, and any user defined arguments. When the handler is invoked, an 642additional argument is appended: 643the {\eclipse} stream number for the queue. This command should get the 644data required, output it onto the queue, and call {\bf ec_flush} to flush 645the data to {\eclipse} side. If the command does not flush data to 646{\eclipse}, {\eclipse} will print a warning and return control to Tcl side. 647 648The following predefined Tcl data producer 649handler is provided: 650 651\begin{description} 652\item[\index{ec_stream_input_popup (Tcl remote interface)}{\bf ec_stream_input_popup} {\it label_text stream_nr}]\ \\ 653 Pops up a window displaying the label_text, an input field 654 and an ok-button. The text typed into the input field will 655 be written into the specified queue stream {\it stream_nr}, which 656 is the {\eclipse} stream number for the queue. If this command is 657 invoked as a handler for a to-{\eclipse} queue, {\it stream_nr} 658 will be automatically appended by the interface. There should be no 659 unflushed data already on the queue when this command is invoked. 660\end{description} 661 662\paragraph{An example to-{\eclipse} queue with Tcl handler} 663 664To create the queue on the Tcl side with a Tcl-handler: 665 666\begin{verbatim} 667Tcl code : 668ec_queue_create myqueue toec \ 669 {ec_stream_input_popup "Input for myqueue:"} {} 670\end{verbatim} 671 672This associates the pre-defined Tcl data producer handler {\bf 673ec_input_popup} with myqueue. The last \verb'{}' specifies that there is no 674{\eclipse} handler and can be omitted as that is the default. This queue 675can now be used on the {\eclipse} side in a demand driven way, i.e.\ 676{\eclipse} side can read from the queue: 677 678\begin{verbatim} 679ECLiPSe code : 680 681 ... 682 read(myqueue, Data), 683 ... 684\end{verbatim} 685 686When the {\eclipse} side reads from myqueue, and the queue contains no data 687on the {\eclipse} side, then 688control will be handed over to Tcl, and {\bf ec_input_popup} 689invoked. This pops up a Tcl window, with the label ``Input for myqueue:'' 690with a text entry widget, asking the user to supply the requested data. The 691data is then sent back to the {\eclipse} side. 692 693Here is a slightly simplified version (there are no buttons) 694of {\bf ec_stream_input_popup}: 695 696\begin{verbatim} 697set ec_stream_input_string {} 698 699proc ec_stream_input_popup {Msg Stream} { 700 global ec_stream_input_string 701 702 toplevel .ec_stream_input_box 703 label .ec_stream_input_box.prompt -width 40 -text $Msg 704 entry .ec_stream_input_box.input -bg white -width 40 \ 705 -textvariable ec_stream_input_string 706 bind .ec_stream_input_box.input <Return> {destroy .ec_stream_input_box} 707 708 ;# pack the popup window 709 pack .ec_stream_input_box.prompt -side top -fill x 710 pack .ec_stream_input_box.input -side top -fill x 711 712 tkwait window .ec_stream_input_box 713 puts -nonewline [ec_streamnum_to_channel $Stream] $ec_stream_input_string 714 ;# flush the output to ECLiPSe with the length of the input 715 ec_flush $Stream [string length $ec_stream_input_string] 716} 717 718\end{verbatim} 719 720Data is flushed to the {\eclipse} side using {\bf ec_flush}. The {\bf puts} 721needs the Tcl channel name of the queue to write to, and this is provided 722via the Tcl remote interface command {\bf ec_streamnum_to_channel} (see 723section~\ref{translate-remote-qnames}). {\bf ec_flush} is called with two 724arguments in this case, both the queue number ({\it Stream}), and the 725length of the data that is sent. Note that this makes the assumption that 726no other unflushed data has been written to the queue. 727 728\paragraph{{\eclipse} Handler for a To-{\eclipse} Queue} 729 730For a to-{\eclipse} queue, the {\eclipse} handler would be a data 731consumer. This handler is initiated when Tcl initially has control, and 732flushes data on a queue using {\bf ec_flush}. Control is transferred to 733{\eclipse}, and if the {\eclipse} handler is defined, this is invoked to 734consume the data. When the handler returns, control is returned to Tcl, 735which continues executing the code after the flush. The general sequence of 736actions are: 737 738\vspace{0.5cm} 739\begin{center} 740\begin{tabular}{l|l} 741{\eclipse} side & Tcl side\\ 742\hline 743 & \parbox{6.5cm}{Outputs data onto the to-{\eclipse} queue}\\ 744 & \parbox{6.5cm}{Calls {\bf ec_flush} to send data to {\eclipse} side}\\ 745\parbox{6.5cm}{The {\eclipse} handler associated with the queue is called to consume and 746process the data} &\\ 747 & \parbox{6.5cm}{Execution continues after the {\bf ec_flush}}\\ 748\end{tabular} 749\end{center} 750\vspace{0.5cm} 751 752The {\eclipse} handler is specified by the {\it event\/} argument of {\bf 753ec_queue_create}. This specifies an event that will be raised on the 754{\eclipse} side when data is written to a previously empty queue. The 755{\eclipse} side does not see this data, and the event not raised, until the 756data is flushed by {\bf ec_flush} and copied by {\eclipse} to its 757buffer and, if the buffer was initially empty, the event would then be raised. 758 759The programmer should define the event handler associated with {\it 760event}. 761 762\paragraph{An example to-{\eclipse} queue with {\eclipse} handler} 763 764To create the queue on the Tcl side with an {\eclipse}-handler: 765 766\begin{verbatim} 767Tcl code: 768 ec_queue_create myqueue toec {} remoteflush_myqueue 769\end{verbatim} 770 771Note that the \verb'{}' is needed to specify that there is no Tcl handler. 772It defines \verb'remoteflush_myqueue' as the event that will be raised when 773the queue is flushed by {\bf ec_flush} on the Tcl side. 774 775The event handler needs to be defined on the {\eclipse} side: 776 777\begin{verbatim} 778ECLiPSe code: 779 780:- set_event_handler(remoteflush_myqueue, read_myqueue/0). 781 782... 783read_myqueue :- 784 read_exdr(myqueue, Data), 785 process(Data). 786 787\end{verbatim} 788 789This read handler assumes that the data is written using EXDR format. So on 790the Tcl side, the data should be written using EXDR format: 791 792\begin{verbatim} 793Tcl code: 794 795 ... 796 ec_write_exdr [ec_streamname_to_channel myqueue] $data 797 ec_flush [ec_streamname_to_streamnum myqueue] 798 ... 799\end{verbatim} 800 801 802\subsection{Asynchronous Queues} 803 804Asynchronous queues are created on the Tcl side using the Tcl command {\bf 805ec_async_queue_create}: 806 807\begin{description} 808\item[\index{ec_async_queue_create (Tcl remote interface)}ec_aysnc_queue_create {\it eclipse_stream_name ?mode? 809?fromec_command? ?toec_event?}]\ \\ 810 Creates a socket stream between {\eclipse} and Tcl with the name 811 {\it eclipse_stream_name\/} on the {\eclipse} side. The created 812 stream is bidirectional, and can be written to or read from at both 813 ends. The {\it mode\/} argument is for compatibility with the {\it 814 ec_aysnc_queue_create\/} command of the embedded interface only, 815 and has no effect on the nature of the queue. The procedure 816 returns a channel identifier for use in commands like {\bf puts}, 817 {\bf read}, {\bf ec_read_exdr}, {\bf ec_write_exdr} or {\bf 818 close}. Unlike the synchronous queues, only data consumer handlers 819 can be defined: if a {\it fromec_command} argument is provided, 820 this command is set as the Tcl data consumer handler to be called 821 when data arrives on the Tcl end of the socket. If {\it toec_event\/} 822 is given, it specifies the event that will be raised on the 823 {\eclipse} side when data is flushed by {\it ec_flush} on the Tcl 824 side. 825\item[\index{ec_queue_close (Tcl remote interface)}ec_queue_close {\it 826eclipse_stream_name}]\ \\ 827 Closes the (synchronous or asynchronous) queue with the {\eclipse} 828 name of {\it ec_stream_name}. The queue is closed on both the Tcl and {\eclipse} 829 sides, and bookkeeping information for the queue is removed. 830 831 832 833\end{description} 834 835Asynchronous queues are bi-directional queues which allows data transfer 836between {\eclipse} and Tcl sides without transfer of control. 837In the case where a Tcl data consumer 838handler is defined in {\it fromec_command}, which is invoked on the Tcl 839side when the queue is flushed on the {\eclipse} side, the {\eclipse} side 840will carry on execution while the handler is invoked on the Tcl side. 841 842These queues are designed to allow for more efficient transfer of data 843between {\eclipse} and Tcl than the synchronous queues. 844 845For data transfer from 846{\eclipse} to Tcl, the intended use is that a Tcl data consumer handler 847 would be invoked as the data becomes available on 848the Tcl side, after being flushed from the {\eclipse} side. 849Note that control is not handed over to Tcl side in this case: 850the Tcl handler is 851invoked and executed on the Tcl side while {\eclipse} side still has control, with the 852restriction that the Tcl handler is unable to issue {\bf ec_rpc} 853goals because {\eclipse} side still retains control. Another difference 854with the synchronous from-{\eclipse} queue is that the handler would read 855from the queue in non-blocking mode, i.e.\ it will read whatever data is 856available on the queue at the Tcl side and never wait for more data. 857If more data become 858available, the handler would be invoked again. The following Tcl handler is 859pre-defined for the asynchronous queue for handling from-{\eclipse} data: 860 861\begin{description} 862\item[\index{ec_stream_to_window (Tcl remote interface)}ec_stream_to_window {\it tag text_widget stream_nr length}]\ \\ 863 Inserts all the current contents of the specified queue 864 at the end of the existing {\it text_widget}, using {\it tag} as 865 the tag for the text. 866 867\end{description} 868 869 870For data transfer from Tcl to {\eclipse}, 871the queue can be used either asynchronously or synchronously. 872If the 873queue is used asynchronously, then the standard Tcl command {\bf flush} 874should be used to flush the queue. There would not be any transfer of 875control, and so there would not be an 876immediate corresponding read on the {\eclipse} side. In fact, no handler 877would be invoked automatically on the {\eclipse} side, even when control is 878transferred. 879Output and flush 880operations do not block on the Tcl side, as the Tcl side of the queue is 881put into non-blocking mode, so that the data is buffered and the operations 882carried out when they will not block. It is the programmer's responsibility 883to write and call the code to read the data from the queue on the {\eclipse} side when 884the {\eclipse} side is given control. 885 886This asynchronous use to send data to {\eclipse} should be useful when 887the queue is used as an auxiliary data 888channel, where the main data is sent either via {\bf ec_rpc} or another 889queue. The desired effect is that data can be sent on the auxiliary channel 890without triggering processing on the {\eclipse} side until it is told to do 891so on the main data channel, which would be handled synchronously. 892 893To use the queue synchronously for 894to-{\eclipse} data, {\bf ec_flush} should be used to flush the queue on the 895Tcl side. 896With {\bf ec_flush}, control will be handed over to the 897{\eclipse} side to process the data: the goal associated with the event {\it toec_event} is 898executed, and this goal should read the data from the queue. 899Unlike the synchronous to-{\eclipse} 900queues, the data is not buffered, and the handler goal is called every time 901{\bf ec_flush} is invoked, rather than only when the queue is empty. This 902should normally not make any difference, as the handler should empty all 903the contents of a queue each time it is invoked. 904 905The goal is called with two optional arguments: the first argument is the 906event name, the second argument is the `culprit' of the form 907\verb'rem_flushio(Queue,Len)', indicating that this event is caused by a 908remote flush, where Queue is the {\eclipse} stream number, 909and Len is the number of bytes sent (this is supplied by {\bf ec_flush}, if 910{\bf ec_flush} does not supply a length, then Len is the atom 911\verb'unknown'. 912 913\subsubsection{Examples for asynchronous queue} 914 915\paragraph{Using the queue asynchronously: to-{\eclipse}} 916 917An example of using an asynchronous queue asynchronously to send data to 918{\eclipse} is in the tracer for Tk{\eclipse} development tools. Here the trace line is 919printed on a synchronous from-{\eclipse} queue, and handled by a Tcl data 920consumer handler which prints the trace line and waits for the user to type 921in a debugger command. This debugger command is sent to the {\eclipse}-side 922using an asynchronous queue, which is read by the {\eclipse} side when it 923returns. Here is a much simplified version of the code: 924 925\begin{verbatim} 926Tcl code: 927 ... 928 ec_queue_create debug_traceline fromec handle_trace_line 929 ec_async_queue_create debug_input toec ;# no handlers 930 ... 931\end{verbatim} 932 933During the initialisation of the development tools, the Tcl code creates 934the from-{\eclipse} queue where the trace-line information is sent 935(\verb'debug_traceline'), and the asynchronous queue (used only in a 936to-{\eclipse} direction) for sending the debugger commands to {\eclipse} 937(creep, leap, skip etc.). Note that as this queue is used asynchronously, 938there are no handlers associated with it. 939 940On the {\eclipse} side, when a goal with a spy-point is executed, this 941raises an event that calls the predicate \verb'trace_line_handler/2' which 942should output the trace-line, and wait for a debug command, process the 943command, and carry on: 944 945\begin{verbatim} 946trace_line_handler(_, Current) :- 947 % Current contains information on the current execution state 948 % from this a trace line Traceline (a string) can be created 949 make_current_traceline(Current, Traceline), 950 % send the traceline to Tcl side 951 write_exdr(debug_traceline, Traceline), 952 flush(debug_traceline), 953 % flush will return when the Tcl handler has finished 954 read_exdr(debug_input, Cmd), 955 % read the command from debug_input and process it 956 interpret_command(Cmd, Current). 957\end{verbatim} 958 959The trace-line handler is called with the second argument set to a 960structure that contain information on the current execution state 961(\verb'Current'), from this, a trace-line (the debug port name, depth, goal 962being traced etc.) can be constructed: \verb'Traceline' is the string that 963should be printed, e.g. 964 965\begin{verbatim} 966 (1) 1 CALL append([1, 2, 3], [], L) 967\end{verbatim} 968This is sent as an EXDR term to the Tcl side using the synchronous 969queue \verb'debug_traceline'. When \verb'flush/1' is 970called, control is handed over to the Tcl to handle the data, and the 971Tcl data consumer handler {\bf handle_trace_line} is invoked: 972 973\begin{verbatim} 974proc handle_trace_line {stream length} { 975 global tkecl 976 977 $ec_tracer.trace.text insert end \ 978 [ec_read_exdr [ec_streamnum_to_channel $stream]] 979 configure_tracer_buttons active 980 981 ;# wait for a tracer command button to be pressed... 982 tkwait variable tkecl(tracercommand) 983 configure_tracer_buttons disabled 984 ec_write_exdr [ec_streamname_to_channel debug_input] \ 985 $tkecl(tracercommand) 986 flush [ec_streamname_to_channel debug_input] 987} 988\end{verbatim} 989 990As this is invoked as a handler, the {\eclipse} stream number ({\it 991stream}) and number of bytes sent ({\it length}) are appended as 992arguments. Note that as the trace-line is written as an EXDR term, the {\it 993length\/} information is actually not needed. What the handler does is 994simply read the trace-line as an EXDR term, and placing the resulting 995string onto the tracer text window \verb'$ec_tracer_trace.text'. Next, {\bf 996configure_tracer_buttons active} is called. This code is not shown, but 997what it does is to enable the buttons for the debugger commands so that the 998user can press them. There are buttons for the debugger commands such as 999`leap', `creep' etc. When one of this button is pressed, the global 1000variable \verb'tkecl(tracercommand)' is set to the corresponding command, 1001and the handler continues its execution beyond the {\bf tkwait}. The 1002buttons are disabled, the command sent to {\eclipse} side on the 1003\verb'debug_input' queue using {\bf flush}. This is the asynchronous 1004sending of data on the asynchronous queue: 1005control is {\it not\/} handed 1006over to {\eclipse} to process this command. Instead, the execution on the 1007Tcl side carries on (and happens to finish immediately after the {\bf 1008flush}. Control is then returned to the {\eclipse} side as the Tcl handler 1009has finished, and the {\eclipse} side continues execution after the 1010\verb'flush(debug_traceline)' goal. Next, \verb'debug_input' is read for 1011the tracer command, and this command is acted on. 1012 1013\paragraph{Using the queue synchronously: to-{\eclipse}} 1014 1015 1016If the Tcl remote interface command {\bf 1017ec_stream_input_popup} (see section~\ref{toeclipse-tclhandler}) is used to 1018send data to the {\eclipse}-side (in section~\ref{toeclipse-tclhandler}, 1019the command was initiated by a read operation on the {\eclipse} side; here 1020the command is invoked directly when Tcl side has control), then the 1021following is a possible {\eclipse} handler: 1022 1023\begin{verbatim} 1024Tcl code: 1025 1026;# create the asynchronous queue, with 1027;# from-ECLiPSe Tcl consumer handler: data_to_window 1028;# to-ECLiPSe ECLiPSe handler event: flush_myqueue 1029ec_async_queue_create myqueue {data_to_window textwin} flush_myqueue 1030 1031... 1032;# get input for the queue and send to ECLiPSe side 1033ec_stream_input_popup "Data:" [ec_channel_to_streamnum myqueue] 1034... 1035 1036ECLiPSe code: 1037 1038:- set_event_handler(flush_myqueue, read_remote_data/2). 1039 1040% Len is known when ec_stream_input_popup is used to send data 1041read_remote_data(_Event, rem_flushio(Queue,Len)) :- 1042 read_string(Queue, "", Len, Data), 1043 process(Data). 1044 1045\end{verbatim} 1046 1047The {\eclipse} code defines \verb'read_remote_data/2' as the handler for 1048to-{\eclipse} data sent with {\bf ec_flush} on the Tcl side. This handler 1049is called when control is handed over to {\eclipse} side to read the 1050data. Both the two optional arguments are used in this handler. The second 1051argument supplies the {\eclipse} stream number for the queue and the length 1052of data written. As the data is 1053sent by explicitly calling {\bf ec_stream_input_popup}, the length of the 1054data sent is known, so \verb'read_string/4' can be used to read the exact amount of 1055data. In the asynchronous queue, it is generally the programmer's 1056responsibility to ensure that the read will not block. 1057 1058\paragraph{Using the queue asynchronously: from-{\eclipse}} 1059 1060The example \verb'ec_async_queue_create' also defines a Tcl data consumer 1061handler to handle data sent on the from-{\eclipse} direction, with a user 1062defined argument of the text window that the data will be sent to. Here is 1063a simple procedure which reads the data on the queue and places it on the 1064text window specified: 1065 1066\begin{verbatim} 1067Tcl code: 1068 1069proc data_to_window {Window Stream} { 1070 set channel [ec_streamnum_to_channel $Stream] 1071 1072 $Window insert end [read $channel] 1073} 1074 1075\end{verbatim} 1076 1077The {\it Stream} argument is appended by the interface when the handler is 1078invoked, and is the {\eclipse} stream number of the queue. The procedure 1079simply reads the data from the corresponding Tcl channel and display the 1080data on {\it Window}, the text window specified by the programmer. 1081 1082 1083\subsection{Reusable Queue Names} 1084 1085{\eclipse} stream names are global in scope, so using fixed queues names 1086like `myqueue' might cause name conflicts with other modules, if the 1087programmer intend the remote Tcl code to be usable with other {\eclipse} code. 1088One way to avoid name clashes is to dynamically composing queue names using 1089the name of the control connection: 1090 1091 1092\begin{verbatim} 1093Tcl code: 1094 append queue_name [ec_control_name] myqueue 1095 ec_queue_create $queue_name fromec {ec_stream_output_popup red textwin} 1096\end{verbatim} 1097 1098The user specified name `myqueue' is appended to the control name of the 1099remote connection to give a unique queue name. On the {\eclipse} side, 1100the code will also need to use the dynamic name: 1101 1102\begin{verbatim} 1103 :- local variable(remote_control). 1104 1105 ... 1106 % code fragment to remember the control name 1107 remote_connect(Addr, Control, _), 1108 setval(remote_control, Control), 1109 ... 1110 1111 ... 1112 % code fragment to use the queue 1113 getval(remote_control, Control), 1114 concat_atom([Control, myqueue], QName), 1115 ... 1116 write(QName, hello), flush(QName), 1117 ... 1118 1119\end{verbatim} 1120 1121 1122\subsection{Translating the Queue Names} 1123\label{translate-remote-qnames} 1124 1125The remote queues connecting {\eclipse} and Tcl are given different names 1126on the two sides. The remote Tcl interface 1127keeps track of the {\eclipse} names for the queues on the Tcl side. On the 1128{\eclipse} side, the queue has a stream number, as well as possibly several 1129symbolic aliases. The interface only keeps track of one symbolic name -- 1130the one that is supplied in {\it ec_queue_connect\/} and {\it 1131ec_async_queue_create}. If the {\eclipse} stream number was supplied in 1132these commands, then the stream number is also considered the symbolic name 1133for the queue as well. The Tcl interface provides several commands to convert the names 1134from one form to another: 1135 1136\begin{description} 1137\item[\index{ec_streamname_to_channel (Tcl remote interface)}ec_streamname_to_channel {\it eclipse_name}]\ \\ 1138 Returns the Tcl channel name for the remote queue with the 1139 symbolic name {\it eclipse_name}. 1140\item[\index{ec_streamnum_to_channel (Tcl remote 1141 interface)}ec_streamnum_to_channel {\it eclipse_stream_number}]\ \\ 1142 Returns the Tcl channel name for the remote queue with the 1143 {\eclipse} stream number {\it eclipse_stream_number}. 1144\item[\index{ec_channel_to_streamnum (Tcl remote interface)} 1145 ec_channel_to_streamnum {\it channel}]\ \\ 1146 Returns the {\eclipse} stream number for the remote queue with the 1147 Tcl channel name {\it channel}. 1148\item[\index{ec_streamname_to_streamnum (Tcl remote interface)}ec_streamname_to_streamnum {\it eclipse_name}]\ \\ 1149 Returns the {\eclipse} stream number for the remote queue with the 1150 symbolic name {\it eclipse_name}. 1151\item[\index{ec_stream_nr (Tcl remote interface)}ec_stream_nr {\it eclipse_name}]\ \\ 1152 This is an alias for {\bf ec_streamname_to_streamnum} for 1153 compatibility with embedded interface. 1154\end{description} 1155 1156 1157\section{Additional Control and Support} 1158\label{remote-control} 1159 1160The remote interface provides additional support for controlling the 1161interaction of the Tcl and {\eclipse} sides, such as explicit transfer of 1162control between {\eclipse} and Tcl, and the disconnection of the Tcl 1163and {\eclipse} sides. The interface also provides support for special 1164user-defined commands to be executed during these events. 1165 1166\subsection{Initialisation During Attachment} 1167 1168 1169In an application, after the Tcl side has been attached, typically some 1170application specific initialisation needs to be performed, such as setting 1171up various data queues between the two sides, and defining the actions to 1172take when the two sides are disconnected. On both sides, these 1173initialisations can be performed immediately after attachment. On the Tcl 1174side, such 1175actions can be specified in the optional {\it init_command} argument of 1176{\it ec_remote_init}. On the {\eclipse} side, such actions can be specified 1177in the `InitGoal' (last) argument of {\it remote_connect/3}. InitGoal can 1178be a built-in, or a user-defined goal. 1179 1180\subsection{Disconnection and Control Transfer Support} 1181 1182Disconnection should normally be performed when the {\eclipse} application 1183has finished using the GUI provided by the particular attached remote process. 1184The disconnection 1185may be initiated from either side. In addition to cleaning up and closing 1186all the remote queues connecting the two sides, the disconnection would 1187trigger the execution of user definable procedures on both sides (through an 1188event on the {\eclipse} side, and a call-back on the Tcl side), which can 1189be used to perform extra application specific cleanup and shutdown 1190routines. 1191 1192For the transfer of control from Tcl to {\eclipse} and vice versa, 1193user-definable call-backs are made. This is to enable to define application 1194specific restrictions on what the GUI is allowed to do when the {\eclipse} 1195side has the control (for example, the GUI may have a button that sends an 1196rpc goal to {\eclipse} when pressed. Such a button could be disabled by the 1197call-back when control is transferred to {\eclipse} and reenabled when 1198control is transferred back to Tcl). 1199 1200Note that there are two types of transfer of control from {\eclipse} to 1201Tcl: 1) when the control is implicitly yielded (e.g.\ initiating I/O 1202from {\eclipse} with Tcl, or returning after an rpc call); 2) when the 1203control is handed over by yielding explicitly (e.g.\ by calling 1204\bipref{remote_yield/1}{../bips/kernel/externals/remote_yield-1.html} in {\eclipse}). With implicit yield, the Tcl side is 1205expected to eventually handed back control implicitly to {\eclipse}, and 1206not to explicitly hand control over to {\eclipse} before this. Thus two 1207call-backs are provided when control is yield to Tcl: one is executed 1208whenever the control is yielded, and the other is only executed when the 1209control is explicitly yielded. Thus when control is explicitly yielded, 1210both call-backs are executed. This can be useful for example by defining 1211the explicit yield call-back to enable a button on the Tcl side that will 1212explicitly transfer control back to {\eclipse} when pressed, which should 1213only be enabled when {\eclipse} explicitly yielded to Tcl. 1214 1215On the {\eclipse} side, an event is raised when the two sides 1216disconnect. The event's name is the control stream's name. The user can 1217define a handler for this event to allow user-defined action to take place 1218on the {\eclipse} side on disconnection. The simplest way to define this 1219handler is to do it during the connection, via the last argument of \bipref{remote_connect/3}{../bips/kernel/externals/remote_connect-3.html}. 1220 1221\subsubsection{Tcl side} 1222 1223\begin{description} 1224\item[\index{ec_running (Tcl remote interface)}ec_running]\ \\ 1225 checks if the {\eclipse} side has control. Returns 1 if {\eclipse} 1226 side has control, 0 otherwise. If that is the case, 1227 then the Tcl side cannot issue an ec_rpc goal. Note that ec_running 1228 will return 1 before connection and after disconnection. 1229\item[\index{ec_connected (Tcl remote interface)}ec_connected]\ \\ 1230 checks if the Tcl side is currently attached to {\eclipse}. Returns 1231 1 if there is a connection to {\eclipse} (i.e.\ it is attached), 0 1232 otherwise. 1233\item[\index{ec_resume (Tcl remote interface)}ec_resume]\ \\ 1234 explicitly hand-over control to {\eclipse}. Tcl side must have 1235 control when this command is called (i.e. {\it ec_running\/} must 1236 be false). This command returns when {\eclipse} side yields the 1237 control back to the Tcl side. Meanwhile, the Tcl process is not 1238 suspended as the Tcl event loop is entered while waiting for the 1239 yield. 1240\item[\index{ec_running_set_commands (Tcl remote interface)}ec_running_set_commands {\it ?start? ?end? ?yield? ?disconnect?}]\ \\ 1241 set up commands that will be called just before control is handed 1242 over to {\eclipse} ({\it start}), when control is handed back from 1243 {\eclipse} ({\it end}), when {\eclipse} explicitly yields control 1244 ({\it yield}), and when the Tcl side is 1245 disconnected by the {\eclipse} side ({\it 1246 disconnect}). The {\it start} and {\it end} commands are called 1247 both when control change hands explicitly (e.g.\ via {\it 1248 ec_resume}), or implicitly (e.g.\ by making an rpc call or 1249 performing I/O on a synchronous remote queue). An explicit yield 1250 from {\eclipse} will in addition call the {\it yield\/} command, {\it 1251 after\/} the {\it start\/} command is executed. 1252 1253 The default for each command is that no command will be called. 1254 1255\item[\index{ec_disconnect (Tcl remote interface)}ec_disconnect {\it ?side?}]\ \\ 1256 disconnect the Tcl process from the {\eclipse} process. This closes 1257 all the connections between the two sides. The {\eclipse} side will 1258 abort from what it was doing. After disconnection, the 1259 two sides can no longer communicate, and {\it ec_running\/} will be 1260 set. The optional argument {\it side\/} specifies which side, tcl 1261 or eclipse, 1262 initiated the disconnection. For user's Tcl program, this will 1263 normally be the default tcl. If the disconnect is initiated from 1264 the Tcl side, this command will cause the {\eclipse} side to also 1265 close its connections to this remote connection, as well as 1266 raising the disconnect event in {\eclipse} associated with this 1267 remote connection. If the disconnect was initiated from 1268 the {\eclipse} side, then {\it ec_disconnect\/} will be called 1269 automatically with {\it side\/} set to eclipse, and the disconnect 1270 command set up by {\it ec_running_set_commands\/} will be executed. 1271\end{description} 1272 1273\subsubsection{{\eclipse} side} 1274 1275\begin{description} 1276\item[\index{remote_yield/1}remote_yield(+Control)]\ \\ 1277 Explicitly yields control from {\eclipse} to the remote side with 1278 the control stream {\it Control}. {\eclipse} execution will suspend 1279 until control is transferred back to {\eclipse}. This predicate 1280 returns when {\eclipse} side resumes control. 1281 1282\item[\index{remote_disconnect/1}remote_disconnect(+Control)]\ \\ 1283 Initiates disconnection from the remote side specified by {\it 1284 Control}. This will close all connections between {\eclipse} and 1285 the remote side, on both sides. It will also cause an event {\it 1286 Control} to be raised. 1287\end{description} 1288 1289Note that if the {\eclipse} process is halted normally, then {\eclipse} 1290will try to disconnect from every remote side it may be connected to. 1291 1292\section{Example} 1293 1294 1295\begin{figure}[htb] 1296\begin{verbatim} 1297% Tcl side will create the from-ECLiPSe queue gui_output, which will also 1298% automatically flush at the end of every line (and so transfer the data 1299% to the Tcl side) 1300 1301 1302disconnect_handler :- % just terminate ECLiPSe execution 1303 writeln("Terminating...."), 1304 halt. 1305 1306 1307:- remote_connect(localhost/5000, control, 1308 set_event_handler(control, disconnect_handler/0)), 1309 % for simplicity, the host and port are fixed. 1310 % Name for control connection is also fixed. 1311 % when remote_connect returns, the gui_output queue will be 1312 % connected to Tcl side already. 1313 % eclipse side initialisation follows is just to set up the 1314 % handler for disconnection.... 1315 writeln(gui_output, "Connected..."). 1316 1317% this is for yielding control to Tcl. No need to specify Control explicitly 1318tclyield :- 1319 remote_yield(control). 1320\end{verbatim} 1321\caption{Example use of interface: {\eclipse} code} 1322\label{remote-eclipse} 1323\end{figure} 1324 1325 1326\begin{figure}[htb] 1327{\small 1328\begin{verbatim} 1329# ECLIPSEDIR has to be set to where your ECLiPSe is at 1330lappend auto_path [file join $ECLIPSEDIR) lib_tcl] 1331 1332package require remote_eclipse 1333 1334proc terminate {} { 1335 destroy . 1336} 1337 1338# disable the terminate button when control is transferred to ECLiPSe 1339proc disable_button {} { 1340 .b configure -state disabled 1341} 1342 1343# enable the terminate button when control is transferred back to Tcl 1344proc enable_button {} { 1345 .b configure -state normal 1346} 1347 1348# the initialisation procedure, called when the remote side is attached. 1349# this creates the gui_output from-ECLiPSe queue, and then uses an 1350# ec_rpc to cause the queue to flush at every newline 1351proc initialise {} { 1352 ec_queue_create gui_output fromec 1353 ec_rpc "set_stream_property(gui_output, flush, end_of_line)" 1354} 1355 1356# this button initiates disconnection and terminates the Tcl program 1357pack [button .b -text "Terminate" -command "ec_disconnect; terminate"] 1358# only start and end commands given; the others default to no commands 1359ec_running_set_commands disable_button enable_button 1360 1361# disable button initially as ECLiPSe side has initial control 1362disable_button 1363 1364# the attachment to ECLiPSe includes the initialisation ec_init, which 1365# creates the gui_output queue. The connection is at the fixed port address 1366ec_remote_init localhost 5000 initialise 1367# Tcl side initially has control, hand it over to ECLiPSe... 1368ec_resume resume 1369\end{verbatim}} 1370\caption{Example use of interface: Tcl code} 1371\label{remote-tcl} 1372\end{figure} 1373 1374Figures~\ref{remote-eclipse} and \ref{remote-tcl} shows a simple example of 1375the use of the interface. To try this program, the user should start an 1376{\eclipse}, compile the {\eclipse} program. This will suspend on the 1377\verb'remote_connect/3', waiting for the Tcl program to attach. The Tcl 1378program should then be started on the same machine, and the attachment will 1379be connected using the fixed host and port address. During the 1380initialisation when attaching, 1381a from-{\eclipse} queue is created, which is set 1382to flush at every newline. This is done by an {\bf ec_rpc} goal after the 1383queue is created. As no Tcl data consumer handler is specified, the default 1384Tcl data consumer handler {\bf ec_stream_output_popup} handles and display the data on the Tcl side on a 1385pop-up window. The Tcl side 1386GUI has just one button which allows the application to terminate. This 1387button is disabled when {\eclipse} side has control, and this is done by 1388setting up the appropriate call-backs to disable and enable the button in 1389{\it ec_running_set_commands\/} on the Tcl side. 1390 1391On disconnection, which can be initiated either by pressing the button on 1392the Tcl side, or by quitting from {\eclipse}, the handlers for 1393disconnection ensures that both the {\eclipse} and Tcl program terminates. 1394 1395\section{Differences From the Tcl Embedding Interface} 1396\label{remotediff} 1397 1398The remote Tcl interface is designed to be largely compatible with the 1399embedded Tcl interface, so that a user GUI can be written that allows 1400either interfaces to be used, while sharing most of the code in both 1401{\eclipse} and Tcl. An example of this is the Tkeclipse development tools. 1402 1403Some remote specific code would need to be written. This includes code to 1404handle the connection and disconnection of the Tcl and {\eclipse} 1405sides: there is no equivalent to ec_cleanup in the embedded Tcl interface, 1406as the termination of the {\eclipse} side should be handled in {\eclipse}. In 1407addition, the user may need to provide code to restrict the interaction 1408within the Tcl/Tk GUI when control is transferred to {\eclipse}. Aside from 1409this, the rest of the code should be reusable, if the user exercises some 1410care. 1411 1412The supported compatible methods of communicating between Tcl and 1413{\eclipse} in the two interfaces is via the {\bf ec_rpc} calls and the use 1414of the I/O queues. The {\bf ec_rpc} mechanism should behave the same in 1415both interfaces. For the queues, there are some differences because the 1416queues are in-memory queues in the embedded interface, but are socket 1417channels in the remote interface. This leads to the following differences: 1418 1419\begin{itemize} 1420 1421\item Data will not appear on the other side until the queue is 1422 flushed on the side that is generating the output. To make code 1423 compatible, output queues should be always flushed. 1424 1425\item In general, reading data via a blocking socket requires the 1426 size of the data to be explicitly specified, except when I/O is done 1427 via the EXDR primitives, where size is implicitly specified. Only 1428 EXDR format is supported when data is sent from Tcl to {\eclipse}. 1429 That is, a write handler for a Tcl write channel must write the data 1430 in EXDR format. For output from the {\eclipse} side, the Tcl read 1431 handler would be supplied with the length of the output when it is 1432 invoked, and this information must be used if the Tcl read is not 1433 done via an EXDR primitive. However, in general it is strongly 1434 suggested that only EXDR formatted data should be sent via the queues 1435 in both direction. 1436 1437\item An I/O operation on the stream may block if there is no 1438 handler to consume/produce the data on the other side. If a handler 1439 is specified via the {\it command} argument, then a corresponding 1440 handler in the Tcl side will be invoked at the correct place when the 1441 {\eclipse} side produces output or request input. 1442 1443\item The channel identifier is not of the form {\tt 1444 ec_queueX}. To make code portable, the name of the channel should be 1445 obtained from the {\eclipse} stream symbolic name or number via the 1446 commands {\bf ec_streamname_to_channel} or {\bf 1447 ec_streamnum_to_channel}. 1448 1449\item Asynchronous queues are bi-directional. In the embedding interface, 1450 there are no asynchronous queues, and {\bf ec_async_queue_create} is 1451 aliased to {\bf ec_queue_create}, and a uni-directional queue is 1452 created. Thus for compatibility, these queues should only be used 1453 in one direction. 1454\end{itemize} 1455 1456In summary, to write code that will work for both the remote and embedded 1457interfaces, the data should be sent using EXDR format, flush always 1458performed, and a handler ({\it command\/} argument) provided. The Tcl 1459channel identifier should not be constructed explicitly. 1460 1461However, there may be cases where the two interfaces need to be 1462distinguished. For example, if the Tcl side is to perform some operations 1463on the file system for the {\eclipse} side (e.g.\ selecting a file via a 1464GUI), then with the remote interface, the two sides might not have access 1465to the same file systems, and being able to distinguish whether the 1466interface is remote or embedded allows the user to provide code to handle 1467this. 1468 1469To obtain information on which interface is being used, use the command: 1470 1471\begin{description} 1472\item[\index{ec_interface_type (Tcl remote interface)}ec_interface_type]\ \\ 1473 returns remote for the remote interface, and embedded for the 1474 embedding interface. 1475\end{description} 1476 1477%HEVEA\cutend 1478 1479 1480 1481