6.7  Additional Control and Support

• Initialisation During Attachment
• Disconnection and Control Transfer Support

The remote interface provides additional support for controlling the interaction of the Tcl and ECLⁱPS^e sides, such as explicit transfer of control between ECLⁱPS^e and Tcl, and the disconnection of the Tcl and ECLⁱPS^e 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 ECLⁱPS^e 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 ECLⁱPS^e 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 ECLⁱPS^e 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 ECLⁱPS^e 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 ECLⁱPS^e side has the control (for example, the GUI may have a button that sends an rpc goal to ECLⁱPS^e when pressed. Such a button could be disabled by the call-back when control is transferred to ECLⁱPS^e and reenabled when control is transferred back to Tcl).

Note that there are two types of transfer of control from ECLⁱPS^e to Tcl: 1) when the control is implicitly yielded (e.g. initiating I/O from ECLⁱPS^e 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 ECLⁱPS^e). With implicit yield, the Tcl side is expected to eventually handed back control implicitly to ECLⁱPS^e, and not to explicitly hand control over to ECLⁱPS^e 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 ECLⁱPS^e when pressed, which should only be enabled when ECLⁱPS^e explicitly yielded to Tcl.

On the ECLⁱPS^e 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 ECLⁱPS^e 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 ECLⁱPS^e side has control. Returns 1 if ECLⁱPS^e 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 ECLⁱPS^e. Returns 1 if there is a connection to ECLⁱPS^e (i.e. it is attached), 0 otherwise.

ec_resume

explicitly hand-over control to ECLⁱPS^e. Tcl side must have control when this command is called (i.e. ec_running must be false). This command returns when ECLⁱPS^e 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 ECLⁱPS^e (start), when control is handed back from ECLⁱPS^e (end), when ECLⁱPS^e explicitly yields control (yield), and when the Tcl side is disconnected by the ECLⁱPS^e 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 ECLⁱPS^e 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 ECLⁱPS^e process. This closes all the connections between the two sides. The ECLⁱPS^e 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 ECLⁱPS^e side to also close its connections to this remote connection, as well as raising the disconnect event in ECLⁱPS^e associated with this remote connection. If the disconnect was initiated from the ECLⁱPS^e 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.

ECLⁱPS^e side

remote_yield(+Control)

Explicitly yields control from ECLⁱPS^e to the remote side with the control stream Control. ECLⁱPS^e execution will suspend until control is transferred back to ECLⁱPS^e. This predicate returns when ECLⁱPS^e side resumes control.

remote_disconnect(+Control)

Initiates disconnection from the remote side specified by Control. This will close all connections between ECLⁱPS^e and the remote side, on both sides. It will also cause an event Control to be raised.

Note that if the ECLⁱPS^e process is halted normally, then ECLⁱPS^e will try to disconnect from every remote side it may be connected to.