10.6  Support for the Remote Interface

ECLⁱPS^e 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 ECLⁱPS^e 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 ECLⁱPS^e side. Peer is the name of the control connection, and is used to identify a particular remote peer (an ECLⁱPS^e 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 ECLⁱPS^e 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 ECLⁱPS^e 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 ECLⁱPS^e 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 ECLⁱPS^e side will be suspended until the remote side returns control to ECLⁱPS^e 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 ECLⁱPS^e. 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 ECLⁱPS^e 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 ECLⁱPS^e.