Additional Control and Support

## 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 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.