6.7 Additional Control and Support
The remote interface provides additional support for controlling the
interaction of the Tcl and ECLiPSe sides, such as explicit transfer of
control between ECLiPSe and Tcl, and the disconnection of the Tcl
and ECLiPSe sides. The interface also provides support for special
user-defined commands to be executed during these events.
6.7.1 Initialisation During Attachment
In an application, after the Tcl side has been attached, typically some
application specific initialisation needs to be performed, such as setting
up various data queues between the two sides, and defining the actions to
take when the two sides are disconnected. On both sides, these
initialisations can be performed immediately after attachment. On the Tcl
side, such
actions can be specified in the optional init_command argument of
ec_remote_init. On the ECLiPSe side, such actions can be specified
in the `InitGoal' (last) argument of remote_connect/3. InitGoal can
be a built-in, or a user-defined goal.
6.7.2 Disconnection and Control Transfer Support
Disconnection should normally be performed when the ECLiPSe application
has finished using the GUI provided by the particular attached remote process.
The disconnection
may be initiated from either side. In addition to cleaning up and closing
all the remote queues connecting the two sides, the disconnection would
trigger the execution of user definable procedures on both sides (through an
event on the ECLiPSe side, and a call-back on the Tcl side), which can
be used to perform extra application specific cleanup and shutdown
routines.
For the transfer of control from Tcl to ECLiPSe and vice versa,
user-definable call-backs are made. This is to enable to define application
specific restrictions on what the GUI is allowed to do when the ECLiPSe
side has the control (for example, the GUI may have a button that sends an
rpc goal to ECLiPSe when pressed. Such a button could be disabled by the
call-back when control is transferred to ECLiPSe and reenabled when
control is transferred back to Tcl).
Note that there are two types of transfer of control from ECLiPSe to
Tcl: 1) when the control is implicitly yielded (e.g. initiating I/O
from ECLiPSe with Tcl, or returning after an rpc call); 2) when the
control is handed over by yielding explicitly (e.g. by calling
remote_yield/1 in ECLiPSe). With implicit yield, the Tcl side is
expected to eventually handed back control implicitly to ECLiPSe, and
not to explicitly hand control over to ECLiPSe before this. Thus two
call-backs are provided when control is yield to Tcl: one is executed
whenever the control is yielded, and the other is only executed when the
control is explicitly yielded. Thus when control is explicitly yielded,
both call-backs are executed. This can be useful for example by defining
the explicit yield call-back to enable a button on the Tcl side that will
explicitly transfer control back to ECLiPSe when pressed, which should
only be enabled when ECLiPSe explicitly yielded to Tcl.
On the ECLiPSe side, an event is raised when the two sides
disconnect. The event's name is the control stream's name. The user can
define a handler for this event to allow user-defined action to take place
on the ECLiPSe side on disconnection. The simplest way to define this
handler is to do it during the connection, via the last argument of remote_connect/3.
Tcl side
-
ec_running
checks if the ECLiPSe side has control. Returns 1 if ECLiPSe
side has control, 0 otherwise. If that is the case,
then the Tcl side cannot issue an ec_rpc goal. Note that ec_running
will return 1 before connection and after disconnection.
- ec_connected
checks if the Tcl side is currently attached to ECLiPSe. Returns
1 if there is a connection to ECLiPSe (i.e. it is attached), 0
otherwise.
- ec_resume
explicitly hand-over control to ECLiPSe. Tcl side must have
control when this command is called (i.e. ec_running must
be false). This command returns when ECLiPSe side yields the
control back to the Tcl side. Meanwhile, the Tcl process is not
suspended as the Tcl event loop is entered while waiting for the
yield.
- ec_running_set_commands ?start? ?end? ?yield? ?disconnect?
set up commands that will be called just before control is handed
over to ECLiPSe (start), when control is handed back from
ECLiPSe (end), when ECLiPSe explicitly yields control
(yield), and when the Tcl side is
disconnected by the ECLiPSe side ( disconnect). The start and end commands are called
both when control change hands explicitly (e.g. via ec_resume), or implicitly (e.g. by making an rpc call or
performing I/O on a synchronous remote queue). An explicit yield
from ECLiPSe will in addition call the yield command, after the start command is executed.
The default for each command is that no command will be called.
- ec_disconnect ?side?
disconnect the Tcl process from the ECLiPSe process. This closes
all the connections between the two sides. The ECLiPSe side will
abort from what it was doing. After disconnection, the
two sides can no longer communicate, and ec_running will be
set. The optional argument side specifies which side, tcl
or eclipse,
initiated the disconnection. For user's Tcl program, this will
normally be the default tcl. If the disconnect is initiated from
the Tcl side, this command will cause the ECLiPSe side to also
close its connections to this remote connection, as well as
raising the disconnect event in ECLiPSe associated with this
remote connection. If the disconnect was initiated from
the ECLiPSe side, then ec_disconnect will be called
automatically with side set to eclipse, and the disconnect
command set up by ec_running_set_commands will be executed.
ECLiPSe side
-
remote_yield(+Control)
Explicitly yields control from ECLiPSe to the remote side with
the control stream Control. ECLiPSe execution will suspend
until control is transferred back to ECLiPSe. This predicate
returns when ECLiPSe side resumes control.
- remote_disconnect(+Control)
Initiates disconnection from the remote side specified by Control. This will close all connections between ECLiPSe and
the remote side, on both sides. It will also cause an event Control to be raised.
Note that if the ECLiPSe process is halted normally, then ECLiPSe
will try to disconnect from every remote side it may be connected to.