documents/embedding/embremoteproto.tex

33 The {\eclipse} remote interface protocol is used to build a remote
36 separate {\eclipse} process via the remote interface. The Tcl remote
38 interface. This chapter describes the protocol, so that remote interfaces
45 peers\/} is used to unify the remote and embedding interfaces.
47 Another feature of the remote interface is that on the {\eclipse} side,
50 interface (e.g.\ for a GUI) and change the remote code without needing to
53 Briefly, a socket connection is established between the remote program and
56 communication to be platform independent, and the {\eclipse} and remote
63 The remote interface is established by {\bf attaching} the remote and
68 \item[Control] This connection is used to control the remote
70 to the remote protocol to co-ordinate the two processes.
71 \item[Rpc] This is used to send {\bf ec_rpc} goals from the remote process
75 More than one remote attachment can be established in an {\eclipse}
76 process. Each attachment is independent, and is a remote peer,
78 connection. Each remote attachment has two sides: the {\eclipse} side, and
79 the remote side.
81 At any one time, either the {\eclipse} or the remote side has {\it
89 The {\bf ec_rpc} mechanism is designed to be the main way for the remote
90 side to interact with the {\eclipse} side. The remote side can send an
92 can only be done while the remote side has control, and when the goal is
95 to the remote side when {\eclipse} completes the execution of the goal.
111 without transferring control. In fact, if the remote language is
143 checking that the remote protocols on the two sides are compatible;
146 (remote language, {\eclipse} name for the peer).
150 The remote protocol version is stored in the flag {\tt
156 behaves correctly. The version information is sent from the remote side
159 is using. In order to cope with remote connections which may not be using
160 the remote protocol, the {\eclipse} side waits only for a fixed period of
161 time for the remote side to send the version information before timing out.
169 The detailed sequence of events for the attachment for the remote side
176 from the remote side. The user can specify the amount of time to wait
182 \item Remote side: sends the remote protocol version information on the
188 the remote side; otherwise it sends the {\eclipse} remote protocol version
189 to the remote side and disconnects from the remote side (raising
191 most 100 seconds after the control connection is established for the remote side's version: after
200 when the remote connection was initiated -- for \bipref{remote_connect/3}{../bips/kernel/externals/remote_connect-3.html}, the
208 particular remote attachment -- the peer name for the peer. This name is needed when calling ec_rpc goals
211 remote process on the control connection. This should be in EXDR string
221 \item Remote side: read the control connection name again on the remote side, on the
225 \item Remote side: the remote side now has control. Any user-defined initialisations on the remote
226 side can now be performed, to make the remote side ready for the
227 interaction. The remote side has the control initially. Note that
231 connection for the remote side to give control back to the {\eclipse} side.
234 At the end of this, the remote side should be ready for normal interaction
238 the remote side before exiting. Thus when the predicate succeeds, the
239 remote side has been attached and properly initialised, with {\eclipse}
242 The protocol does not specify how the remote side should be informed of the
246 addition, the remote process can be started from within {\eclipse} using
249 In accepting client socket connections from the remote side, the {\eclipse}
250 side is informed of the host of the remote side. This should either be the
260 The following is a simple example of making a remote attachment on the
261 remote side. In this case, the remote side is also an {\eclipse} program.
262 A remote attachment by a program written in another programming language
266 % Example code for making a remote attachment on the remote side
270 % remote_attach/6 makes a remote attachment to a host ECLiPSe program.
276 %    -Control: the remote side (local) name of the control connection
277 %    -Ec_rpc:  the remote side name of the ec_rpc connection
284      % we are the remote side, so must have our own version info.
291          writeln("Incompatible versions of remote protocol. Failing...."),
328      % make the remote attachment. For this simple example, there is no
346 side. After attachment, it disconnects the remote attachment as soon as
350 To try out the example, start an {\eclipse} session and initiate a remote
378 The remote side is suspended, awaiting the {\eclipse} side to return
379 control. To return control to the remote side, the {\eclipse} side should
390 In this simple example, when control is returned to remote side, it
392 side is aborted (as disconnect was initiated from the remote side), as per
416 The programmer for the remote side needs to provide the remote side of the
427 \caption{{\eclipse} implementation of remote synchronous peer queue}
432 stream to the remote side.
440 direction of the data is from {\eclipse} to the remote side (i.e.\
442 if the direction is from the remote side to {\eclipse} (i.e.\ {\eclipse}
445 correctly to the remote side without blocking.
460 The socket stream must be connected to the remote side before it could be
463 remote side, this depends on the facilities available in the language used
464 for the remote side.
471 I/O operations on these queues do not need to be controlled by the remote
472 protocol, but their creation and closing is controlled by the remote
473 protocol, so that the remote interface can keep track of these queues.
479 data (e.g.\ from {\eclipse} side to the remote side without handing over
484 These are the messages that are exchanged between the {\eclipse} and remote
485 sides when the remote side is attached. The messages are sent on the
500 there are messages for terminating the remote attachment. Note that
504 The implementer for the remote interface should provide the methods for a
505 programmer to initiate the interactions from the remote side. These
514 the remote side on the right. Messages are shown as vertical arrows between
533 \subsection{Messages from {\eclipse} side to remote side}
537 \item[yield] this yields control to the remote side.  The message is used either to
538 implicitly return control to the remote side at the end of an
539 interaction initiated from the remote side, or it
540 is used to explicitly hand over control to the remote side.
642 The interaction-initiating messages from the remote side will be described
645 \item[ec_flushio(Queue, Length)] this message is sent when output on a remote
671 that is being sent on the queue. Control is yielded to the remote
674 this message on the remote side, the remote side should read Length bytes from
675 Queue. After processing the data, the remote side should return
679 from a remote synchronous queue, and the data is not available in the
732 and control is yielded to remote side so that it can provide
734 the queue on the remote side. This handler should obtain the data, and send
735 the data to the {\eclipse} side. The data will arrive from the remote side via a
736 {\bf rem_flushio} message, which initiates a remote flushio interaction, nested
738 associated with the remote peer queue Queue, and is automatically copied by
740 the remote side, completing the flushio interaction. The remote side then
744 The remote flushio interaction is described in more detail in its own
745 section. The main difference between a remote flushio initiated on the
746 remote side and one initiated by an {\eclipse} waitio described here is
753 while waiting for the data to be sent from the remote side. If a {\bf
758 back to the remote side. Other messages are handled as normal, recursively
760 for unexpected aborts from the remote side, although it could also be used to
761 perform ec_rpc calls before the remote side sends the data.
763 \item[socket_client(Port, Name, Type, Dir)] this requests the remote side
764 to form a client socket connection for the remote peer queue Name. The
794 passed to the remote side via the {\bf socket_client} message. The remote side
801 on the remote side). When the remote side connection is established, it
810 from the remote side if the name does not match. Status is either
811 success or fail, depending on if the remote side successfully created the
812 remote side of the queue or not.
815 for the peer queue by accepting the socket connection. Since the remote end
821 one previously recorded for the remote side. If so, the
828 The {\eclipse} side then returns control to the remote side via a
839 The remote side should then record the  id Queue for later use (it is
841 fail was received, then the remote side should clean up the attempted queue
842 connection. When the remote side has finished the final stage of the
848 failed on the remote side before {\bf socket_connect} is sent. They also
873 The remote side should close the remote side of the peer queue Queue, and
898 Control is yielded to the remote side, which should acknowledge
903 queues) to the remote side, and clean up the information associated with the
904 attachment. After sending the disconnect_resume message, the remote side
913 a {\bf disconnect} message from the remote side, i.e.\ the remote side
937 done because the application on the {\eclipse} side (such as the remote
938 development tools) may be deep inside some interaction loop with the remote
946 \subsection{Messages from remote side to {\eclipse} side}
951 \item[resume] this message hands over control from remote side to
954 side, or to explicitly hand over control to the remote side.
1058 \item[rpc] this message is sent before the remote side sends an ec_rpc goal
1084 After sending the {\bf rpc} message, the remote side
1087 {\eclipse} side will yield control back to the remote side with a {\bf
1092 \item[rem_flushio(Queue)] this message is sent if the remote side wishes to
1094 the remote side does not know how many bytes will be sent with the operation.
1139 \item[rem_flushio(Queue, Length)] this message is sent if the remote side wishes to
1183 remote side wishes to initiates the creation of a new peer queue. Name is the
1236 control. The {\eclipse} side will yield control back to the remote side,
1245 yield control back to the remote side with a {\bf yield} message. In this
1248 \item[queue_close(Queue)] this message is sent when the remote side
1273 closed on the remote side, with the bookkeeping information removed too.
1275 \item[disconnect] this message is sent if the remote side wishes to initiate
1297 receives this message, the remote attachment between the two sides is
1298 considered terminated. The remote side should now close all connections to the
1326 message, the remote attachment between the two sides is considered
1327 terminated. The remote side should now close all connections to the
1330 In addition, this message should be sent if the remote side has to
1332 happen if the remote process is forced to quit. This is the only case where
1333 a message can be sent via the control connection on the remote side while
1334 it does not have control. Once the message is sent, the remote side can
1345 disconnect_yield} ({\eclipse} side) or {\bf disconnect_resume} (remote
1352 it does not have control. For example, in the Tcl remote interface, the
1365 disconnect from all remote attachments. This is done in {\bf sepia_end/0}
1369 definable event will be raised in {\eclipse}, just before the remote queues
1371 for dealing with the disconnection of the remote interface (on the
1373 probably be provided on the remote side. The event raised has the same name
1375 defined to be {\tt true/0} (i.e. a no-op) when the remote connection is set
1388         printf("Disconnected from remote attachment %w", [Remote]).
1396 {\eclipse} provides the following predicates to support the remote
1401 Initiates a remote attachment at address Host/Port. The predicate
1402 will wait for a remote process to establish an attachment according to the
1408 when the attachment is successfully made and the remote side returns
1410 connection, and is used to identify a particular remote peer (an
1416 level predicates allow more flexibility in the implementation of the remote
1420 called first. The predicate creates a socket server for remote attachment
1422 the socket server that is created. When the predicate returns, the remote process
1425 refuse the connection). The remote process will suspend waiting for the
1430 remote program in between. This will allow the user to start the remote
1431 attachment automatically by executing the remote program from within
1435 This predicate accepts an remote attachment at the socket server Socket.
1440 remote process. {\tt Socket} will be closed if the attachment is
1444 will wait for a remote process to attempt a remote attachment. If no remote
1447 To make the predicate block indefinitely waiting for a remote
1458 connection. The remote side sends a pass-term which is checked to see it is
1461 Unimplemented functionality error is raised if the remote protocol used by
1462 the remote and {\eclipse} sides are incompatible. This can happen if
1466 Initiates the disconnection of the remote attachment represented by
1472 Explicitly yield control to the remote side Peer. Execution on
1473 {\eclipse} side will be suspended until the remote side returns control to
1474 {\eclipse} side. The predicate will succeed when remote side returns
1475 control. The predicate will abort if the remote side initiates
1476 disconnect. The abort will occur after the remote attachment is disconnected.