1 Interfacing & embedding

2 References  Full tutorial and references Embedding and Interfacing Manual Windows - select “Documentation” from the ECLiPSe entry in the “start” menu Unix - access the file “doc/index.html” under the ECLiPSe installation directory  Examples The “doc/examples/” directory under the ECLiPSe installation directory

3 Overview  Languages  General execution model  Architecture Embedded / Remote  Language specifics  Example  References (again)

4 Languages  Java  C  C++  Tcl  External programs

5 General execution model  Synchronous  Control token passing  Explicit and Implicit  ECLiPSe goals bind variables  RPC for simple goals  Queues/Streams for data Peer goal returns yield() resume() post goal ECLiPSe

6 Architecture  Embedded Java C(++) Tcl  Run within the same operating system process  Data structures can be shared  Remote (ERIP) Java Tcl External program  Run in a separate operating system process  Communication over sockets  Data structures must be converted

7 C(++) Embedding  ECLiPSe engine encapsulates the state of computation Single instance  The only interface where ECLiPSe can explicitly call functions defined in the “peer” language  The only interface where non-deterministic goals are handled implicitly  Some care must be taken with memory management

8 Java/ECLiPSe interface  Implements one side of the ERIP  Common interface for embedded & remote Initialisation/shutdown differs  Single Java thread per ECLiPSe instance Blocks when ECLiPSe has control  Data passing over queues/streams Automatic conversion Can pass control by specifying QueueListener

9 Java/ECLiPSe interface ECLiPSeJava atom Atom compound CompoundTerm integer java.lang.Integer integer java.lang.Long list java.lang.Collection float java.lang.Double float java.lang.Float string java.lang.String variable null

10 Remote Predicate Call  Java side supplies goal term to RPC method  ECLiPSe executes goal: three possible outcomes Goal succeeds Goal with satisfying substitutions is returned to Java All subsequent solutions are cut Goal fails Java throws Fail exception Goal causes ECLiPSe exception Java throws Throw exception  Same mechanism used in other interfaces

11 Data transfer using EXDR  Eclipse eXternal Data Representation  Serializable  Represents types which are common across interface  ECLiPSe-side support: write_exdr/2 (to any stream) read_exdr/2 (from any stream)  Java-side support: EXDRInputStream(wraps any InputStream) EXDROutputStream(wraps any OutputStream)

12 ECLiPSe support for ERIP  Setup & teardown remote_connect(?Address, ?Peer, ?InitGoal) remote_disconnect(+Peer)  Queue/stream management peer_queue_create/5 peer_queue_close/1  Sending data Treat queues as normal ECLiPSe streams May be asynchronous Control is transferred when flush/1 is called

13 External programs  External program started with exec(++Command, +Streams, ?Pid) Command takes list of atomic terms Binds stdin, stdout & stderr to the specified Streams Returns process id in Pid  Communication over streams  Wait for termination with wait(?Pid, ?Status) Pid (process id) to wait for Termination Status

14 Embedded ECLiPSe example import com.parctechnologies.eclipse.*; import java.io.*; public class QuickTest { public static void main(String[] args) throws Exception { // Create some default Eclipse options EclipseEngineOptions eclipseEngineOptions = new EclipseEngineOptions(); // Object representing the Eclipse engine EclipseEngine eclipse; // Connect the Eclipse's standard streams to the JVM's eclipseEngineOptions.setUseQueues(false); // Initialise Eclipse eclipse = EmbeddedEclipse.getInstance(eclipseEngineOptions); // Write a message eclipse.rpc("write(output, 'hello world'), flush(output)"); // Destroy the Eclipse engine ((EmbeddedEclipse) eclipse).destroy(); }

15 External program example exec([ls,"-C"], [null, out], Pid). Pid = yes. repeat, get(out,X), (X = -1 -> close(out) ; put(X), fail). aux.ocoroutine.plkegi.plsepia.o bsi.plcprolog.pllint.plsorts.pl cio.plhistory.pllists.plstrings.pl cn.plk_env.plquintus.plt_all.pl X = -1 wait(S, Pid). Pid = S = yes.

16 References  Full tutorial and references Embedding and Interfacing Manual Windows - select “Documentation” from the ECLiPSe entry in the “start” menu Unix - access the file “doc/index.html” under the ECLiPSe installation directory  Examples The “doc/examples/” directory under the ECLiPSe installation directory