10.6 Support for the Remote Interface
ECLiPSe provides the following predicates to support the remote
interface:
-
remote_connect(?Address, ?Peer, ?InitGoal)
-
Initiates a remote attachment at address Host/Port. The predicate
will wait for a remote process to establish an attachment according to the
protocol described in section 10.3. If instantiated, InitGoal
is called after the connection is established to perform any user defined
initialisation on the ECLiPSe side (this can be used for example to
define a disconnection handler that will be called when the two sides
disconnect). The predicate succeeds
when the attachment is successfully made and the remote side returns
control to the ECLiPSe side. Peer is the name of the control
connection, and is used to identify a particular remote peer (an
ECLiPSe session can have several).
- remote_connect_setup(?Address, ?Peer, -Socket)
-
remote_connect/2 is implemented by calls to remote_connect_setup/3 and remote_connect_accept/6. These lower
level predicates allow more flexibility in the implementation of the remote
attachment, at the cost of some increased complexity.
The two predicates must be used together, with remote_connect_setup/3
called first. The predicate creates a socket server for remote attachment
at host Host and port Port. Socket will be instantiated to the name of
the socket server that is created. When the predicate returns, the remote process
can request the socket connection at Host/Port address (if the request is
issued before remote_connect_setup/3 is called, the server would
refuse the connection). The remote process will suspend waiting for the
request to be accepted. This will happen when remote_connect_accept/6
is called.
Splitting the attachment into two predicates enables the user to start the
remote program in between. This will allow the user to start the remote
attachment automatically by executing the remote program from within
ECLiPSe with an exec/3 call.
- remote_connect_accept(?Peer, +Socket, +TimeOut,?InitGoal,?PassTerm,-InitRes)
-
This predicate accepts an remote attachment at the socket server Socket.
This predicate is called after a call to remote_connect_setup/3, with the same arguments for Peer
and Socket. The predicate will create the control and rpc connections
according to the protocol described in section 10.3 with a
remote process. Socket will be closed if the attachment is
successful.
TimeOut specifies the amount of time (in seconds) that the predicate
will wait for a remote process to attempt a remote attachment. If no remote
attachment request is made in the specified time, the predicate will
fail. This time is also used for the time-outs on peer queue connections.
To make the predicate block indefinitely waiting for a remote
attachment, the atom block can be used for TimeOut.
InitGoal is used to define the optional initialisation on the
ECLiPSe side when the two sides are connected. InitGoal will be called
immediately after connection, before the two sides are allowed to
interact. If no initialisation is desired, then the argument can be left
uninstantiated. The result of executing the goal is returned in InitRes, which should be initially left uninstantiated.
PassTerm is the pass-term that is used to verify the
connection. The remote side sends a pass-term which is checked to see it is
identical to PassTerm. If not, the attachment fails.
Unimplemented functionality error is raised if the remote protocol used by
the remote and ECLiPSe sides are incompatible. This can happen if
one side is outdated (and using an outdated version of the protocol).
- remote_disconnect(+Peer)
-
Initiates the disconnection of the remote attachment represented by
Peer. All connections (control, ec_rpc, synchronous and asynchronous
streams) will be closed. The predicate succeeds after the clean up. In
addition, a Control event will be raised.
- remote_yield(+Peer)
-
Explicitly yield control to the remote side Peer. Execution on
ECLiPSe side will be suspended until the remote side returns control to
ECLiPSe side. The predicate will succeed when remote side returns
control. The predicate will abort if the remote side initiates
disconnect. The abort will occur after the remote attachment is disconnected.
The abort can be caught to allow for more graceful exits in user
applications by wrapping the remote_yield/1 in a block/3 call.
- peer_queue_create(+Name,+Peer,+Type,+Direction,+Event)
-
Creates a peer queue from ECLiPSe. Name is the name for the queue,
and Peer is the peer to which the queue would be connected. Type specifies if the queue is synchronous or not (atom sync or async),
and direction is the direction of the queue (fromec, toec for synchronous
queues, it is ignored for asynchronous queues), Event is the name of
the event that will be raised on the ECLiPSe side. The user should
associate an event handler goal with Event. If no event is to be raised,
then the empty atom (
''
) should be used.
The predicate does not provide a way to specify a handler for the queue on
the peer side. This is because it is not possible to provide a generic
way that is independent of peer's programming language.
- peer_queue_close(+Name)
-
Closes the peer queue Name from ECLiPSe.