Home

pdf format

1. Local and global size eclipse local size and eclipse global size are the max imum size of the local stack and the global stack respectively In each case the option is an integer representing the required size in megabytes If no setting is made the sizes default to the ECL PS defaults Local size is the maximum combined size of the local stack and the control stack Roughly speaking the local stack is the ECL PS equivalent of the call return stack in procedural languages l he control stack is used to store the choicepoints which occur in the execution of non deterministic code You may therefore need to increase this limit if your search tree is exceptionally deep or if there is a lot of non determinism You can use the ECL PS goal get flag max local control X to find out the 75 current setting For more details see the section on Memory Organisation and Garbage Collection in the ECL PS User Manual Global size is the maximum combined size of the global stack and the trail stack The global stack is used to store data structures The trail stack is used to store backtracking information and is therefore closely related to the control stack You may need to increase this limit if you are creating large data structures in ECL PS or if there is a lot of non determinism You can use the ECL PS goal get flag max global trail X to find out the current setting Again see the section in the ECL PS User Manual for more de
2. This read handler assumes that the data is written using EXDR format So on the Tcl side the data should be written using EXDR format Tcl code ec write exdr ec streamname to channel myqueue data ec flush ec streamname to streamnum myqueue 6 6 3 Asynchronous Queues Asynchronous queues are created on the Tcl side using the Tcl command ec_async_queue_create ec_aysnc_queue_create eclipse stream name mode fromec command toec_event Creates a socket stream between ECL PS and Tcl with the name eclipse stream name on the ECL PS side The created stream is bidirectional and can be written to or read from at both ends The mode argument is for compatibility with the ec aysnc queue create command of the embedded interface only and has no effect on the nature of the queue The procedure returns a channel identifier for use in commands like puts read ec read exdr ec write exdr or close Unlike the synchronous queues only data consumer handlers can be defined if a fromec_command argument is provided this command is set as the Tcl data consumer handler to be called when data arrives on the Tcl end of the socket If toec_event is given it specifies the event that will be raised on the ECL PS side when data is flushed by ec flush on the Tcl side ec queue close eclipse stream name Closes the synchronous or asynchronous queue with the ECL PS name of ec stream name The queue is closed on both the Tcl and ECL PS sides
3. pass term it was given when the remote connection was initiated for remote connect 3 the pass term is the empty string but the user can specify any pass term if remote connect setup 3 and remote connect accept 6 are used If the terms are not identical then the ECL PS side will discontinue the attachment process 7 Remote side read from the control connection the ECL PS name for the control con nection This is sent in EXDR format and is used to identify this particular remote attachment the peer name for the peer This name is needed when calling ec rpc goals that refer to the peer 8 Remote side write the name of the programming language e g tcl java of the remote process on the control connection This should be in EXDR string format and the con nection flushed 9 ECL PS side read the name of the programming language and store it it can be accessed later via peer get property 3 The ECL PS side now wait to accept the socket stream using the same socket server as the control connection for the ec rpc connection This can also time out 10 Remote side create a client socket stream for the ec rpc connection using the same Port as for the control connection This stream should be in blocking mode and perform no translation on the data sent The server socket on the ECL PS will be closed after accepting this client 11 Remote side read the control connection name again on the remote side on the ne
4. ECLiPSe side Host chicken icparc ic ac uk Port 32436 Control peer3 yes eclipse 2 The remote side is suspended awaiting the ECL PS side to return control To return control to the remote side the ECL PS side should call remote yield 1 see section 10 6 for a description of remote yield 1 ECLiPSe side eclipse 2 remote yield peer3 Abort eclipse 3 In this simple example when control is returned to remote side it immediately disconnects thus the remote yield 1 on the ECL PS side is aborted as disconnect was initiated from the remote side as per the disconnect protocol Remote side eclipse 4 test chicken icparc ic ac uk 32436 yes eclipse 5 95 10 4 Remote Peer Queues As discussed in section 10 2 peer queues can be formed interactively during an attachment between the two sides The protocol provides for the creation and closing of these queues on both sides The handling of data on these queues are performed by data handlers routines which either provide data to the queue or consume data from the queue They are triggered by the appropriate control messages so that a data consumer handler would consume data arriving on a queue and a data provider handler would send data onto a queue which would be consumed on the other side These data handlers can be user defined The programmer for the remote side needs to provide the remote side of the interface to the
5. In this case an event handler is directly associated with the socket stream and this event is invoked when the rem flushio message is received The event handler goal in this case is invoked with the culprit argument being the term rem flushio Queue Len where Len is the atom unknown It is up to the user defined event handler goal to properly read the data since the length is unknown the data sent should have natural boundaries e g EXDR terms or use a mutually agreed end of data marker rem flushio Queue Length this message is sent if the remote side wish to transfer data to the ECL PS side on peer queue with queue id Queue and the length of data to be sent is known and is specified in Length the number of bytes to be sent ECLiPSe Remote 103 After sending the message control is transferred over to the ECL PS side and the data is sent on the socket stream On the ECL PS side if the queue is a synchronous queue then it would read Length bytes of data from the socket stream and transfer the data to the queue buffer If an event handler has been associated with the peer queue this will now be invoked to consume the data from the buffer If not for example if the rem flushio was initiated by an ec waitio message then the data is left on the buffer to be processed later In the case that the peer queue is an asynchronous queue an event handler is directly associated with the socket stream and
6. Tcl side This can be accessed by the user using the command ec control name returns the ECL PS name of the control connection An error is raised if this procedure is called before an attachment to ECL PS is made Unimplemented functionality error will be raised if the Tcl or ECL PS side are incompatible with each other This can happen if one side is outdated e g if the remote Tcl interface used and the ECL PS being connected to are not from the same version of ECL PS In this case it is best to update both sides to the latest version of ECL PS 6 3 1 A Note on Security Once a Tcl side is attached to an ECL PS the Tcl side can execute ECL PS goals on the ECL PS side via the ec rpc mechanism This may be a security concern as this gives the Tcl side as much access to the resources on the ECL PS side as the ECL PS process itself even though the Tcl side can potentially be anywhere reachable from the ECL PS side via TCP However the connection must be initiated from the ECL PS side and the attachment process must follow a protocol in order for a successful attachment Nevertheless if a third party somehow knew which Address to connect to and follows the protocol it can steal the connection to ECL PS No authentication is performed by the simple remote connect setup 3 but 3See section 5 7 for more on EXDR format 33 remote connect accept 6 does allow a simple authentication where it can require the Tcl side
7. Term 7 Integer Double String List Nil Struct Variable Integer B byte I XDR_int J XDR long Double i D XDR double String CS Length lt byte gt R Index List 0 C Term List Nil Nil sien 7 Struct Spe IP Arity String Term Variable PEE at Length XDR nat Index XDR nat Arity XDR nat Version 2 Xbyte XDR int lt 4 bytes msb first XDR long lt 8 bytes msb first XDR double lt 8 bytes ieee double exponent first XDR nat n lt 8 bits 1 seven bits unsigned value gt XDR_int gt 0 The version byte is 1 or 2 EXDR version 1 encodings are also valid version 2 encodings and version version 2 decoders can read version 1 encoded terms XDR_long XDR int and byte are all signed integers in two s complement representation The string reference code R means that the string is the same as the Index th S encoded string that occurred in the EXDR term earlier The presence of the CompactFlag C in the header 86 indicates that the term may actually contain such string references If the flag is absent the term does not contain any 87 88 Chapter 10 The Remote Interface Protocol 10 1 Introduction The ECL PS remote interface protocol is used to build a remote interface between ECL PS and some programming language A program written in that programming language can interact and communicate with a separate EC
8. laati aa a Na ara a a ea ee Decomposing ECL PS terms in CH4 cus ue be a Referring to ECL PS terms from C ees Passing Data to and from External Predicates in C ii 85 86 86 89 89 89 90 93 96 96 97 97 106 106 109 B 5 Operations on EOL PS Data a0 5 000 4 bas ke ed owe bom ed ee 117 B 6 Initialising and Shutting Down the ECL PS Subsystem 117 B 7 Passing Control and Data to ECL PS from C l l sen 117 C Summary of C Interface Functions 119 C 1 Constructing ECL PS terms in C sat fed vada wa ow Ea qa mte Bae 119 C 2 Decomposing BCL PS terms in C sues vex wa Gn ects EY ed 120 C3 Referring to BCL PS terms from C i que e doe d x ae ae eer RS 121 C 4 Passing Data to and from External Predicates in C a 122 5 Operations on EGL PS Data 1x murales RES dedita 123 C 6 Initialising and Shutting Down the ECL PSe Subsystem 123 C 7 Passing Control and Data to ECL PS from C 123 C 8 Communication via ECL PS Streams 2 0 0 125 7 9 Miscellaneous isn outer ep on VR atuge d deed EIU m DAS ee AP Meo ey 125 D Foreign C Interface 127 Chapter 1 Introduction This manual contains the information needed to interface ECL PS code to C C or Java environments or to use it from within scripting languages such as Tcl ECL PS is available in the form of a linkable library and a number of facilities are available to pass data between
9. this is invoked to consume the data When the handler returns control is returned to Tcl which continues executing the code after the flush The general sequence of actions are ECL PS side Tcl side Outputs data onto the to ECL PS due alls ec flush to send data to ECL PS side The ECL PS handler associated with the queue is called to consume and pro cess the data Execution continues after the ec flush The ECL PS handler is specified by the event argument of ec queue create This specifies an event that will be raised on the ECL PS side when data is written to a previously empty queue The ECL PS side does not see this data and the event not raised until the data is flushed by ec flush and copied by ECL PS to its buffer and if the buffer was initially empty the event would then be raised The programmer should define the event handler associated with event An example to ECL PS queue with ECL PS handler To create the queue on the Tcl side with an ECL PS handler Tcl code ec queue create myqueue toec remoteflush myqueue Note that the is needed to specify that there is no Tcl handler It defines remoteflush myqueue as the event that will be raised when the queue is flushed by ec flush on the Tcl side 41 The event handler needs to be defined on the ECL PS side ECLiPSe code set event handler remoteflush myqueue read myqueue O read myqueue read exdr myqueue Data process Data
10. with I O operations performed directly on the socket The Name and Queue id for the stream is thus those for the ECL PS socket stream It is the responsibility of the user to ensure that I O operations do not block on these queues They are provided to allow asynchronous transfer of data e g from ECL PS side to the remote side without handing over control and also they allow more efficient transfer of data 10 5 Control Messages These are the messages that are exchanged between the ECL PS and remote sides when the remote side is attached The messages are sent on the control connection and are in EXDR format All arguments for the messages are either atoms or integers The messages are used to co ordinate and synchronise the two sides A message should only be sent from a particular side when that side has control and control is handed over to the other side when the message is sent Most messages are used to initiate an interaction with the other side That is used to cause some action to take place on the other side control is handed over the action takes place on the other side and eventually control is handed back when the action is completed Control can also be explicitly handed over from one side to the other so that the other side can initiate interactions Some additional messages can only be sent as part of an interaction for exchanges of information between the two sides Finally there are messages for terminating the remote
11. 3 Restrictions and Recommendations It is neither supported nor recommended practice to call ec resume from within an external predicate because this would invariably lead to programs which are hard to understand and to get right Currently it is also not possible to post goals from within an external predicate but that is a sensible programming style and will be supported in forthcoming releases Posting events however is already possible now 19 20 Chapter 5 Embedding into Tcl Tk This chapter describes how to embed ECL PS into a Tcl host program Tcl Tk is a cross platform toolkit for the development of graphical user interfaces The facilities described here make it possible to implement ECL PS applications with platform independent graphical user interfaces The interface is similar in spirit to the ECL PS embedding interfaces for other languages An alternative method of using ECL PS with Tcl is to use the Tcl remote interface described in chapter 6 In this case the ECL PS is ran as a separate program The facilities provided by the remote and embedding interfaces are largely compatible so that it is possible to reuse the same Tcl and ECL PS code in both interface The advantage of the embedding interface is that ECL PS is much more tightly coupled with the Tcl program and communication between the two is more efficient The advantage of the remote interface is that the Tcl and ECL PS programs are not tightly couple
12. ECL PS embedded into another host language e More than one Tcl or other remote process can be attached to a single ECL PS via the remote interface e For the programmer the embedding and remote interfaces are largely similar and once the connection is established in the remote interface the same code on the ECL PS and Tcl sides can be used for both interfaces The remote interface thus offers more flexibility than an embedding interface in how the Tcl code can be connected to an ECL PS program However as the Tcl and ECL PS processes are not as tightly coupled as in an embedded interface the speed of communications between the Tcl and ECL PS processes is likely to be slower Currently Tcl is the only language available for connecting to ECL PS remotely However it is expected that remote interfaces for other languages will become available in future releases of ECL PS 6 1 Basic Concepts of the Interface The interface is used by starting separate ECL PS and Tcl processes and then attaching the Tcl process to the ECL PS process Once attached the Tcl and ECL PS processes can 31 communicate much as in the embedded interface ECL PS goals can be sent from the Tcl side to the ECL PS side via the remote predicate call ec rpc mechanism and further I O queues can be established between the ECL PS and Tcl processes to allow streams of bytes to sent from one side to the other The attached Tcl process can also be deta
13. PS side closes the peer queue with id Queue ECLiPSe Remote ueue close resume The remote side should close the remote side of the peer queue Queue and remove all book keeping information associated with it Control should then be returned to ECL PS via a resume message The ECL PS side should also close the queue and remove bookkeeping information on the ECL PS side disconnect this message is sent when ECL PS side initiates disconnect ECLiPSe Remote disconnect disconnect resume Control is yielded to the remote side which should acknowledge with the discon nect resume message Once the ECL PS side receives this message the connection between the two sides is considered terminated The ECL PS side will then close all the connections the control and ec rpc connections and any asynchronous and synchronous queues to the remote side and clean up the information associated with the attachment After sending the disconnect resume message the remote side should also shutdown its end of the connection by closing all the connections on its side Note that the disconnection message can be used to terminate the attachment from within an interaction In such cases the interaction s would not be completed disconnect yield this message is sent when ECL PS side receives a disconnect message from the remote side i e the remote side initiated disconnection 101 ECLiPSe Remote disconnect disconnec
14. ToC Similar to ec resume status but allows an integer to be returned to the caller as done by ec resume long ec wait resume status long long ToC int timeout Similar to ec resume status long but waits for the ECL PS thread to finish execution The function returns as soon as the ECL PS thread is finished or after timeout millisec onds whatever is earlier In case of timeout the return value will be PRUNNING If timeout is zero the function is equivalent to ec resume status long If timeout is nega tive there will be no timeout and the function will only return when the ECL PS thread is finished 124 int ec_handle_events long ToC Similar to ec_resume_long but posted goals are not executed only events are handled void ec cut to chp ec ref Cut all choicepoints created by the batch of goals whose execution succeeded The argu ment should have been obtained by a call to ec_resume2 int ec post event pword Name Post an event to the ECL PS engine This will lead to the execution of the corresponding event handler once the ECL PS execution is resumed See also event 1 and the User Manual chapter on event handling for more information Name should be an ECL PS atom int ec post event string const char Post an event to the ECL PS engine This will lead to the execution of the corresponding event handler once the ECL PS execution is resumed See also event 1 and the User Manual chapter on event han
15. ae he tee eR USE un ete ae ut tierce als tig aS Using the Java ECL PS Interface amp I Getting Started e s 24 0b eee URB E SS R RR ROS RUBUS S A eue Es 8 1 1 Check your Java SDK version 2 a a a 8 1 2 Make the com parctechnologies eclipse package available in your class pathi i s xus S a m oS Uu scs aV od RV Ue RAO S EROR RR eS 8 1 3 Compile and run QuickTest java lens 8 2 Functionality overview A closer look at QuickTest java i 21 21 21 22 23 24 25 25 26 27 27 27 28 31 31 32 32 33 34 34 34 35 36 42 46 47 48 48 48 50 5l 55 55 55 55 56 58 8 3 8 4 8 5 8 6 9 1 9 2 Java representation of ECL PS data 2o A 8 3 1 General correspondence between ECL PS and Java data types 8 8 2 Atoms and compound terms 2 0 2 eee Saa pie be A ee See Ma a ee ea es ee a EO ae a 8 3 4 Floats and Doubles 2 0 2 a 9 0 Integers a c hc ae ak ls eo bE ers euh Ae Dg 8 2 0 Variables ise yo or a a Bite wee Gee BED amete ries 9 7 Lhe equals method c IgG eC Oe LS Executing an ECL PS goal from Java and processing the result 8 4 1 Passing the goal parameter to rpc 0 00022 ee ee 8 4 2 Retrieving the results of an rpc goal execution ss 8 4 3 More details about rpc goal execution 2e Communicating between Java and ECL PS using queues 8 5 1 Opening using and closing queues 002 ee
16. and book keeping information for the queue is removed Asynchronous queues are bi directional queues which allows data transfer between ECL PS and Tcl sides without transfer of control In the case where a Tcl data consumer handler is defined in fromec command which is invoked on the Tcl side when the queue is flushed on the ECL PS side the ECL PS side will carry on execution while the handler is invoked on the Tcl side 42 These queues are designed to allow for more efficient transfer of data between ECL PS and Tcl than the synchronous queues For data transfer from ECL PS to Tcl the intended use is that a Tcl data consumer handler would be invoked as the data becomes available on the Tcl side after being flushed from the ECL PS side Note that control is not handed over to Tcl side in this case the Tcl handler is invoked and executed on the Tcl side while ECL PS side still has control with the restriction that the Tcl handler is unable to issue ec rpc goals because ECL PS side still retains control Another difference with the synchronous from ECL PS queue is that the handler would read from the queue in non blocking mode i e it will read whatever data is available on the queue at the T cl side and never wait for more data If more data become available the handler would be invoked again The following Tcl handler is pre defined for the asynchronous queue for handling from ECL PS data ec stream to window tag tert widget s
17. async queue create If the ECL PS stream number was supplied in these commands then the stream number is also considered the symbolic name for the queue as well The Tcl interface provides several commands to convert the names from one form to another ec streamname to channel eclipse name Returns the Tcl channel name for the remote queue with the symbolic name eclipse name ec streamnum to channel eclipse stream number Returns the Tcl channel name for the remote queue with the ECL PS stream number eclipse stream mumber ec channel to streamnum channel Returns the ECL PS stream number for the remote queue with the Tcl channel name channel ec streamname to streamnum eclipse name Returns the ECL PS stream number for the remote queue with the symbolic name eclipse name ec stream nr eclipse name This is an alias for ec streamname to streamnum for compatibility with embedded interface 47 6 7 Additional Control and Support The remote interface provides additional support for controlling the interaction of the Tcl and ECL PS sides such as explicit transfer of control between ECL PS and Tcl and the disconnec tion of the Tcl and ECL PS 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 ini tialisation needs to be performed such
18. attachment Note that interactions can be nested that is an interaction from one side can contain an interaction initiated from the other side The implementer for the remote interface should provide the methods for a programmer to ini tiate the interactions from the remote side These routines would send the appropriate control messages to the ECL PS side and the messages should not be directly visible to the program mer The usage of each message is summarised in the diagram s accompanying them These diagrams show e time proceeds downward The ECL PS side is shown on the left the remote side on the right Messages are shown as vertical arrows between the two sides The direction of the arrow indicates the direction the message is sent 97 e the context in which the message can be sent i e the message from the other side that it is either expecting as a response or that it is a response to The message sequence is shown with the message highlighted e any accompanying actions expected with the message These actions are either sending or receiving data on some other connections between the two sides These are shown as dashed arrows in the diagrams e whether nested interactions can take place between messages of an interaction This is indicated by vertical ellipsis between the messages in the diagram In such cases the nested interaction can be initiated and this interaction completed before the next message for the origin
19. can be written and read using the EXDRInputStream and EXDROutputStream classes discussed in Section 8 5 2 Via the QueueListener feature Java code can be invoked in a sense from within ECL PS The use of this feature is discussed in Section 8 5 3 In some cases the standard streams stdin stdout and stderr of the ECL PS engine will be visible to Java as queues How to use these is discussed in Section 8 5 4 8 5 1 Opening using and closing queues We now explain the standard sequence of events for using queues Opening and closing can be performed in a single step from either the Java or the ECL PS side Opening a queue using Java methods FromEclipseQueue and ToEclipseQueue do not have public constructors Instead we invoke getFromEclipseQueue or getToEclipseQueue This asks the EclipseConnection object for a reference to a FromEclipseQueue or ToEclipseQueue instance which represents a new queue To specify the stream for later reference we supply the method with a string which will equal to the atom by which the queue is referred to as a stream in ECL PS For example the following code creates two queues one in each direction ToEclipseQueue java to eclipse eclipse getToEclipseQueue java to eclipse FromEclipseQueue eclipse to java eclipse getFromEclipseQueue eclipse to java These methods will create and return new FromEclipseQueue or ToEclipseQueue objects and will also open streams with the specified names
20. for writing to reading from and otherwise interacting with streams Any of these may be used Perhaps most useful are read exdr 2 and write exdr 2 these are explained in Section 8 5 2 For the stream ID you may either use the stream name or the stream number obtained for example using peer get property 3 Note always flush When communicating between Java and ECL PS using queues you should always invoke the flush method of the Java OutputStream which you have written to whether it be a ToE clipseQueue or an EXDROutputStream Similarly on the ECL PS side flush 1 should always be executed after writing Although in some cases reading of the data is possible without a flush flushing guarantees the transfer of data Closing a queue using Java methods This is done simply by calling the close method on the FromEclipseQueue or ToEclipseQueue instance Closing a queue using ECL PS predicates This is done by executing the builtin peer queue close 1l Note that the builtin close 1 should not be used in this situation as it will not terminate the Java end of the queue 8 5 2 Writing and reading ECL PS terms on queues Rather than dealing with low level data I O instructions such as reading and writing bytes the Java ECL PS Interface provides classes for reading and writing whole terms In the underlying implementation of these classes the EXDR ECL PS eXternal Data Representation format is used This allows ECL PS to communi
21. handler for that event is invoked 7 C code possibly within a signal handler post_event EC_atom timeout ECLiPSe code handle_timeout timeout lt appropriate action gt set event handler timeout handle timeout 1 2 3 3 The yield resume model Although implicitly yielding control when a set of goals succeeds or fails is often enough it is possible to explicitly yield control to the C level This is done with the yield 2 predicate This yields control to the calling C program The arguments are used for passing data to C and from C When yield 2 is called within ECL PS code the EC_resume function returns the value EC yield so one can recognise this case The data passed out via the first argument of yield 2 can be accessed from C via the EC ref argument to EC_resume The data received in the second argument of yield 2 is either the list of posted goals or an EC word passed as an input argument to EC resume yield out 1 2 InData In this example the compound term out 1 2 is passed to C If we had previously called EC ref FromEclipse result EC resume FromEclipse then result would be EC yield and FromEclipse would refer to out 1 2 If then we resumed execution with result EC resume EC atom ok FromEclipse then the variable InData on the ECL PS side would be set to the atom ok 2 3 4 Summary of EC resume arguments EC resume can be called
22. if speed is not critical and if the goal does not contain variables whose values may be needed later This function is part of the simplified interface void ec post exdr int len const char exdr same as ec post goal but the goal is given in EXDR format see chapter 9 This function is part of the simplified interface int ec resume resume execution of the ECL PS engine All posted goals will be executed and all posted events will be handled The return value will be PSUCCEED if the goals succeed PFAIL is 123 int int int int int int int returned if the goals fail and PYIELD if control was yielded because of a yield 2 predicate call in the ECL PS code If a writable queue stream with yield option see open 4 was flushed the return value is PFLUSHIO If there was an attempt to read from an empty queue stream with yield option the return value is PWAITIO If an asynchronous ECL PS thread is already running PRUNNING is returned No parameters can be passed This function is part of the simplified interface ec resumel ec ref ToC Similar to ec resume but if the return value is PSUCCED the ToC argument returns a cut value that can be used to discard alternative solutions by passing it to ec cut to chp If the return value is PYIELD control was yielded because of a yield 2 predicate call in the ECL PS code and ToC contains the data passed by the first argument of yield 2 If the return value is PFLU
23. linker about these directories so that these tools can include and link the appropriate files A make file Makefile external can be found 3 together with the libraries The definitions in that makefile may have to be updated according to your operating system environment A set of example C and C programs can be found in usr local eclipse doc examples When delivering an application you will have to include with it the contents of the directory usr local eclipse lib without which ECL PS cannot work Normally this would be copied into the directory structure of the delivered application The interface can set different values for this directory enabling different applications to have different sets of libraries 2 1 2 Definitions To include the definitions needed for calling the ECL PS library in a C program use include lt eclipse h gt For C a more convenient calling convention can be used based on some classes wrapped around these C definitions To include these use include lt eclipseclass h gt 2 1 3 Compiling linking and running on Unix Linux Assuming that the environment variable ECLIPSEDIR is set to the ECL PS installation direc tory and the environment variable ARCH is set to the architecture operating system name an application can be built as follows gcc I ECLIPSEDIR include ARCH eg c basic c L ECLIPSEDIR lib ARCH leclipse This will link your application with the shared library libec
24. long and dident fixed size data types you are responsible for allocating the memory For strings you declare a char variable and on conversion it will point to the internal ECL PS string In the following example we see how one can try to convert to different types Of course normally you will know what type you are expecting so only one of these functions need be called 11 EC_word term double r long i EC_atom did char s if EC succeed term is double amp d cout lt lt d lt lt Wn else if EC succeed term is_long amp i cout lt lt i lt lt n else if EC succeed term is atom amp did cout lt lt did Name lt lt Wn else if EC succeed term is string amp s cout lt lt s lt lt n else cout lt lt not a simple type n The term is converted by the function which returns EC_success The functions that fail to convert will return a negative error number Care has to be taken with strings these pointers point to the internal ECL PS string which may move or be garbage collected during an ECL PS execution As a result if a string is to be kept permanently one should copy it first 3 2 20 Decomposing ECL PS terms The function ec_get_arg index term amp subterm is used to get the index th subterm of a structure The index varies from 1 to arity of term A list can also be decomposed this way where the head is at index 1 and the tail at index 2 Below we see how
25. multitask 1 55 56 peer get property 3 71 92 peer queue close 1 71 108 peer queue create 5 71 104 108 posting events 7 posting goals 6 pword 10 QueueListener interface 69 71 73 Queues 73 queues 61 64 70 73 queues closing 70 71 queues opening 70 71 read exdr 2 25 71 73 86 read string 4 25 recordz 2 14 references 13 14 remote connect 3 32 48 80 81 90 92 106 remote connect accept 6 32 34 80 81 90 92 107 remote connect setup 3 32 33 80 81 90 92 107 remote disconnect 1 49 81 107 remote yield 1 48 49 68 81 95 102 108 remote eclipse 32 RemoteEclipse class 74 78 82 resume 6 8 rpc method 69 rpc method 63 65 67 69 72 74 81 84 schedule suspensions 2 117 123 search 9 set_event_handler 2 36 setarg 3 13 116 setval 2 14 state 6 string 11 12 structure 11 12 term 10 11 thread 5 6 type testing 11 write 2 24 write_exdr 2 25 71 73 86 xget 3 14 xset 3 15 yield 8 yield 2 8 22 23 68 124 130
26. on the ECL PS side No stream in ECL PS should exist with the specified name If a stream exists which has this name and is not a queue between the Java object and ECL PS the Java method throws an exception If the name is used by a pre existing queue it is returned so the getFromEclipseQueue and getToEclipseQueue methods can also be used to retrieve the queue objects by name once if they have already been created 70 Opening a queue using ECL PS predicates You can use the ECL PS builtin peer_queue_create 5 to open a queue Used correctly these have the same effect as the Java methods explained above For the peer name you should use the atom returned by the getPeerName method of the relevant EclipseConnection instance The direction should be fromec for a FromEclipseQueue and toec for a ToEclipseQueue The queue type should always be sync when using the Java ECL PS interface asynchronous queues are not supported Transferring data using Java methods On the Java side once a FromEclipseQueue has been established you can treat it as you would any instance of java io InputStream of which FromEclipseQueue is a subclass Similarly ToE clipseQueue is a subclass of java io OutputStream The only visible difference is that FromE clipseQueue and ToEclipseQueue instances may have QueueListeners attached as is discussed in Section 8 5 3 Transferring data using ECL PS predicates On the ECL PS side there are built in predicates
27. remote init chicken icparc ic ac uk 25909 ec remote init host port init command pass format Initialise the remote Tcl interface on the Tcl side A corresponding remote connect 3 must have been started on the ECL PS side which specifies the hostname host and port number port to connect to The optional init command is an is a Tcl command that will be invoked at the end of the attachment before control is handed over to the ECL PS side see section 6 7 for more details pass and format are optional arguments for a simple security check they specify an ECL PS term that will be matched against a corresponding term using 2 on the ECL PS side before the connection is allow to proceed pass will be sent to the ECL PS side in EXDR format the default is an empty string which is what remote connect setup 3 expects If successful some initial links are established between the two sides such as the control connec tion and the connection to allow rpc goals to be sent from the Tcl to the ECL PS side After the attachment optional user defined initialisations are performed on both sides via the InitGoal argument on the ECL PS side and the init command on the Tcl side and the two sides can then interact Initially the control is given to the Tcl side and remote_connect 3 returns only when control is handed over to the ECL PS side As part of the attachment process the ECL PS name of the control connection is passed to the
28. returns from flush and con tinue executing the following code The Tcl handler is specified by command in ec queue create command includes the name of the Tcl procedure to invoke and any user defined arguments When the handler is invoked two additional arguments are appended the ECL PS stream number for the queue and the number of bytes that has been sent on the queue This command should read the data off the queue and process it The following predefined T cl data consumer handlers are provided ec stream to window sync tag text widget stream mr length Read length bytes from the specified queue and insert the data at the end of the existing tert widget using tag as the tag for the text If this is invoked as a handler for a from ECL PS queue length and stream nr would be supplied when the handler is invoked ec stream output popup label text stream mr length Pops up a window displaying the abel text a text field displaying the contents of the specified queue stream and an ok button for closing The data is read as normal strings This is the default Tcl fromec handler that will be called if ec_create_queue did not define one An example from ECL PS queue with Tcl handler To create the queue on the Tcl side with a Tcl handler Tcl code ec queue create myqueue fromec ec stream to window sync red tex twin Note that the last specifies that there is no ECL PS handler This is the actual default for this a
29. rpc EcSideControl 4 control connection new client socket Host Port Control send the protocol version information to the ECLiPSe side 4 we are the remote side so must have our own version info write exdr Control remote protocol 1 flush Control 4 read response from ECLiPSe side to make sure it is compatible read exdr Control IsSameVersion IsSameVersion yes gt true writeln Incompatible versions of remote protocol Failing 93 if fail T send pass term if this does not match the pass term on the ECLiPSe side it will terminate the attachment write exdr Control Pass flush Control ECLiPSe side name for connection read exdr Control EcSideControl send language name to ECLiPSe side write exdr Control eclipse flush Control Ec rpc connection new client socket Host Port Ec rpc read control name again on Ec rpc to verify connection in a more sophisticated implementation this should time out read exdr Ec rpc EcSideControl gt true not verified terminate connection close Control close Ec rpc fail Remote side now has control call Init to perform application specific initialisations call Init hand control over to ECLiPSe side write exdr Control resume flush Control new client socket Host Port Socket socket internet stream Socket connect Socket Host Port the following code make use of remote attach 6 to make a
30. stream input popup set ec stream input string proc ec stream input popup Msg Stream 1 global ec stream input string toplevel ec stream input box label ec stream input box prompt width 40 text Msg entry ec stream input box input bg white width 40 textvariable ec stream input string bind ec stream input box input Return destroy ec stream input box pack the popup window pack ec_stream_input_box prompt side top fill x 40 pack ec_stream_input_box input side top fill x tkwait window ec_stream_input_box puts nonewline ec_streamnum_to_channel Stream ec_stream_input_string flush the output to ECLiPSe with the length of the input ec_flush Stream string length ec_stream_input_string Data is flushed to the ECL PS side using ec flush The puts needs the Tcl channel name of the queue to write to and this is provided via the Tcl remote interface command ec streamnum to channel see section 6 6 5 ec flush is called with two arguments in this case both the queue number Stream and the length of the data that is sent Note that this makes the assumption that no other unflushed data has been written to the queue ECL PS Handler for a To ECL PS Queue For a to ECL PS queue the ECL PS han dler would be a data consumer This handler is initiated when Tcl initially has control and flushes data on a queue using ec flush Control is transferred to ECL PS and if the ECL PS handler is defined
31. than using a generic procedure to check the argument of every external function After compiling definitions of the foreign 3 predicate the predicate foreign file 2 is ignored the predicate make simple interface has to be called This predicate generates a file inter face c which contains the auxiliary C definitions This file has to be compiled to obtain the interface o file it might also have to be edited to include other files After the file interface o has been generated the system is fully compatible with the Quintus SICStus foreign interface and calling load foreign files 2 will connect the external functions with ECL PS Although it is possible to use this library to interface existing independent C functions its main use is to port foreign interface from Quintus or SICStus Please refer to their manuals for the description of the foreign interface 127 Index 33 data types Java 64 ARCH 3 architecture 3 array 13 asynchronous 7 atom 9 backtracking 6 bag_dissolve 2 14 block 3 108 choicepoint 7 8 classpath 62 compound term 11 cut 7 directories 3 doc examples 1 ec_async_queue_create Tcl embedding in terface 24 ec_async_queue_create Tcl remote inter face 42 ec_channel_to_streamnum Tcl remote inter face 47 ec_connected Tcl remote interface 49 ec_control_name Tcl remote interface 33 ec_disconnect Tcl remote interface 49 ec_exdr2tcl 28 ec_flush Tcl embeddi
32. the execution of the goal After the attachment extra I O connections can be established between the two sides This allows data to be transferred from one side to the other These connections referred to as peer queues can be of two types synchronous These queues are synchronised by the control connection Control messages are exchanged between the two sides to ensure that they are both are synchronised for the data transfer one side consumes the data that is sent from the other This ensures that no blocking occurs with the I O operations across the sockets asynchronous These queues can perform I O operations that are not co ordinated by the control connection Either side can write to or read from the queue without transferring control In fact if the remote language is multi threaded it can perform asynchronous I O while ECL PS side has control Note that asynchronous I O operations may block on the ECL PS side 10 3 Attachment The attachment process is summarised in Figure 10 3 It is initiated from the ECL PS side by either calling remote connect 3 or the more flexible remote connect setup 3 and remote connect accept 6 pair In fact remote connect 3 is implemented using re mote connect setup 3 and remote connect accept 6 with default values for some of the arguments The attachment can be divided into several phases 1 Initialisation and handshaking the control connection is established and handshaking between the tw
33. the ECL PS side When ECL PS sends data to Java it will decide between the two classes depending on the number of bits needed for the integer So for example if the number is small enough to fit in an Integer that is what will be returned Note that therefore the type of number coming back from ECL PS cannot be relied upon to be of one type or the other if it could fall on either side of the 32 64 bit boundary If you require a set of numbers coming from ECL PS to be all of one Java type e g long then the best approach is to cast the object returned by ECL PS to an instance of java lang Number and then invoke the appropriate conversion method e g longValue 8 3 6 Variables The Java null token is used to represent any variables being sent to ECL PS All variables coming from ECL PS will appear as null The limitations of this are discussed in more detail in Section 8 4 66 8 3 7 The equals method The equals method has been overridden for AbstractCompoundTerm and therefore also for Atom and CompoundTermImpl The implementation returns true iff the parameter Object implements CompoundTerm and its functor and arity are equal to those of the AbstractCom poundTerm and pairwise invocations of equals return true between each of the Abstract CompoundTerm s arguments and the corresponding argument of the parameter object 8 4 Executing an ECL PS goal from Java and processing the result The EclipseConnection interface p
34. the Java program is to be run on a workstation The RemoteEclipse class can be used to connect Java to ECL PS in these two scenarios The deployment model is that the RemoteEclipse Java object is a Proxy for the ECL PS engine which is running on the remote machine as shown in UML notation in Figure 8 3 Java virtual machine host Java virtual machine process eclipse RemoteEclipse TCP IP network connection Eclipse host peer ECLiPSe process Figure 8 3 UML deployment diagram for RemoteEclipse The key consequences of this deployment model are e ECL PS and Java can run on different machines and the two machines may have a different architecture OS e ECL PS can connect to multiple Java processes using this model e The lifetime of the ECL PS engine need not necessarily be a sub duration of the lifetime of the JVM Initialisation of a RemoteEclipse connection Connecting Java to ECL PS using RemoteEclipse requires the ECL PS engine to be primed so that it is ready to accept the connection By the time it connects the Java program must have 79 the IP address of the machine hosting the ECL PS engine the server and the port number being used for the connection The attachment protocol also optionally allows for a password to be used by the Java side and checked against one specified on the ECL PS side Also the server must be configured to allow TCP IP socket servers which can be connected to by the mac
35. to eclipse The Java program then makes an rpc invocation to the ECL PS program s only predicate read 2 write 1 0 which is defined as follows read 2 write 1 read exdr java to eclipse Term1 72 read_exdr java_to_eclipse Term2 write_exdr eclipse_to_java pair Termi Term2 flush eclipse_to_java The built in read exdr 2 reads a term s worth of data from the stream supplied and instantiates it to the second argument So read_2_write_1 0 reads the two terms from the stream They are then written on to the eclipse_to_java stream within a pair functor using the built in write_exdr 2 and the stream is flushed When the predicate succeeds the rpc invocation returns and the term data is on eclipse_to_java in EXDR format The next step of the java program is the following System out println eclipse to java formatted readTerm Since eclipse to java was the FromEclipseQueue passed as a parameter when eclipse to java formatted was initialised the readTerm method of this object reads the EXDR data which is on eclipse to java and converts it into the appropriate Object to repre sent the piece of data in this case a CompoundTerm This Object is then returned by readTerm Hence the output of the program is pair a b 8 5 8 Using the QueueListener interface It may sometimes be useful to have Java react automatically to data arriving on a queue from ECL PS An example of this would be where a Java program has a gra
36. we would write a function to find the nth element of a list int nth const int n const EC_word list EC_word amp el EC_word tail list for int i 1 i n i if EC fail tail arg 2 tail return EC fail return tail arg 1 e1 The above function actually is not limited to lists but could work on any nested structure 3 3 Referring to ECL PS terms The terms constructed so far as EC words have been volatile that is they do not survive an ECL PS execution due to eg garbage collection It is possible to create safe terms that have been registered with the ECL PS engine and which do survive execution The EC ref and EC refs classes are provided for this purpose EC refs are vectors of safe terms When you declare an EC ref it will contain free variables 12 EC_ref X declare one free variable EC_refs Tasks 10 declare 10 free variables EC refs work like logical variables When ECL PS fails during search they are reset to old values They are always guaranteed to refer to something i e they never contain dangling references If ECL PS backtracks to a point in the execution older than the point at which the references were created they return to being free variables or take on their initial values It is possible to declare references giving them an initialiser but this must be an atomic type that fits into a single word That restricts you to atoms integers and nil You can freely assign betw
37. with two optional arguments An input argument that is an EC word and an output that is an EC ref If the input argument is omitted input is taken as the list of posted goals Otherwise the input to ECL PS is exactly that argument If the output argument is present its content depends on the value returned by EC resume If it returns EC succeed it is the choicepoint identifier If it returns EC yield It is the first argument to the yield 2 goal If it returns EC fail it is not modified Chapter 3 Managing Data and Memory in Mixed Language Applications ECL PS is a software engine for constraint propagation and search tasks As such it represents its data in a form that is different from how it would be represented in a traditional C C program In particular the ECL PS data representation supports automatic memory manage ment and garbage collection modifications that can be undone in a search context referential transparency and dynamic typing In a mixed language application there are two basic ways of communicating information between the components coded in the different languages Conversion When data is needed for processing in another language it can be converted to the corresponding representation This technique is appropriate for simple data types integers strings but can have a lot of overhead for complex structures Sharing The bulk of the data is left in its original representation referred to by a hand
38. within the goals Control is explicit in C After posting some goals the C program calls the EC resume function and these goals are all solved A return code says whether they were successfully solved or whether a failure occurred In ECL PS control is normally implicit Control returns to C when all goals have been solved include eclipseclass h main ec_init writeln hello world post goal term EC functor writeln 1 hello world EC resume ec cleanup 0 The above is an example program that posts a goal and executes it 2 3 1 Control flow and search Using this model of communication it is possible to construct programs where execution of C code and search within the ECL PS are interleaved If you post a number of goals of which some are non deterministic and resume the ECL PS execution and the goals succeed then control returns to the C level By posting a goal that fails the ECL PS execution will fail back into the previous set of goals and these will succeed with a different solution include eclipseclass h main ec_init EC_ref Pred post goal term EC functor current built in 1 Pred while EC succeed EC resume 1 post goal term EC functor writeln 1 Pred 6 post_goal EC_atom fail ec_cleanup 0 The above example prints all the built ins available in ECL PS When EC resume returns EC succeed there i
39. E ERROR if the argument index is out of range ec arity pword returns the arity number of arguments of an ECL PS pword if it is a structure otherwise Zero ec get handle const pword const t ext type t ext ptr checks whether the ECL PS pword is a handle whose method table matches the given one and if so the data pointer is returned ec is var const pword checks whether the ECL PS pword is a variable Note that the return values are PSUC CEED are PFAIL rather than standard C truth values C 3 Referring to ECL PS terms from C The data types ec refs and ec ref provide a means to have non volatile references to ECL PS data from within C data structures However it must be kept in mind that ECL PS data structures are nevertheless subject to backtracking which means they may be reset to an earlier status when the search engine requires it Creating a reference to a data structure does not change that in any way In particular when the search engine fails beyond the state where the reference was set up the reference disappears and is also reset to its earlier value 121 ec_refs ec_refs_create int n const pword pw create a data structure capable of holding n non volatile references to ECL PS data items They are initialised with the value pw which must be of a simple type ec refs ec refs create newvars int like ec refs create but each item is initialised to a freshly created ECL PS variable void ec refs
40. ECL PS Embedding and Interfacing Manual Release 5 7 Stefano Novello IC Parc Joachim Schimpf IC Parc Kish Shen IC Parc Josh Singer Parc Technologies Ltd August 7 2004 Trademarks WindowsNT and Windows95 are trademarks of Microsoft Corp Java SunOS and Solaris are trademarks of Sun Microsystems Inc International Computers Limited and Imperial College London 1996 1999 Contents 1 Introduction 1 2 Calling ECL PS from C 3 RE Vo eet started gauras oF AS SR Sold eer Al ee Pe a RU ne 3 2 1 T Directories 223 REUS IE be et Ae Fok 3 2 1 2 Definitions 4 64k kx eR Ee 8 o9 de X 3 o3 G3 4 2 1 3 Compiling linking and running on Unix Linux 4 2 1 4 Static linking Unix Linux cou 24 Se hk ote be EG OR Sa 4 2 1 5 Compiling linking and running on Windows 5 2 2 Creating an PCL PS context s Gr s fone ee ante OE ee SS bore RES 5 221 lInitialisatl n x sce de as ect tee i RG i ee ae A 5 2 9 Control TOW ses sx deep aren Behe ce a es ho e i ene ut ec 6 2 3 1 Control flow and search 2 2 2 2e 6 2 3 2 Asynchronous events 2 2 2 2 a e 7 2 3 8 The yield resume model lee 8 2 3 4 Summary of EC_resume arguments 24 8 3 Managing Data and Memory in Mixed Language Applications 9 3 1 Constructing ECL PS datas ato ma penceasd amp fan ote le eke qa ee Baits 9 3 1 1 BOL PS atoms and functors s ex REO we he ae E SE 9 3 1 2 Buil
41. ECL PS side as the data is to be consumed by the suspended read operation instead This is ensured in the protocol by prohibiting handlers on both sides of a synchronous peer queue Note that the ECL PS side will also listen to the control connection while waiting for the data to be sent from the remote side If a resume is sent before the data arrives this is likely caused by a programming error in the data provider handler which finished without sending data to the ECL PS side The ECL PS side will print a warning message on the 99 warning output stream and immediately yield back to the remote side Other messages are handled as normal recursively while waiting for the data to arrive this is mainly intended to allow for unexpected aborts from the remote side although it could also be used to perform ec rpc calls before the remote side sends the data socket_client Port Name Type Dir this requests the remote side to form a client socket connection for the remote peer queue Name The queue is of type Type sync or async and direction Dir fromec toec for synchronous queues bidirect for asynchronous queues The client socket is to connect at port Port with the ECL PS side host name ECLiPSe Remote socket client P N T D socket connect N S socket accept N Q resume The ECL PS side first creates a server socket for the peer queue Name The port address is Port This along with the details of the
42. JVM and shares its resources can be started and ended only once during the lifetime of the JVM There is no public constructor method for EmbeddedEclipse Initialisation of the embedded ECL PS is done using the static get Instance method of class Embedded Eclipse which takes an EclipseEngi neOptions instance as a parameter The method uses this to configure and set up ECL PS and then returns an object of type EmbeddedEclipse There may only ever be one instance of Em beddedEclipse in a JVM If the embedded ECL PS has already been set up or if it has been set up and terminated subsequent invocations of getEclipse with an EclipseEngineOptions will throw exceptions However during the lifetime of the embedded ECL PS a reference to the unique EmbeddedEclipse object can be obtained using the parameterless static getEclipse method 76 Java virtual machine host Java virtual machine process lt lt Singleton eclipse EmbeddedEclipse Figure 8 1 UML deployment diagram for EmbeddedEclipse Termination of an EmbeddedEclipse The destroy method which appears in the Embed dedEclipse class will shut the embedded ECL PS down Once the destroy method has been invoked the invocation of any methods which require use of the ECL PS engine will result in an EclipseTerminatedException being thrown The destroy method should free all the resources of the JVM process which were being used by the embedded ECL PS Once the EmbeddedEclipse has been des
43. L PS process via the remote interface The Tcl remote interface chapter 6 is an example of such an interface This chapter describes the protocol so that remote interfaces to other programming languages can be built The protocol is designed to allow the implementer to build an interface that is compatible with the embedding interface of the same language This should allow the same code in both ECL PS and the other language to be used in both interfaces On the ECL PS side the concept of peers is used to unify the remote and embedding interfaces Another feature of the remote interface is that on the ECL PS side the interface is independent of the programming language that is being interfaced to It should be possible to write ECL PS code with the interface e g for a GUI and change the remote code without needing to rewrite the code on the ECL PS side Briefly a socket connection is established between the remote program and an ECL PS pro cess The processes exchange messages in the EXDR see chapter 9 format according to the protocol This allows the communication to be platform independent and the ECL PS and remote processes can be located on any two machines which can establish socket connections 10 2 Basics The remote interface is established by attaching the remote and ECL PS processes The attachment establishes two socket connections between the two processes Control This connection is used to control the remote inte
44. L PS side the multitasking phase is started with the following predicate call peer_do_multitask demo The interact handler is defined thus proc multi_interact_handler type global return_code if return_code terminate disable_buttons return return_code 59 The code checks for the two cases where the user has requested to terminate the multitasking phase by pressing the end button and disables the buttons The end button itself invokes the following code to set return_code proc end_interaction global return_code set return_code terminate if ec_multi get_multi_status on ec_resume j The code checks if it is in a peer multitasking phase and if so return_code is set to terminate so that when the handler returns the multitasking phase will terminate Otherwise the peer has been explicitly handed control exclusively and so control is handed back to ECL PS in the normal way using ec resume The program also allows a peer to deregister from multitasking or if already deregistered to register again for multitasking This is handling by the following two procedures proc register for multi 1 ec multi peer register list start multi start handler reg configure command deregister for multi reg configure text Deregister multitasking proc deregister for multi 1 ec multi peer deregister reg configure command register for multi reg configure text Register multitask
45. PS 122 C 5 Operations on ECL PS Data Interfaces to some basic operations on ECL PS Data int ec compare const pword pw1 const pword pw2 Similar to the compare 3 built in predicate returns 0 if the arguments are identical a negative number if pwl is smaller than pw2 and a positive number if pw1 is greater than pw2 in the standard term ordering int ec schedule suspensions pword int Similar to the schedule suspensions 2 built in predicate Waking will only happen once control is returned to ECL PS and the wake 0 predicate is invoked Return code is PSUCCEED or an error code C 6 Initialising and Shutting Down the ECL PS Subsystem These are the functions needed to embed ECL PS into a C main program int ec set option int int int Set the value of a numerical option see appendix A int ec set option ptr int char Set the value of a string valued option see appendix A int ec init Initialise the ECL PS engine This is required before any other functions of this interface except option setting can be used int ec cleanup Shutdown the ECL PS engine C 7 Passing Control and Data to ECL PS from C These are the functions needed to embed ECL PS into C code void ec post goal const pword post a goal constraint that will be executed when ECL PS is resumed void ec post string const char same as ec post goal but the goal is given in ECL PS syntax in a string This should only be used
46. RE ec_set_option_ptr EC_OPTION_MAPFILE NULL The above options are set differently in ECL PS when it is a worker in a parallel system They should not be altered 111 112 Appendix B Summary of C Interface Functions Note that apart from the methods and functions described here all functions from the C interface which operate on simple types int long char can also be used from C code B 1 Constructing ECL PS terms in C B 1 1 Class EC atom and EC_functor The ECL PS dictionary provides unique identifiers for name arity pairs EC atoms are dictio nary identifiers with zero arity EC_functors are dictionary identifiers with non zero arity EC atom char looks up or enters the given string into the ECL PS dictionary and returns a unique atom identifier for it char EC atom name returns the name string of the given atom identifier EC functor char int looks up or enters the given string with arity into the ECL PS dictionary and returns a unique functor identifier for it char EC functor name returns the name string of the given functor identifier int EC functor arity returns the arity of the given functor identifier B 1 2 Class EC word The EC word is the basic type that all ECL PS data structures are built from because within ECL PS typing is dynamic The following are the functions for constructing ECL PS terms from the fundamental C types EC word const char conve
47. SHIO or PWAITIO ToC contains the associated stream number ec resume2 const pword FromC ec ref ToC Similar to ec resumel but it allows to pass an argument to the resumed execution This is only useful if the execution had yielded due to a yield 2 predicate call The term FromC is passed as input into the second argument of yield 2 ec resume long long ToC Similar to ec resumel but allows only integer values to be passed from ECL PS to C otherwise TYPE ERROR is returned This function is part of the simplified interface ec resume async Similar to ec resume but ECL PS is resumed in a separate thread in case this is sup ported by the operating system The return value is PSUCCED if the thread started successfully SYS ERROR if there was a problem creating the thread and PRUNNING if there was already an ECL PS thread running only one ECL PS thread is allowed to run at any time If threads are not supported the call does nothing and return PSUCCED Use ec resume status to wait for termination and to retrieve the results of the execution ec resume status This function is supposed to be called after a call to ec resume async It returns PRUN NING as long as the ECL PS thread is still running If the thread has stopped the return values are the same as for ec resume If threads are not supported the pair of ec resume async and ec resume status is equivalent to an ec resume ec resume status long long
48. TermImpl new CompoundTermImpl write new Atom output a term new CompoundTermImpl flush new Atom output Using this variant is a bit more cumbersome e g the creation of a new CompoundTermImpl for the conjunction of goals in the above example but it would be useful for large goals con structed dynamically There are also a number of convenience rpc methods where instead of providing a Compound Term you provide the objects from which the term is made See the API documentation for more details of these variants 67 Note yield 2 remote_yield 1 and rpc The builtins yield 2 and remote_yield 1 should not be executed anywhere within an rpc goal as they will cause the goal to return prematurely 8 4 2 Retrieving the results of an rpc goal execution The rpc method returns an object which implements CompoundTerm This object is the Java representation of the goal term with the solution substitution applied to its variables The solution substitution can be deconstructed using the returned CompoundTerm s arg method This method takes an integer the argument position and returns an Object which is the Java representation of the ECL PS argument at that position In the returned CompoundTerm instantiated variables are replaced with their instantiations Hence even if the variable was named in the initial goal its instantiation is identified in the returned goal by its position rather than its name Uninstanti
49. al interaction is expected From ECL PS side to the remote side yield this yields control to the remote side The message is used either to implicitly return control to the remote side at the end of an interaction initiated from the remote side or it is used to explicitly hand over control to the remote side ECLiPSe Remote ECLiPSe Remote i rpc goal via rpc ield answer via rpc ECLiPSe Remote ECLiPSe Remote rem_flushio Q data via Q rem flushio Q L L bytes via Q ield ield ECLiPSe Remote queue create N T D E socket client P N T D socket connect N S socket accept N Q queue close Q resume ield yield The interaction initiating messages from the remote side will be described in more detail in their own sections ec flushio Queue Length this message is sent when output on a remote synchronous queue is flushed on the ECL PS side 98 resume Queue is the ECL PS stream number for the peer queue and Length is the number of bytes that is being sent on the queue Control is yielded to the remote side The data on the queue Queue will be sent through the queue after sending this message on the control connection so on receiving this message on the remote side the remote side should read Length bytes from Queue After processing the data the remote side should return control to the ECL PS side via a resume message ec waitio Queue this message i
50. an embedded ECL PS where to find it support files The default setting is NULL which means that the location is taken from the registry entry or from the ECLIPSEDIR environment variable Stack Memory Allocation ec set option int EC OPTION LOCALSIZE 128 1024 1024 ec set option int EC OPTION GLOBALSIZE 128 1024 1024 The sizes in bytes of the stacks can be varied They will be rounded to system specific pa gesizes On machines where initially only virtual memory is reserved rather than allocating real memory WindowsNT 95 Solaris they default to very large sizes 128MB where real memory or space in the operating system swap file is taken immediately SunOS their default is very small 750KB 250KB Heap Memory Allocation ec set option int EC OPTION PRIVATESIZE 32 1024 1024 ec set option int EC OPTION SHAREDSIZE 64 1024 1024 The sizes in bytes of the private and shared heaps Normally these are ignored as the heaps grow as required They are used in the parallel ECL PS since there allocation is done at fixed addresses and in that case these sizes determine the maximum amount of memory per heap 109 Panic Function void my_panic char what char where ec_set_option_ptr EC_OPTION_PANIC my panic When ECL PS experiences an unrecoverable error this function is called By default a function that prints the panic message and exits is called After such an error one should not call any of the functions in th
51. and reenabled when control is transferred back to Tcl Note that there are two types of transfer of control from ECL PS to Tcl 1 when the control is implicitly yielded e g initiating I O from ECL PS 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 ECL PS With implicit yield the Tcl side is expected to eventually handed back control implicitly to ECL PS and not to explicitly hand control over to ECL PS 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 ECL PS when pressed which should only be enabled when ECL PS explicitly yielded to Tcl On the ECL PS 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 ECL PS 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 48 Tcl side ec_running checks if the ECL PS side has control Returns 1 if ECL PS side h
52. annot build such terms asynchronously while ECL PS is running for example this precludes building terms from within a signal handler unless it can make sure that ECL PS has yielded when it is running 3 1 3 Building atomic ECL PS terms It is possible to simply cast from a number of simple C types to build an EC word In addition functions exist for creating new variables and for the nil which terminates ECL PS lists In C you can just cast making simple terms in C EC word w EC atom hardback hardback EC word Swift EC word hardback EC word 1 002e 7 EC word 12345 EC word nilO EC word newvar 3 sz zm zzz ECLiPSe equivalent code Pi Swift P2 hardback P3 1 002e 7 P4 12345 P5 P6 3 1 4 Building ECL PS lists The list head tail function builds a list out of two terms Well formed lists have lists as their tail term and a nil at the end or a variable at the end for difference lists making the list 1 b 3 0 in C EC word w list 1 list b list 3 0 nilQ The following example shows how you can write functions to build variable length lists 10 function to build a list n n 1 n42 mn 1 m EC word fromto int n int m 1 EC word tail nil for int i m i gt n i tail list i tail return tail The list is constructed starting from the end so at all points during its construction yo
53. ants The facilities described here allows a Tcl peer to participate in peer multitasking so that different peers can apparently interact with ECL PS simultaneously This would for example allow GUI windows that are implemented using different peers for the same ECL PS process to be appear as if they can interact with the host eclipse side at the same time 7 2 Loading the interface The peer multitasking interface is provided as a Tcl package called eclipse peer multitask and must be loaded along with either the embedded eclipse or remote remote eclipse variant of the Tcl peer interface lappend auto path location of my eclipse lib tcl package require remote eclipse package require eclipse peer multitask 7 3 Overview A peer must already exist before it can participate in peer multitasking i e it has already been set up using ec init embedded or ec remote init remote Peer multitasking occur in a multitasking phase which is a special way for an ECL PS side to hand over control to the external side Effectively instead of handing over control to a single peer control is handed over repeatedly to all the peers that are participating in peer multitasking The control is shared between these peers in a round robin fashion giving rise to a form of co operative multitasking The multitasking is co operative in that each peer has to give up control so that the control can be passed to the next multitasking peer A peer multi
54. as control 0 otherwise If that is the case then the T cl 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 ECL PS Returns 1 if there is a connection to ECL PS i e it is attached 0 otherwise ec resume explicitly hand over control to ECL PS Tcl side must have control when this command is called i e ec running must be false This command returns when ECL PS 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 ECL PS start when control is handed back from ECL PS end when ECL PS explicitly yields control yield and when the Tcl side is disconnected by the ECL PS 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 ECL PS 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 ECL PS process This closes all the connections between the two sides T
55. 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 ini tialisations 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 ECL PS 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 ECL PS 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 ECL PS 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 ECL PS 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 ECL PS side has the control for example the GUI may have a button that sends an rpc goal to ECL PS when pressed Such a button could be disabled by the call back when control is transferred to ECL PS
56. at the socket client interaction is performed by the ECL PS built in peer queue create 5 this is the goal that ECL PS calls on receiving the queue create message If the initial creation of the socket server fails then the ECL PS side will not initiate a socket client interaction Instead it will simple yield control back to the remote side with a yield message In this case no peer queue is created queue close Queue this message is sent when the remote side closes the peer queue with id Queue 104 ECLiPSe Remote ueue_close yield The ECL PS side should close the ECL PS side of the peer queue Queue and remove all bookkeeping information associated with it Control should then be returned to ECL PS via a yield message The queue should also be closed on the remote side with the bookkeeping information removed too disconnect this message is sent if the remote side wish to initiate disconnection ECLiPSe Remote disconnect disconnect yield Control is handed over to the ECL PS side which will acknowledge with discon nect yield message Once the ECL PS side receives this message the remote attach ment between the two sides is considered terminated The remote side should now close all connections to the ECL PS side Concurrently the ECL PS side will also close down its end of the connections The disconnect message can be issued during an interaction In such cases the interaction will be t
57. ated variables in the returned Compound Term are represented using the Java null token If a variable in the rpc goal becomes instantiated to an ECL PS data type which does not have an equivalent EXDR type such as breal then in the returned Compound Term it will appear as the Java null token The following Java code is an example of how the returned Compound Term can be deconstructed to extract the variable substitutions CompoundTerm result eclipse rpc X Q Y is 2 1 7 The top level functor of the goal term is The first and second arguments of the goal term are the two subgoals and we can safely cast these as CompoundTerms CompoundTerm firstGoal CompoundTerm result arg 1 CompoundTerm secondGoal CompoundTerm result arg 2 X is the first argument of the first goal Object firstGoalFirstArg firstGoal arg 1 Y is the first argument of the second goal Object secondGoalFirstArg secondGoal arg 1 System out println X firstGoalFirstArg System out println Y secondGoalFirstArg The output will be X null Y 9 1 Other ways an rpc invocation can terminate Apart from succeeding and returning a CompoundTerm rpc can throw exceptions If the goal fails an instance of Fail is thrown So to test for failure you must catch this exception An instance of Throw is thrown if ECL PS itself throws an error 68 8 4 3 More details about rpc goal execution Variables As explain
58. atest version can be downloaded from Sun Microsystems Inc http www sun com 8 1 2 Make the com parctechnologies eclipse package available in your class path The Java ECL PS Interface consists mainly of a Java package which is used as a library by the Java programs you will write This package is included as a jar file located within the ECL PS distribution at eclipse dir lib eclipse jar You are free to copy eclipse jar to a more convenient location However to compile or run any Java programs which use the package you must include the full path of eclipse jar in your classpath For more information on using the classpath please consult your Java documentation 8 1 3 Compile and run QuickTest java To test that everything is working as it should be and to see a quick example of the Java ECL PS Interface at work try compiling and running the Java program QuickTest java This starts up an ECL PS from Java and tells it to write a message to stdout The program can be found at eclipse dir doc examples Javalnterface QuickTest java After compilation to run the program start the Java interpreter as you normally would but before the name of the class supply the command line option Declipse directory eclipse dir This tells Java where to find the ECL PS installation so it can run ECL PS You should use this command line options when running all other examples in this document When you run QuickTest java you
59. ava ECL PS interface by taking a closer look at how QuickTest java works In the other sections of the document you will learn how to write Java programs which can e Manipulate ECL PS terms and other data in Java Section 8 3 e Execute goals in ECL PS and use the results of this computation in Java Section 8 4 e Transfer data between Java and ECL PS using queues Section 8 5 e Initialise and terminate different kinds of connections between ECL PS and Java Section 8 6 Throughout this document eclipse dir stands for the root location of your ECL PS installation Detailed javadoc generated HTML descriptions of the API provided by the com parctechnologies eclipse package can be found at eclipse dir doc javadoc JavaEclipseInterface index html You may wish to browse the API documentation after reading this document to obtain more detailed descriptions of classes and interfaces in the package 8 1 Getting Started At the end of this section you will run the simple Java program QuickTest java which uses ECL PS First of all though you need to check that your Java SDK version is recent enough and that your classpath correctly set up 61 8 1 1 Check your Java SDK version Use of the Java ECL PS Interface requires an installation of the Java SDK Standard Devel oper s Kit version 1 2 2 or later If your Java SDK installation is an earlier version than this or you do not have the Java SDK on your machine the l
60. be loaded as follows lappend auto path location of my eclipse lib tcl package require remote eclipse An ECL PS program onto which the Tcl program will attach also needs to be started 6 3 Attaching and Initialising the Interface To use the interface the Tcl program needs to be attached to the ECL PS program The attach request is initiated on the ECL PS side by calling the predicate remote connect 3 from ECL PS The Tcl program is then attached to the ECL PS program by executing the procedure ec remote init from Tcl If no error occurs then the connection is established and the interface is set up In more detail the ECL PS predicate remote connect 3 establishes a socket listening for the connection from the Tcl side It prints out on the stream log output the hostname and the port number that the Tcl side should connect to The ECL PS side may be more complicated than a simple ECL PS as it can be an embedded ECL PS or the ECL PS process and other attached remote processes nstead of remote connect 3 the more flexible remote connect setup 3 and re mote connect accept 6 pair of predicates can be used See the reference manual entries for these predicates for more details 32 eclipse 1 remote connect Host Port Control _InitGoal Socket created at address chicken icparc ic ac uk 25909 On the Tcl side ec remote init is called with the hostname and port number given by re mote connect 3 ec
61. cate with other languages using a common data type However it is not necessary for the API user to know about EXDR in detail to use the Java ECL PS Interface features discussed in this section 71 EXDRInputStream is a subclass of java io DataInputStream which can read EXDR format EX DROutputStream is a subclass of java io FilterOutputStream which can write EXDR format Initialising EXDRInputStream and EXDROutputStream The constructor for EXDRInputStream takes an instance of java io InputStream as a parameter This parameter stream is the source of the EXDR data for the new stream If data has been written to the InputStream in EXDR format you can access it by invoking the readTerm method of the new EXDRInputStream This will read the data from the InputStream and translate the EXDR format into the Java representation of the data which is then returned by readTerm Similarly the constructor for EXDROutputStream takes an instance of java io OutputStream as a parameter This parameter stream is the destination of the data written to the new stream You write data by invoking the write method of the stream The parameter of this method is a Java object representing the piece of data to be written The class of this object can be any of the Java classes mentioned in Table 8 1 The object gets translated into EXDR format and this is written to the destination OutputStream EXDRInputStream and EXDROutputStream at work Although the underlyin
62. cation and resume should not be executed within the QueueListener methods dataAvailable or dataRequest The resume method and the remote_yield 1 builtin should only be used when other tech niques such as rpc are not suitable Termination of a RemoteEclipse connection A RemoteEclipse connection between ECL PS and Java may be terminated in different ways Firstly disconnection may be initiated by either side Secondly the disconnection may be either multilateral or unilateral Multilateral disconnection the preferred method is where the side which has control initiates disconnection Unilateral disconnection is where the side which initiates disconnection does not have control and should only take place as a clean up routine when one side is forced to terminate the connection because of an unexpected event Java initiated multilateral disconnect is performed by invoking the disconnect method on the RemoteEclipse instance while the Java side has control Java initiated unilateral disconnect is performed by invoking the unilateralDisconnect method on the RemoteEclipse instance while Java does not have control ECL PS initiated multilateral disconnect is performed on the ECL PS side by executing a remote disconnect 1 goal while ECL PS has control identifying the connection to be closed by supplying the peer name 8l ECL PS initiated unilateral disconnect cannot be executed by the user since ECL PS is not multi threaded Howev
63. ched from the ECL PS process This disconnection will terminate and clean up the links between the two processes Thus typically if the pro grammer wants to allow a particular application to be usable through both the Tcl remote and embedding interfaces the only code that needs to be specific to one or the other interface is the code associated with starting and termination of the application the attach and detach operations in the case of the remote interface The interaction between the Tcl and ECL PS is mediated by a version of thread like control flow of the embedded interface The interface distinguishes two sides the Tcl side which is the Tcl process and the ECL PS side which is generally the ECL PS process At any given time either the ECL PS side or the Tcl side has control When the Tcl side has control execution of the ECL PS process is suspended When the ECL PS side has control the Tcl side cannot initiate the execution of ec rpc goals The interface can implicitly transfer control from one side to the other e g when processing synchronous I O or it can be explicitly transferred An ECL PS process can have several attached remote processes Each remote process is iden tified by a control name which is the ECL PS name for a special control connection between the two sides 6 2 Loading the Interface Before using the interface the Tcl program must first load a Tcl package called remote eclipse which can
64. chieved by transferring control between ECL PS and Tcl in a coroutine like manner to ensure that data that is sent from one side is processed on the other These queues are designed to be compatible with the queues created via ec queue create of the embedded interface see section 5 4 Their actual implementations are different in that the queues in the embedded case are memory queues and the synchronous queue use socket connections The interface tries to minimise the difference by buffering where possible at either ends of the socket connection However there is an overhead for doing this and not all differences can be hidden This is discussed in more detail in section 6 9 asynchronous These are bi directional data can be sent both ways Sending or receiving data on these queues does not necessarily transfer control between ECL PS and Tcl In particular it is not possible to request data from the other side if the queue is empty such an operation would simply block This is because such queues map directly to the socket connections with no buffering and there is no concept of a socket being empty Generally it is up to the programmer to co ordinate the transfer and processing of the data They have no direct equivalent in the embedding Tcl interface but some uses of the embedding Tcl interface queues such as writing data from one side without a corresponding reader on the other side are better approximated by the asynchronous queue
65. 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 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 T his time is also us
66. control to the other side to allow handlers to handle the data see section 5 5 Strictly speaking flushing is not necessary in the embedding case to make the data available to the other side However it is needed in the remote case and for compatibility and good practice flushing is recommended 23 ec queue create eclipse stream name mode command event Creates a queue between Tcl and ECL PS On the Tcl side a Tcl channel is created On the ECL PS side the queue would be given the symbolic name eclipse stream name The mode argument indicates the direction of the queue and can either be fromec or toec The procedure returns a channel identifier for use in commands like puts read ec read exdr ec write exdr or close The optional arguments command and event specifies the data handler for the queue command is the name of the Tcl procedure for handling the data with its user defined arguments event is the name of the event that will be raised on the ECL PS side As a handler can only be defined for one side either event or command should be undefined 17 ec queue close eclipse stream name Closes the queue with the ECL PS name of ec stream name ec stream nr eclipse stream name This command returns the ECL PS stream number given a symbolic stream name this is the same operation that the ECL PS built in get stream 2 performs ec streamname to streamnum eclipse stream name This is an alias for ec stream nr fo
67. create debug traceline fromec handle trace line ec async queue create debug input toec no handlers During the initialisation of the development tools the Tcl code creates the from ECL PS queue where the trace line information is sent debug traceline and the asynchronous queue used only in a to ECL PS direction for sending the debugger commands to ECL PS creep leap skip etc Note that as this queue is used asynchronously there are no handlers associated with it On the ECL PS side when a goal with a spy point is executed this raises an event that calls the predicate trace line handler 2 which should output the trace line and wait for a debug command process the command and carry on trace line handler Current 4 Current contains information on the current execution state from this a trace line Traceline a string can be created make current traceline Current Traceline 4 send the traceline to Tcl side write exdr debug traceline Traceline flush debug traceline 4 flush will return when the Tcl handler has finished read exdr debug input Cmd 4 read the command from debug input and process it interpret command Cmd Current The trace line handler is called with the second argument set to a structure that contain in formation on the current execution state Current from this a trace line the debug port name depth goal being traced etc can be constructed Traceline is the string that should b
68. ction and its subinterface EclipseEngine are Java interfaces which contain the meth ods used when interacting with ECL PS Create an object which implements EclipseConnection or EclipseEngine There are a number of classes which implement these interfaces In the case of QuickTest java we use an instance of EmbeddedEclipse The initialisation of these implementing classes varies from class to class In the case of Embedded Eclipse initialisation is done by creating and config uring an EclipseEngineOptions object and using this in an invocation of the EmbeddedEclipse class static method getInstance Interact with ECL PS using methods in the EclipseConnection or EclipseEngine inter face We interact with the ECL PS engine by invoking methods on the object which implements EclipseConnection or EclipseEngine In the case of QuickTest java we invoke the rpc method which causes the ECL PS to execute a goal in this case one which simply prints a message 63 Terminate interaction with the ECL PS In order to clean up after the Java program has finished interacting with ECL PS the in teraction should be terminated Like initialisation how this termination is done varies among the classes which implement the EclipseConnection and EclipseEngine interfaces In the case of QuickTest java termination is done by invoking the destroy method on the EmbeddedEclipse object 8 3 Java representation of ECL PS data The Java ECL PS Interfac
69. ctionality in package eclipse which takes care of linking Tcl to ECL PS there is a package eclipse tools containing Tk interfaces to ECL PS facilities like debugging and development support This package should be used when developing Tcl Tk ECL PS applications To add these tools to your application load the package and add the tools menu to your application s menu bar Your code should then contain the following pattern package require eclipse package require eclipse tools menu mbar ec init ec tools init mbar tools See also the examples in the lib tcl directory of the ECL PS installation 5 3 Passing Goals and Control to ECL PS The control flow between Tcl and ECL PS is conceptually thread based An ECL PS goal is executed by using the ec rpc mechanism The goal is posted from Tcl and control is transferred automatically to ECL PS to allow the goal to be executed Control can also be explicitly transferred to ECL PS using ec resume Furthermore handler goals can be implicitly invoked on I O operations on queues this is described in more detail in section 5 4 with implicit transfer of control The related commands are the following ec rpc goal format Remote ECL PS predicate call It calls goal in the default module The goal should be simple in the sense that it can only succeed fail or throw It must not call yield 2 Any choicepoints the goal leaves will be discarded Unlike ec resume calls to ec rpc can be n
70. d and in fact can be run on separate machines The tkeclipse development environment is entirely implemented using the facilities described in this chapter The toplevel of tkeclipse is currently implemented using only the embedding interface but the development tools can be used with both the embedding and remote interfaces 5 1 Loading the interface The ECL PS interface is provided as a Tcl package called eclipse and can be loaded as follows lappend auto path location of my eclipse lib tcl package require eclipse 5 2 Initialising the ECL PS Subsystem These are the Tcl commands needed to initialize an embedded ECL PS ec set option option name option value Set the value of an initialisation option for ECL PS This must be done before invok ing ec init The available option names are localsize globalsize privatesize sharedsize default module eclipsedir io See Appendix A for their meaning 21 ec init peername Initialise the ECL PS engine This is required before any other commands of this interface except ec set option can be used The optional argument peername is the name of the embedding peer which defaults to master Example Tcl code for initialising ECL PS lappend auto path location of my eclipse lib tcl package require eclipse dec set option io 0 input output error via tty for testing ec set option io 2 input output error via queues default ec init Apart from the basic fun
71. d write status depends on from which side the queue is viewed a read queue in ECL PS is a write queue in Tcl 24 ECLiPSe write my_out_queue hello flush my out queue Tel set result read my_in_channel 5 The disadvantage of using these low level primitives is that for reading one must know exactly how many bytes to read It is therefore recommended to use the EXDR ECL PS external data representation see section 5 7 format for communication This allows to send and receive structured and typed data The primitives to do that are write exdr 2 on the ECL PS side and ec read exdr section 5 7 on the Tcl side ECLiPSe write exdr my out queue foo bar 3 flush my out queue Tcl set result ec read exdr my in channel In the example the Tcl result will be the list foo bar 3 For details about the mapping see section 5 7 5 4 2 To ECL PS from Tcl To create a queue from Tcl to ECL PS to Tcl use ec queue create with the mode argument set to toec e g Tcl set my_out_channel ec_queue_create my_in_queue toec Now the queue can be used e g by writing into it with Tcl s puts command and by reading using ECL PS s read_string 4 builtin Tcl puts my_out_channel hello ec_flush ec_streamname_to_streamnum my_in_queue 5 ECLiPSe read string my in queue 5 Result The disadvantage of using these low level primitives is that for reading one must know exactly how many bytes to read or define a del
72. defined Tcl data producer handler is provided ec_stream_input_popup abel text stream_nr Pops up a window displaying the label_text an input field and an ok button The text typed into the input field will be written into the specified queue stream stream_nr which is the ECL PS stream number for the queue If this command is invoked as a handler for a to ECL PS queue stream_nr will be automatically appended by the interface There should be no unflushed data already on the queue when this command is invoked An example to ECL PS queue with Tcl handler To create the queue on the Tcl side with a Tcl handler Tcl code ec_queue_create myqueue toec ec_stream_input_popup Input for myqueue This associates the pre defined Tcl data producer handler ec_input_popup with myqueue The last specifies that there is no ECL PS handler and can be omitted as that is the default This queue can now be used on the ECL PS side in a demand driven way i e ECL PS side can read from the queue ECLiPSe code read myqueue Data When the ECL PS side reads from myqueue and the queue contains no data on the ECL PS side then control will be handed over to T cl and ec input popup invoked This pops up a Tcl window with the label Input for myqueue with a text entry widget asking the user to supply the requested data The data is then sent back to the ECL PS side Here is a slightly simplified version there are no buttons of ec
73. destroy ec refs destroy the ECL PS references It is important that this is done otherwise the ECL PS garbage collector will not be able to free the references data structures which may even tually lead to memory overflow void ec refs set ec refs int i const pword pw set the ith reference to the ECL PS term pw This setting is subject to the ECL PS engine s undo mechanism on backtracking pword ec refs get const ec refs int i return the ECL PS term referred to by the i th reference int ec refs size const ec refs return the capacity of the ec refs data structure ec ref ec ref create pword like ec refs create for a single reference ec ref ec ref create newvar analogous to ec refs create newvars void ec ref destroy ec ref analogous to ec refs destroy void ec ref set ec ref const pword analogous to ec refs set pword ec ref get const ec ref analogous to ec refs get C 4 Passing Data to and from External Predicates in C These two functions are only meaningful inside C functions that have been called from ECL PS as external predicates pword ec arg int i If inside a C function called from ECL PS this returns the i th argument of the call int ec unify pword pword Unify the two given pwords Note that if attributed variables are involved in the unifi cation the associated unification handlers as well as subsequent waking will only happen once control is returned to ECL
74. ding BU L PSU TOMUS cm rto asd decet Taser ap no eo udo seria xs 10 3 1 3 Building atomic ECL PS terms sc xugteaiex exon ROR ee ae eR 10 3 1 4 Building BOE Par lots we s wth cute Autre A DUCES SES 10 3 1 5 Building ECL PS structures os ek eere e oe Bea Y Bees 11 3 2 Converting ECL PS data to C data x eva arse ree eee ttd 11 3 2 1 Converting simple ECL PS terms to C datatypes 11 3 2 2 Decomposing ECL PS terms 55 iu EG e Ro ex EG 12 3 3 Referring to ECL PS terms aet vor neg I EP SUE ud a REM NE 12 3 4 Passing generic C or C data to ECL PSe cen 13 3 4 1 Wrapping and unwrapping external data in an ECL PSe term 13 9 42 Fhe method table uer ERREUR Lue RUE eA uos 13 4 External Predicates in C and C 17 4 1 Coding External Predicates aoao aaa ee ee 17 4 2 Compiling and loading 4 2 s oz omo R eee eee ae 18 4 8 Restrictions and Recommendations 0 0 000000 2 eee 19 5 Embedding into Tcl Tk 5 1 Loading the interface 2 2 lll less 5 2 Initialising the ECL PS Subsystem 0 00002 eee eee 5 3 Passing Goals and Control to HUM PSs Dos nee uos x Vee EE AC 5 4 Communication via Queues a s SX Brom BOR PS to Tel 9 actabeate eco cow faf x Pos aei e dedi a DO UDIECIZPSC from Tel oe cecce do ome Rees UD RN EE 5 5 Attaching Handlers to Queues a a a a een beoe Pelt handlersz c dog unus ir seeing dp etium es Sus ms hoo EOL PS Bat
75. dling for more information The event name is given as a string This function is part of the simplified interface C 8 Communication via ECL PS Streams These functions allow exchanging data with an embedded ECL PS via queue streams created by the ECL PS code Queue streams can be created either by using open 3 and open 4 from within ECL PS code or by initializing ECL PS with the MEMORY IO option In the latter case the streams 0 1 and 2 are queues corresponding to ECL PS s input output and error streams int ec queue write int stream char data int size Write string data into the specified ECL PS queue stream Data points to the data and size is the number of bytes to write The return value is 0 for success or a negative error number int ec queue read int stream char buf int size Read string data into the specified ECL PS queue stream Buf points to a data buffer and size is the buffer size The return value is either a negative error code or the number of bytes read into buffer int ec queue avail int stream Determines the number of bytes that are available and can be read from the given queue stream The return value is either that number or a negative error code int ec stream nr char name Get the stream number of the named stream If the return value is negative then there is no open stream with the specified name This is the same operation that the ECL PS built in get stream 2 performs C 9 Miscellaneou
76. e data on Window the text window specified by the programmer 6 6 4 Reusable Queue Names ECL PS stream names are global in scope so using fixed queues names like myqueue might cause name conflicts with other modules if the programmer intend the remote Tcl code to be usable with other ECL PS code One way to avoid name clashes is to dynamically composing queue names using the name of the control connection Tcl code append queue name ec control name myqueue ec queue create queue name fromec ec stream output popup red textwin 46 The user specified name myqueue is appended to the control name of the remote connection to give a unique queue name On the ECL PS side the code will also need to use the dynamic name local variable remote control 4 code fragment to remember the control name remote connect Addr Control setval remote control Control 4 code fragment to use the queue getval remote control Control concat atom Control myqueue QName write QName hello flush QName 6 6 5 Translating the Queue Names The remote queues connecting ECL PS and Tcl are given different names on the two sides The remote Tcl interface keeps track of the ECL PS names for the queues on the Tcl side On the ECL PS side the queue has a stream number as well as possibly several symbolic aliases The interface only keeps track of one symbolic name the one that is supplied in ec queue connect and ec
77. e printed e g 1 1 CALL append 1 2 3 O L This is sent as an EXDR term to the Tcl side using the synchronous queue debug traceline When flush 1 is called control is handed over to the Tcl to handle the data and the Tcl data consumer handler handle trace line is invoked proc handle trace line stream length global tkecl ec tracer trace text insert end 44 ec_read_exdr ec_streamnum_to_channel stream configure_tracer_buttons active wait for a tracer command button to be pressed tkwait variable tkecl tracercommand configure tracer buttons disabled ec write exdr ec streamname to channel debug input tkecl tracercommand flush ec streamname to channel debug input As this is invoked as a handler the ECL PS stream number stream and number of bytes sent length are appended as arguments Note that as the trace line is written as an EXDR term the length information is actually not needed What the handler does is simply read the trace line as an EXDR term and placing the resulting string onto the tracer text window ec_tracer_trace text Next configure_tracer_buttons active is called This code is not shown but what it does is to enable the buttons for the debugger commands so that the user can press them There are buttons for the debugger commands such as leap creep etc When one of this button is pressed the global variable tkecl tracercommand is set to the corresponding comma
78. e remote side The user can specify the amount of time to wait before this operation times out which would then terminate the attachment 2 Remote side create a client socket stream for the control connection with an address compatible with Host Port The socket stream should be in blocking mode and perform no translation on the data sent 3 Remote side sends the remote protocol version information on the control socket in EXDR format and flush it This should be a remote protocol 1 term 91 4 ECL PS side reads the EXDR version term from the control socket and compares with the version on the ECL PS side If the two protocols are compatible it sends the EXDR string yes back to the remote side otherwise it sends the ECL PS remote protocol version to the remote side and disconnects from the remote side raising unimplemented function ality error The ECL PS side waits at most 100 seconds after the control connection is established for the remote side s version after this the ECL PS side disconnects the control connection and raises out of range error 5 It is expected that the future versions of the protocol will remain unchanged up to this point at least to ensure the proper handshaking and checking of versions 6 Remote side write the pass term in EXDR format on the newly created control connec tion and flush it This provides a simple security check ECL PS side will check if the pass term matches the
79. e rpc message the remote side should then send the ec rpc goal in EXDR format on the rpc connection When the execution of the ec rpc goal is finished the ECL PS side will yield control back to the remote side with a yield message followed by the result of the ec rpc execution on the rpc connection in EXDR format the goal with its bindings if the execution succeeded fail if the goal failed throw if an exception is generated rem flushio Queue this message is sent if the remote side wish to transfer data to the ECL PS side on peer queue with queue id Queue and the remote side does not know how many bytes will be sent with the operation After sending the message control is transferred over to the ECL PS side and the data is sent on the socket stream On the ECL PS side if the queue is a synchronous queue then the data sent must be a single EXDR term because otherwise the ECL PS side would not know when the data transfer is complete The ECL PS side would read the data from the socket stream as a single EXDR term which is then written onto the buffer If an event handler has been associated with the peer queue this will now be invoked to consume the data from the buffer If not for example if the rem flushio was initiated by an ec waitio message then the data is left on the buffer to be processed later The rem flushio message can also be used to sending data to ECL PS for asynchronous queues as well
80. e uses a set of conventions and Java classes so that data types common in ECL PS can be represented Representing ECL PS data types is useful for e Constructing compound goals to be sent to ECL PS for execution e Deconstructing the results of ECL PS s computation which are returned as a compound goal e Communicating compound terms and other data via queues More details on these tasks will be provided in Sections 8 4 and 8 5 but it is first necessary to understand how ECL PS data is represented in Java 8 3 1 General correspondence between ECL PS and Java data types Not all ECL PS data types are represented for example at present the ECL PS type rational has no Java equivalent However all the most useful ECL PS types have a corresponding Java class Table 8 1 gives the general correspondence between those ECL PS data types which are supported and the Java classes or interfaces which are used to represent them The ECL PS types Java classes which appear in the table are those which map to or from the ECL PS external data representation EXDR definition ECL PS data type Java class interface atom Atom compound CompoundTerm integer java lang Integer java lang Long list java util Collection float java lang Double java lang Float string java lang String variable null Table 8 1 The correspondence between ECL PS and Java data types The Java classes are within the com parct
81. e which called the remote connect 3 goal or the remote connect accept 6 goal blocks until the Java side explicitly transfers control to ECL PS or disconnects Explicit transfer of control between ECL PS and Java As mentioned above after the initial connection has been established Java has control by default However this may not be convenient For example in the case of search visualisation after the initialisation of the visualisation client we may prefer ECL PS to have control by default allowing control to pass to Java only on certain occasions Control can be explicitly passed from Java to ECL PS by invoking the resume 0 method on a RemoteEclipse In this case the ECL PS code will resume execution after the last point where it passed control to Java For example if resume is invoked immediately after the RemoteEclipse constructor completes ECL PS execution will resume at the point just after the call to the remote connect 3 goal or the remote connect accept 6 goal Control can be transferred to a Java peer using the remote yield 1 builtin In this case the Java thread which passed execution to ECL PS will resume execution at the point where it blocked The resume method and the remote yield 1 builtin should be used with care An invo cation of resume should be paired with an execution of a remote yield 1 goal in most cases In addition remote yield 1 should not be executed in any code executed as a result of an rpc invo
82. e 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 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 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 4 Name Closes the peer queue Name from ECL PS 108 Appendix A Parameters for Initialising an ECL PS engine It is possible to parametrise the initialisation of the ECL PS engine by calling the functions ec_set_option_int and ec_set_option_ptr This must be done before initialisation Installation directory ec set option ptr EC OPTION ECLIPSEDIR usr tom eclipse This can be used to tell
83. eQueue or ToEclipseQueue on which the flush or read happened Note that this invocation occurs only if the ECL PS side of the queue is empty If you have written data to the queue on the Java side but not flushed it the ECL PS side may still be empty in which case the dataRequest method of the listener will be invoked 73 There is an example Java program QueueExample2 java with an accompanying example ECL PS program queue example 2 pl which use QueueListeners attached to queues going in both directions eclipse dir doc examples JavaInterface QueueExample2 java eclipse dir doc examples Javalnterface queue example 2 pl After the queues streams are set up on both sides the Java program attaches as listeners a TermProducer to the ToEclipseQueue and a TermConsumer to the FromEclipseQueue These are both locally defined classes which implement QueueListener The TermProducer each time its dataRequest method is invoked sends one of five different atoms down its queue in EXDR format The TermConsumer when its dataAvailable method is invoked reads some EXDR data from its queue and translates it into the appropriate Java object It then writes this object out to stdout Next the Java program using rpc executes the only predicate in the ECL PS program read 5 write 5 0 This repeats the following operation five times read in a term in EXDR format from the relevant incoming stream write it out in EXDR format with an extra fu
84. ead exdr ec tcl2exdr ec exdr2tcl are available 6 5 Executing an ECL PS Goal From Tcl An ECL PS predicate can be invoked from the Tcl side using the remote ECL PS predicate call ec rpc facility This should be the main method of interacting and communicating with ECL PS in the remote interface Information can be sent to ECL PS via bindings for input arguments when the call is made and results returned from ECL PS via the bindings made to output arguments ec rpc goal format Remote ECL PS predicate call It calls goal in the default module The goal should be simple in the sense that it can only succeed fail or throw Any choice points the goal leaves will be discarded Calls to ec rpc can be nested and can be used from within Tcl queue event handlers However an ec rpc cannot be issued while ECL PS side has control If no format argument is given the goal is assumed to be in ECL PS syntax If a format argument is provided the ECL PS goal is constructed from goal and format according to the conversion rules explained in section 5 7 On success ec rpc returns the possibly more instantiated goal as a Tcl data structure in EXDR format otherwise fail or throw respectively 6 6 Communication via Queues Queues should be used to set up long term I O links between ECL PS and Tcl An example would be the main output from an application that is to be displayed by a Tcl window Streams 34 of bytes can be s
85. ec flush should be used both inside the T cl data provider handler and also to invoke an ECL PS data consumer handler see the next section ec flush eclipse streamnum nbytes If the Tcl side has control flushes the synchronous or asynchronous queue with the ECL PS stream number eclipse streamnum and hands over control briefly to ECL PS to read the data Control is then returned to Tcl nbyte is an optional argument that specifies the number of bytes being sent If this argument is missing the data sent must be a single EXDR term in the case of the synchronous queue There is no restriction for the asynchronous queues but it is the programmer s responsibility that the read operation does not block Normally data is written to the queue using standard Tcl output commands and the amount of data written is not known However the programmer may have kept track of the number of bytes written inside the handler and thus know how many bytes will be sent In this case ec flush can be called with the number of bytes supplied as a parameter It is the programmer s responsibility to ensure that this information is accurate Without nbytes the output is restricted to EXDR terms for synchronous queues The reason for this is because the data is sent through a socket connection and without knowing the amount of data it is not possible in general to know when the data ends unless the data sent has implicit boundaries like an EXDR term For the
86. echnologies eclipse package unless otherwise specified The general rule is that you can send data to ECL PS by passing the relevant method an instance of the Java class corresponding to the ECL PS data type you want on the ECL PS 64 side When data comes back from ECL PS it will be an instance of java lang Object but this can be cast to the relevant Java class which must either be known beforehand or determined e g using the getClass method There are also a number of peculiarities for certain cases which we now explain 8 8 2 Atoms and compound terms Atoms are simple these are constructed in Java using the constructor of the Atom class the string parameter of the constructor becomes the atom symbol Although the Java interface CompoundTerm is listed above compound terms except lists are usually constructed using the CompoundTermImpl class which implements CompoundTerm Incidentally Atom also imple ments Compound Term even though strictly speaking ECL PS atoms are not compound Here is an example of Compound TermImpl at work Construct a term in Java to represent the Eclipse term foo a b 3 private static CompoundTerm construct term Atom a new Atom a Atom b new Atom b Integer numberThree new Integer 3 CompoundTerm theTerm new CompoundTermImpl foo a b numberThree return theTerm This method is taken from the example Java program DataExample1 java which can be found in the exam
87. ed 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 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 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 107 remote_yield Peer Explicitly yield control to the remote side Peer Execution on ECL PS side will be suspended until the remote side returns control to ECL PS side The predicate will succeed when remote side returns control The predicat
88. ed in Section 8 3 6 ECL PS variables are always represented by the null token when rpc is invoked with a Compound Term parameter When used in an rpc goal each null token represents a different variable Using Compound Term you cannot represent a goal with multiple occurrences of a single variable So for example the following Java code will output q b b for the first rpc invocation and q a b for the second eclipse rpc assert q a b eclipse rpc assert q b b System out println eclipse rpc q X X System out println eclipse rpc new CompoundTermImpl q null nu11 Nondeterminism The rpc feature does not support the handling of nondeterminism in the execution of the ECL PS goal If the goal succeeds control is returned to Java immediately after the first solution to the goal is found in ECL PS All choice points thereafter are ignored So for ex ample although the first ECL PS goal below would leave choice points it would be equal in effect to the second result eclipse rpc member X 1 2 3 4 5 result eclipse rpc member X 1 This is not a practical problem It merely implies that if you are using nondeterminism to generate multiple solutions you should collect these on the ECL PS side using a meta level built in predicate such as findall 3 and then return the result to Java Concurrent invocations of rpc Note that the rpc method is synchronized Therefore if while one Java t
89. ed to send data read remote data Event rem flushio Queue Len read string Queue Len Data process Data The ECL PS code defines read remote data 2 as the handler for to ECL PS data sent with ec flush on the Tcl side This handler is called when control is handed over to ECL PS side to read the data Both the two optional arguments are used in this handler The second argument supplies the ECL PS stream number for the queue and the length of data written As the data is sent by explicitly calling ec stream input popup the length of the data sent is known so read string 4 can be used to read the exact amount of data In the asynchronous queue it is generally the programmer s responsibility to ensure that the read will not block Using the queue asynchronously from ECL PS The example ec async queue create also defines a Tcl data consumer handler to handle data sent on the from ECL PS direction with a user defined argument of the text window that the data will be sent to Here is a simple procedure which reads the data on the queue and places it on the text window specified Tcl code proc data to window Window Stream 1 set channel ec streamnum to channel Stream Window insert end read channel The Stream argument is appended by the interface when the handler is invoked and is the ECL PS stream number of the queue The procedure simply reads the data from the cor responding Tcl channel and display th
90. een an EC ref and a EC word One point to take care of is that assigning such a variable is not like unification since assignment cannot fail It just overwrites the old value Assignment is very similar to the setarg 3 built in in the ECL PS language 3 4 Passing generic C or C data to ECL PS It is possible to include any C or C data in an ECL PS term To do this it is wrapped into a handle to tell ECL PS that this is external data You also have to supply a method table which is a set of functions that are called when ECL PS wants to make common operations that it assumes can be done on any data eg comparing printing 3 4 4 Wrapping and unwrapping external data in an ECL PS term To create an ECL PS wrapper for a C C object the function handle is used It takes a pointer to any C or C data and a pointer to a suitable method table t ext type structure and creates an ECL PS handle term which refers to them Method tables for the common case of arrays of char long or double are predefined For example a handle for a double array is made like this double my array 5 1 1 2 2 3 3 4 4 5 5 EC word w handle amp ec xt double arr my array where ec xt double arr is a predefined method table for arrays of doubles To convert back from an ECL PS term is handle is used The method table passed in indicates the sort of data you expect to get If the ECL PS handle contains the wrong sort the function
91. ene 8 5 2 Writing and reading ECL PS terms on queues 8 5 3 Using the QueueListenerinterface 2r 8 5 4 Access to ECL PS s standard streams lll Managing connections to ECL PS oen 8 6 1 A unified ECL PS side interface to Java the peer concept 8 6 2 Creating and managing ECL PS engines from Java 8 6 3 Connecting to an existing ECL PS engine using RemoteEclipse 8 6 4 Comparison of different Java ECL PS connection techniques EXDR Data Interchange Format EGL PS primitives to read write EXDR terms 2s s Serialized representation of EXDR terms aoaaa 10 The Remote Interface Protocol 10 1 10 2 10 3 10 4 10 5 10 6 Introduction x Rose Ie Ve PEU SEU aes diete as bL mL PT v EU Attachment 200 0 4 ms esse scH Usos RE RR eh Gaus P SS NE RUD 10 3 1 An example n amp e m Rogo mk mo womum RO 9 ee Gods Sa ae Remote Peer Queues ls 10 4 1 Synchronous peer queues 2h 10 4 2 Asynchronous peer queues ooo Control Messages uec dean bet pd eden etaed RE el a ee a a 10 5 1 The disconnection protocol 2e Support for the Remote Interface 2 2 Parameters for Initialising an ECL PS engine B Summary of C Interface Functions B 1 B 2 B 3 B 4 Constructing BOL PS terms in CH4 fcc sk S22 dard ee eet Ss B 1 1 Class EC_atom and EC functor 0 0 0 0 002 eee eee B 1 2 Clas EC_word
92. ent along the queue from one side to the other on one side data is written to the queue and when the queue is flushed the data is sent to the other side which can now read the data The data can either be sent as normal strings where each byte represents a character using the normal I O calls or they can be in EXDR format in which case both sides need to read and write using EXDR On the Tcl side the queue is seen as a Tcl I O channel On the ECL PS side a queue is seen as an ECL PS I O stream which has a unique numeric ID the stream number and has a user supplied symbolic name These all refer to the same queue Queues are created using the symbolic names and the Tcl side maintains tables of the correspondence between Tcl channel names symbolic names and stream numbers The built in Tcl I O commands accepts the Tcl channel name for operating on the queue and for compatibility with the embedding interface many of the Tcl remote interface commands refer to the queue using the stream number The interface provides commands to inter convert the various names so that the right name can be used for a particular command There are two types of queues synchronous These queues are unidirectional i e either for sending data from ECL PS to Tcl from ECL PS or from Tcl to ECL PS to ECL PS These streams are synchronous because the interface ensures that the sending and receiving of data across the queue are synchronised This is a
93. er The buffer is needed to ensure that when data is transferred between the two sides the I O operation is synchronised the data is being read on one end of the socket while it is being written at the other so no blocking will occur When a side needs to initiate an I O operation with the other side either to write data to or read data from the other side via the socket stream it must have control otherwise it would not be in a position to initiate an action Before performing the I O operation a control message is sent to the 96 other side to allow it to prepare to read the data before the I O operation is actually initiated The memory queue thus serves to buffer the data before it is transferred to the socket stream The socket stream must be connected to the remote side before it could be used Control messages are used also to synchronise the connection of the socket The protocol does not specify if a buffer is needed on the remote side this depends on the facilities available in the language used for the remote side For a particular synchronous queue a data handler can only be defined on one side of the queue but not both 10 4 2 Asynchronous peer queues I O operations on these queues do not need to be controlled by the remote protocol but their creation and closing is controlled by the remote protocol so that the remote interface can keep track of these queues These are implemented as raw socket streams on the ECL PS side
94. er it may occur in certain urgent situations e g if the ECL PS process is killed while ECL PS does not have control If an ECL PS initiated disconnect occurs or the connection is lost for whatever reason while ECL PS has control the Java thread which handed control to ECL PS should throw an EclipseTerminated Exception If either of these happens while Java has control the next invoca tion of a method on the RemoteEclipse should throw an EclipseTerminatedException although it is possible that some operations will throw a different class of IOException If this should happen it is worth invoking the unilateralDisconnect method to do a final clean up 8 6 4 Comparison of different Java ECL PS connection techniques This section should give you some idea of when it is most appropriate to use each connection class Figure 8 4 is UML class diagram showing the most important relationships and operations of the principal classes and interfaces All three classes implement EclipseConnection which provides all the functionality you would expect during a session with ECL PS The EclipseEngine interface is implemented when the JVM owns the ECL PS engine and so provides the methods to access the standard I O streams Note that the termination methods are not in either of the interfaces but are specific to each class Furthermore the resume method allows RemoteEclipse to explicitly hand control to ECL PS but this operation
95. er under some circumstances a side may be forced to disconnect when it does not have control For example in the Tcl remote interface the root window for the Tcl process may be destroyed by the user In such cases a unilateral disconnect will be performed by that side only the second part of the normal disconnect protocol is performed by sending the disconnect acknowledge message disconnect resume or disconnect yield without being initiated by a disconnect message The ECL PS side checks the control connection for any unexpected incoming messages before it sends an outgoing control message If there is a disconnect resume message the ECL PS side will perform the disconnection on its side When the user exits normally from an ECL PS session ECL PS will disconnect from all remote attachments This is done in sepia end 0 event handler As part of the disconnection process on the ECL PS side a user definable event will be raised in ECL PS just before the remote queues are closed This allows the user to define application specific handlers for dealing with the disconnection of the remote interface on the ECL PS side A similar handler should probably be provided on the remote side The event raised has the same name as the control stream The event handler for this event is initially defined to be true 0 i e a no op when the remote connection is set up The handler can then be redefined by the user e g during the user defined i
96. erefore suitable to be used in situations where no complex types can be passed e g when interfacing to scripting languages C 1 Constructing ECL PS terms in C All these functions return volatile pwords which can be used as input to other constructor functions or which can be stored in non volatile ec_refs pword ec string const char converts a C string to an ECL PS string The string is copied pword ec length string int const char converts a C string of given length to an ECL PS string The string is copied and can contain NUL bytes pword ec atom const dident creates an ECL PS atom A dident dictionary identifier can be obtained either via ec did or ec get atom pword ec long const long converts a C long to an ECL PS integer pword ec double const double converts a C double to an ECL PS float pword ec term dident pword pword creates an ECL PS term from the given components pword ec term array const dident const pword creates an ECL PS term from the arguments given in the array pword ec list const pword const pword creates a single ECL PS list cell with the given head car and tail cdr pword ec listofrefs ec refs creates an ECL PS list containing the elements of the ec refs array 119 pword ec_listoflong int const long creates an ECL PS list of integers containing the longs in the given array The data is copied pword ec_listofchar int const char create
97. erences because the queues are in memory queues in the embedded interface but are socket channels in the remote interface T his leads to the following differences e Data will not appear on the other side until the queue is flushed on the side that is generating the output To make code compatible output queues should be always flushed e In general reading data via a blocking socket requires the size of the data to be explicitly specified except when I O is done via the EXDR primitives where size is implicitly specified Only EXDR format is supported when data is sent from Tcl to ECL PS That is a write handler for a Tcl write channel must write the data in EXDR format For output from the ECL PS side the Tcl read handler would be supplied with the length of the output when it is invoked and this information must be used if the Tcl read is not done via an EXDR primitive However in general it is strongly suggested that only EXDR formatted data should be sent via the queues in both direction e An I O operation on the stream may block if there is no handler to consume produce the data on the other side If a handler is specified via the command argument then a corresponding handler in the Tcl side will be invoked at the correct place when the ECL PS side produces output or request input e The channel identifier is not of the form ec queueX To make code portable the name of the channel should be obtained from the ECL PS stream symbo
98. erminated early along with the attachment disconnect resume this message is sent in acknowledgement of a disconnection initiated from the ECL PS side ECLiPSe Remote disconnect disconnect resume After sending this message the remote attachment between the two sides is considered terminated The remote side should now close all connections to the ECL PS side Con currently the ECL PS side will also close down its end of the connections In addition this message should be sent if the remote side has to terminate the attachment while the ECL PS side has control This can happen if the remote process is forced to quit This is the only case where a message can be sent via the control connection on the remote side while it does not have control Once the message is sent the remote side can terminate its connection unilaterally 105 10 5 1 The disconnection protocol Under normal circumstances the disconnection of the two sides is initiated by the side that has control by sending a disconnect message to the other side The other side acknowledges this by responding with a disconnect yield ECL PS side or disconnect resume remote side The acknowledgement should be sent when that side is ready to disconnect Once the messages have been exchanged both sides should be ready and can physically disconnect The exchange of messages should ensure that any asynchronous I O between the two sides are properly ter minated Howev
99. es directory eclipse dir doc examples JavalInterface 65 Construct a collection in Java to represent the Eclipse list 1 foo 3 5 bar private static Collection construct_collection Collection theCollection new LinkedList theCollection add new Integer 1 theCollection add new CompoundTermImpl foo new Double 3 5 theCollection add new Atom bar return theCollection If you study compile and run DataExample2 java you will see that the collection is indeed translated into the required ECL PS list You will also see that order is maintained in the sense that the order of elements as they appear in the ECL PS list will equal the collection s iterator order the converse is true if the data is coming from ECL PS to Java Also note that the ECL PS empty list is represented in Java by the constant java util Collections EMPTY LIST 8 3 4 Floats and Doubles The ECL PS data type float is always converted to java lang Double in Java However ECL PS can be sent an instance of java lang Double or java lang Float both will be converted to float in ECL PS One value of java lang Double and java lang Float has no counterpart in ECL PS the not a number NaN value Infinite values can be sent in either direction 8 3 5 Integers ECL PS can be sent instances of either java lang Integer 32 bit integers or java lang Long 64 bit integers Both of these will be translated to type integer on
100. ested and can be used from within Tcl queue event handlers 22 If no format argument is given the goal is assumed to be in ECL PS syntax If a format argument is provided the ECL PS goal is constructed from goal and format according to the conversion rules explained in section 5 7 On success ec rpc returns the possibly more instantiated goal as a Tcl data structure otherwise fail or throw respectively This is the recommended way of executing ECL PS code from Tcl and passing the results back via output arguments to Tcl ec running checks whether an asynchronous ECL PS thread is still running If that is the case the only interface function that can be invoked reliably is ec post event ec resume async resume execution of the ECL PS engine All posted events and goals will be executed The return value will be success if the posted goals succeed fail if the goals fail and yield if control was transferred because of a yield 2 predicate call in the ECL PS code No parameters can be passed If the async parameter is 1 default 0 the ECL PS execution is resumed in a separate thread provided this is supported by the operating system The effect of this is that Tcl Tk events can still be handled while ECL PS is running so the GUI does not freeze during computation However only one ECL PS thread can be running at any time so before doing another call to ec resume ec handle events or ec rpc one should u
101. eturned Other unexpected types yield a TYPE ERROR Special cases are explained below int ec get string const pword char checks whether the ECL PS pword is a string or atom and converts it to a C string This string is volatile ie it should be copied when it is required to survive resuming of ECL PS 120 int int int int int int int int int int int ec_get_string length const pword char long the same as ec_get_string but returns also the string s length Note that ECL PS strings may contain null characters ec_get_atom const pword dident checks whether the ECL PS pword is an atom and if so return its dictionary identifier ec_get_long const pword long checks whether the ECL PS pword is a word sized integer and if so returns it as a C long ec get double const pword double checks whether the ECL PS pword is a floating point number and if so returns it as an C double ec get nil const pword checks whether the ECL PS pword is nil the empty list ec get list const pword pword pword checks whether the ECL PS pword is a list and if so returns its head and tail If it is nil the return code is PFAIL ec get functor pword dident checks whether the ECL PS pword is a structure and if so returns the functor ec get arg const int n pword pword checks whether the ECL PS pword is a structure and if so returns the n th argument The return code is RANG
102. g it to be generated dynamically 2 The port number must be communicated to the Java side somehow e g manually or via a file 3 The Java side then invokes one of the RemoteEclipse constructors with a password param eter This either blocks until the connection is successful or throws an exception 4 The ECL PS side executes the builtin remote connect accept 6 specifying the pass word which the Java should supply 5 The Java constructor invocation then completes or throws an exception if the connection could not be made If left as a free variable the Host argument of either the remote connect 3 or re mote connect setup 3 goal will become instantiated to the IP address of the machine hosting ECL PS Another possibility is to call the goal with this argument already instantiated to the atom localhost This will mean that only client connections made by processes on the same machine and using the loopback address will be accepted With this usage on the Java side you should use invoke InetAddress getHostByName localhost Note that InetAd dress getLocalHost will not work in this situation 80 In both connection sequences the peer name indexing the connection is either specified or gener ated dynamically on the ECL PS side in the remote_connect 3 or remote connect setup 3 goal Once the connection has been established by one of the above sequences control initially rests with the Java side Therefore the ECL PS cod
103. g stream could be any kind of stream e g a file stream the most common use of EXDRInputStream and EX DROutputStream is to read data from and write data to queues in EXDR format In other words we usually wrap these classes around FromEclipse Queue and ToEclipseQueue classes We now look at an example which does just this The example is in these two files eclipse dir doc examples JavaInterface QueueExample1l java eclipse dir doc examples Javalnterface queue example 1 pl The Java program s first relevant action is to invoke the compile method of the EclipseEngine This causes the ECL PS program to be loaded by ECL PS engine After compile completes the Java program creates a ToEclipseQueue and a FromEclipseQueue with the following lines Create the two queues java to eclipse eclipse getToEclipseQueue java to eclipse eclipse to java eclipse getFromEclipseQueue eclipse to java Then in the next two lines we create an EXDROutputStream to format data going to java to eclipse and an EXDRInputStream to format data coming from eclipse to java Set up the two formatting streams java to eclipse formatted new EXDROutputStream java to eclipse eclipse to java formatted new EXDRInputStream eclipse to java The Java program writes two atoms to java to eclipse formatted and then flushes the stream This causes each atom to be translated into EXDR format and the translation to then be written on to java
104. handlers for when control is handed back to ECL PS ec start and when control is handed over from ECL PS ec end are defined thus proc ec end if ec multi get multi status on enable buttons proc ec_start if ec_multi get_multi_status on disable_buttons 58 enable_buttons and disable_buttons enables and disables the buttons for the window re spectively The code tests if the peer is multitasking with ec multi get multi status This is needed because during a peer multitasking phase control is repeatedly handed back and forth and we don t want the buttons to be repeatedly enabled and disabled during this phase Next the program registers the peer for peer multitasking ec_multi peer_register list start multi_start_handler interact multi_interact_handler No special handler is needed for the end of multitasking as no special action is needed beyond disabling the buttons The return code is stored in a global variable return_code The start handler is defined thus proc multi start handler type 1 global return code if type demo set return_code continue enable_buttons else set return_code no return return_code As discussed multitasking phases can be of different types For demonstrating this multitasking features of this example program the type is demo Therefore the handler tests for this and enables the button if the phase is demo On the EC
105. he ECL PS 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 ECL PS side to also close its connections to this remote connection as well as raising the disconnect event in ECL PS associated with this remote connection If the disconnect was initiated from the ECL PS side then ec disconnect wil be called automatically with side set to eclipse and the disconnect command set up by ec running set commands will be executed ECL PS side remote yield Control Explicitly yields control from ECL PS to the remote side with the control stream Con trol ECL PS execution will suspend until control is transferred back to ECL PS This predicate returns when ECL PS side resumes control remote disconnect 4 Control Initiates disconnection from the remote side specified by Control This will close all con nections between ECL PS and the remote side on both sides It will also cause an event Control to be raised 49 Note that if the ECL PS process is halted normally then ECL PS will try to disconnect from every remote side it may be connected to 6 8 Example Tcl side will create the from ECLiPSe queue gui output which wil
106. her the EC word is nil the empty list int EC word functor EC functor checks whether the EC word is a compound term and if so returns its functor int EC word arg const int EC word amp checks whether the EC word is a compound term and if so returns its nth argument int EC word arity returns the arity of an EC word if it is a compound term zero otherwise int EC word is handle const t ext type t ext ptr checks whether the EC word is a handle whose method table matches the given one and if so the data pointer is returned int EC word is var checks whether the EC word is a variable Returns EC succeed if so EC fail otherwise B 3 Referring to ECL PS terms from C The data types EC refs and EC ref provide a means to have non volatile references to ECL PS data from within C data structures However it must be kept in mind that ECL PS data structures are nevertheless subject to backtracking which means they may be reset to an earlier 115 status when the search engine requires it Creating a reference to a data structure does not change that in any way In particular when the search engine fails beyond the state where the reference was set up the reference disappears and is also reset to its earlier value EC_refs int n create a data structure capable of holding n non volatile references to ECL PS data items They are each initialised with a freshly created ECL PS variable EC refs in
107. hine hosting Java Initialising a connection using RemoteEclipse therefore requires some coordination between the ECL PS code and the Java code The Java code always consists of a single RemoteEclipse constructor invocation although the constructor parameters may vary The ECL PS side of the code uses certain builtins Refer to the relevant documentation of these for precise details of usage On the ECL PS side the code can be structured in two different ways one simpler and the other allowing more flexibility We outline here the sequence of actions in each case Basic connection sequence This can be used in situations where no password is to be used and where the port number is specified in advance rather than generated dynamically by ECL PS and is known by the Java side 1 The ECL PS side executes the builtin remote connect 3 specifying the port number in advance This builtin will block until the connection is established 2 The Java side then invokes one of the RemoteEclipse constructors which has no password parameter This should immediately complete or throw an exception if the connection is unsuccessful Advanced connection sequence This more complicated sequence uses a password and op tionally allows the port number to be generated dynamically and then communicated to the Java side 1 The ECL PS side executes the builtin remote connect setup 3 specifying the pass word and either specifying the port number or allowin
108. hread is currently executing an rpc invocation a second Java thread tries to invoke the rpc method of the same EclipseConnection the second thread will block until the first thread s rpc invocation returns Nested invocations of rpc During the execution of the rpc method control is transferred to ECL PS Due to the QueueLis tener feature which is discussed in Section 8 5 control is sometimes temporarily returned to Java before the ECL PS execution has finished It is possible for this Java code itself to invoke rpc thus leading to nested rpc invocations Nested rpc invocations should not cause any problems 69 8 5 Communicating between Java and ECL PS using queues In the Java ECL PS Interface queues are one way data streams used for communication be tween ECL PS and Java These are represented on the ECL PS side using peer queues which are I O streams The Java ECL PS Interface includes the classes FromEclipseQueue and ToEclipseQueue which represent these queues on the Java side FromEclipseQueue represents a queue which can be written to in ECL PS and read from in Java A ToEclipseQueue is a queue which can be written to in Java and read from in ECL PS Section 8 5 1 discusses how queues are opened referenced and closed from either the Java or ECL PS sides We also discuss here how to transfer byte data in both directions However the programmer need not be concerned with low level data operations on queues whole terms
109. imiter character It is therefore recommended to use the EXDR ECL PS external data representation see section 5 7 format for communication This allows to send and receive structured and typed data The primitives to do that are ec read exdr section 5 7 on the Tcl side and read exdr 2 on the ECL PS side Tcl ec_write_exdr my_out_channel foo bar 3 SI ec_flush ec_streamname_to_streamnum my_in_queue ECLiPSe read exdr my in queue Result In the example the ECL PS result will be the term foo bar 3 For details about the mapping see section 5 7 5 5 Attaching Handlers to Queues In order to handle ECL PS I O on queues more conveniently it is possible to associate a handler with every queue either on the Tcl or ECL PS side These handlers can be invoked automatically whenever the other side initiates an I O operation 25 5 5 1 Tcl handlers To ECL PS queues For this purpose the to ECL PS queue must be created with the command argument set The following example creates a queue that can be written from the ECL PS side and whose contents if flushed is automatically displayed in a text widget Tcl pack text tout ec queue create my out queue toec ec_stream_to_window tout Assume that ECL PS is then resumed writes to the queue and flushes it This will briefly pass control back to Tcl the ec stream to window handler will be executed with the stream number added to its arguments afterwards c
110. ing Pressing the reg button will either call register_for_multi or deregister_for_multi de pending on if the peer is currently deregistered or registered for peer multitasking respectively The procedure also changes the button to toggle to the other state Pressing the button during a peer multitasking phase will remove the peer from multitasking immediately If pressed while the peer is given exclusive control the peer will not participate in future multitasking phase unless it is re registered 60 Chapter 8 Using the Java ECL PS Interface The Java ECL PS Interface is a general purpose tool for interfacing ECL PS with Java Sun s popular object oriented platform independent programming language It could be used for ex ample to write a Java graphical front end to an ECL PS optimisation program or to interface ECL PS with a commercial application written in Java This document assumes a moderate level of programming in Java e g how to use classes packages interfaces etc and some knowl edge of the java util java io and java net libraries and a basic knowledge of how to interact with ECL PS e g how to execute a goal nondeterminism what lists are etc There are also some diagrams in UML notation but these are not crucial to the reader s understanding Section 8 1 is intended to get you started quickly by running the example program Quick Test java Section 8 2 gives a brief overview of the functionality of the J
111. ing in ECL PS syntax Note that unlike with the C C interface it is not possible to retrieve any variable bindings from ECL PS after 28 successful execution of the goal To pass information from ECL PS to Tcl use queue streams as described later on Example ec post goal go hello 27 If a format argument is provided the ECL PS goal is constructed from goal data and format according to the conversion rules explained in section 5 7 Example ec post goal go hello 27 SI Posting several goals is the same as posting the conjunction of these goals Note that simple deterministic goals can be executed independently of the posted goals using the ec rpc command see below ec post event event name Post an event to the ECL PS engine This will lead to the execution of the correspond ing event handler once the ECL PS execution is resumed See also event 1 and the User Manual chapter on event handling for more information This mechanism is mainly recommended for asynchronous posting of events e g from within signal handlers or to abort execution Otherwise it is more convenient to raise an event by writing into an event raising queue stream see section 5 5 2 ec handle events resume execution of the ECL PS engine for the purpose of event handling only All events that have been posted via ec post event or raised by writing into event raising queues will be handled in an unspecified order The return value will alway
112. is interface Startup Arguments char args L a b c ec set option int EC OPTION ARGC 3 ec set option ptr EC OPTION ARGV args These setting are used to simulate a command line for an embedded ECL PS or to pass command line information to an embedded ECL PS The ECL PS built in predicates argc 1 and argv 2 can access this information This provides a way of passing some initial data to the ECL PS engine Default Module ec set option ptr EC OPTION DEFAULT MODULE my module The default module is the module in which goals called from the top level execute It is also the module that goals called from C or C execute in The default setting is eclipse I O Initialisation ec set option int EC OPTION IO MEMORY I0 This option controls whether the default I O streams of ECL PS are connected to stdin stdout stderr or to memory queues The default setting of this op tion is SHARED IO which means the ECL PS streams 0 1 2 are connected to stdin stdout stderr In an embedded application stdin stdout stderr may not be avail able or the host application may want to capture all I O from ECL PS In this case use the MEMORY IO setting which creates queue streams for streams 0 1 and 2 These can then be read and written using ec queue read and ec queue write Parallel system parameters 110 ec_set_option_int EC_OPTION_PARALLEL_WORKER 0 ec_set_option_int EC_OPTION_ALLOCATION ALLOC_P
113. is not supported by the other two classes To summarise the advantages and disadvantages Table 8 2 gives an at a glance comparison of the different features of the different connection classes 82 interface eConnection Eclip getFromEclipseQueue name String FromEclipseQueue getToEclipseQueuet name String ToEclipseQueue getPeerName Atom mc goal CompoundTerm CompoundTerm interface EclipseEngine BEES ee getEclipseSiding ToEclipseQueye getEclipseStdout FromEclipseQueue getEclipseStderr FromEclipseQueue RemoteEclipse disconnectQ void resume Q void EmbeddedEclipse OutOfProcessEclipse destroyO void destroyQ void Figure 8 4 UML class diagram for different classes connecting Java and ECL PS Some con venience methods from EclipseConnection have been omitted 83 Feature Java ECL PS connection class Embedded OutOfProcess Remote Implements EclipseConnection interface allowing rpc and queues Implements EclipseEngine interface allowing access to ECL PS stdio streams ECL PS is in a separate process with separate memory heap stack ECL PS can be on a separate machine from Java ECL PS engine can start before end after Java virtual machine ECL PS engine created destroyed from Java Efficient transfer of data on queues and rpc invocations One ECL PS can connect to many Java virtual machines using this O
114. isation on remote side etinead initialisation on ECLiPSe side wait for message from remote attachment is complete remote side has initial control remote side on control Vi Figure 10 1 Summary of the attachment protocol ensures that the same or at least compatible versions of the protocol are used so that the two sides behaves correctly The version information is sent from the remote side which must have its own copy of the version information and the ECL PS side checks that this is compatible with the protocol version it is using In order to cope with remote connections which may not be using the remote protocol the ECL PS side waits only for a fixed period of time for the remote side to send the version information before timing out Time out on the ECL PS side can also occur for forming any of the connections between the two sides from the control connection to the peer queue This is specified by the user in remote connect accept 6 If time out occurs during the attachment then the attachment process is abandoned and the predicate fails any connected sockets will be closed The detailed sequence of events for the attachment for the remote side with some description of the relevant ECL PS side actions are 1 ECL PS side a socket server for the control connection is created using the address Host Port which can be specified by the user It then waits to accept a socket stream for the control connection from th
115. l also 4 automatically flush at the end of every line and so transfer the data 4 to the Tcl side disconnect handler just terminate ECLiPSe execution writeln Terminating halt remote_connect localhost 5000 control set_event_handler control disconnect handler 0 for simplicity the host and port are fixed Name for control connection is also fixed when remote connect returns the gui output queue will be connected to Tcl side already eclipse side initialisation follows is just to set up the X XN XN XN 22 23 handler for disconnection writeln gui_output Connected this is for yielding control to Tcl No need to specify Control explicitly tclyield remote_yield control Figure 6 1 Example use of interface ECL PS code Figures 6 1 and 6 2 shows a simple example of the use of the interface To try this program the user should start an ECL PS compile the ECL PS program This will suspend on the remote connect 3 waiting for the Tcl program to attach The Tcl program should then be started on the same machine and the attachment will be connected using the fixed host and port address During the initialisation when attaching a from ECL PS queue is created which is set to flush at every newline This is done by an ec rpc goal after the queue is cre ated As no Tcl data consumer handler is specified the default Tcl data consumer handler ec stream output popup handles and display the da
116. l remote interface 43 ec_stream_to_window_sync Tcl embedding interface 26 ec_stream_to_window_sync Tcl remote in terface 37 ec streamname to channel Tcl embedding interface 24 ec streamname to channel Tcl remote in terface 47 ec_streamname_to_streamnum Tcl embed ding interface 24 ec_streamname_to_streamnum Tcl remote interface 47 ec_streamnum_to_channel Tcl embedding interface 24 ec streamnum to channel Tcl remote inter face 47 ec tcl2exdr 27 ec write exdr 27 ec multi peer register Tcl command 55 ec remote init Tcl command 32 EC word 10 eclipse peer multitask Tcl package 55 EclipseConnection interface 63 67 74 75 82 EclipseEngine interface 63 74 75 82 EmbeddedEclipse class 63 64 74 76 erase 2 14 event 1 27 29 118 125 events 7 EXDR 64 71 72 74 exec 3 93 107 external 1 19 external 2 19 failure 6 flush 1 23 37 foreign library 127 foreign 3 127 functor 9 garbage collection 9 10 12 get flag 2 90 get stream 2 24 125 include files 4 initialisation 5 installation directory 3 129 list 10 12 load 1 18 load foreign files 2 127 logical variable 6 10 logical variables 13 Makefile 4 18 memory management 9 method table 13 open 3 29 96 125 open 4 29 118 124 125 OutOfProcessEclipse class 74 78 package eclipse 21 package eclipse tools 22 passing data 8 9 peer do
117. le and interface functions or methods provide access to its components when required Both techniques are supported by the ECL PS C and ECL PS C4 4 interface 3 1 Constructing ECL PS data 3 1 1 ECL PS atoms and functors ECLiPSe code S book Gulliver s Tales Swift hardback fiction In the above structure hardback and fiction are atoms book is the functor of that structure and it has an arity number of arguments of 4 Each functor and atom is entered into a dictionary and is always referred to by its dictionary entry Two classes EC_atom and EC_functor are used to access such dictionary entries The Name method applies to both to get their string form The Arity method can be used to find out how many arguments a functor has C code EC functor book book 4 EC_atom hardback hardback if book Arity 4 evaluates to true if book hardback evaluates to false S hardback Name like s hardback 3 1 2 Building ECL PS terms The pword C data type is used to store ECL PS terms In C the EC word data type is used This is used for any C type as well as for ECL PS structures and lists The size remains fixed in all cases since large terms are constructed on the ECL PS global stack The consequences of this are that terms will be garbage collected or moved so terms do not survive the execution of ECL PS In particular one c
118. lic name or number via the commands ec streamname to channel or ec streamnum to channel e Asynchronous queues are bi directional In the embedding interface there are no asyn chronous queues and ec async queue create is aliased to ec queue create and a uni directional queue is created Thus for compatibility these queues should only be used in one direction In summary to write code that will work for both the remote and embedded interfaces the data should be sent using EXDR format flush always performed and a handler command argument provided The Tcl channel identifier should not be constructed explicitly However there may be cases where the two interfaces need to be distinguished For example if the Tcl side is to perform some operations on the file system for the ECL PS side e g selecting a file via a GUI then with the remote interface the two sides might not have access to the same file systems and being able to distinguish whether the interface is remote or embedded allows the user to provide code to handle this To obtain information on which interface is being used use the command 51 ec_interface_type returns remote for the remote interface and embedded for the embedding interface 52 ECLIPSEDIR has to be set to where your ECLiPSe is at lappend auto_path file join ECLIPSEDIR lib_tcl package require remote_eclipse proc terminate destroy disable the terminate button when con
119. lipse so At runtime your application must be able to locate libeclipse so This can be achieved by adding ECLIPSEDIR lib ARCH to your LD_LIBRARY_PATH environment variable The embedded ECL PS finds its own support files e g ECL PS libraries through the ECLIPSEDIR environment variable This must be set to the location where ECL PS is installed e g usr local eclipse Alternatively the application can invoke ec set option to specify the ECLIPSEDIR location before initialising the embedded ECL PS with ec init 2 1 4 Static linking Unix Linux If your operating system only supports static linking or if you want to link statically for some reason you have to link explicitly with 1ibeclipse a and the necessary support libraries must be specified e g gcc I ECLIPSEDIR include ARCH eg c basic c ECLIPSEDIR lib ARCH libeclipse a L ECLIPSEDIR lib ARCH lgmp lshm ldummies 1ldl lnsl lsocket lm The libraries gmp shm and dummies are ECL PS support libraries and must be specified in that order The others are Unix libraries It is recommended that you copy the makefile Makefile external provided in your installation directory under lib SARCH and adapt it for your purposes 4 2 1 5 Compiling linking and running on Windows You need to have the following additional setting in your C C compiler development system e In the C C Preprocessor settings specify the ECL PS include directory as an additional include direct
120. ll be executed The return value will be EC_succeed if the goals succeed in this case the ToC argument returns a cut value that can be used to discard alternative solutions EC_fail is returned if the goals fail and EC yield if control was yielded because of a yield 2 predicate call in the ECL PS code in this case ToC contains the data passed by the first argument of yield 2 If a writable queue stream with yield option see open 4 was flushed the return value is PFLUSHIO and ToC contains the associated stream number If there was an attempt to read from an empty queue stream with yield option the return value is PWAITIO and ToC contains the associated stream number Moreover if the previous EC resume yielded due to a yield 2 predicate call The term FromC is passed as input into the second argument of yield 2 on resuming void EC ref cut to Should be applied to the ToC cut return value of an EC resume Cut all choicepoints created by the batch of goals whose execution succeeded int post event EC word Name Post an event to the ECL PS engine This will lead to the execution of the corresponding event handler once the ECL PS execution is resumed See also event 1 and the User Manual chapter on event handling for more information Name should be an ECL PS atom 118 Appendix C Summary of C Interface Functions Note that a self contained subset of the functions described here uses only integer and string arguments and is th
121. ll be handed over to the ECL PS side to process the data the goal associated with the event foec event is executed and this goal should read the data from the queue Unlike the synchronous to ECL PS queues the data is not buffered and the handler goal is called every time ec flush is invoked rather than only when the queue is empty This should normally not make any difference as the handler should empty all the contents of a queue each time it is invoked The goal is called with two optional arguments the first argument is the event name the second argument is the culprit of the form rem flushio Queue Len indicating that this event is caused by a remote flush where Queue is the ECL PS stream number and Len is the number of bytes sent this is supplied by ec flush if ec flush does not supply a length then Len is the atom unknown Examples for asynchronous queue Using the queue asynchronously to ECL PS An example of using an asynchronous queue asynchronously to send data to ECL PS is in the tracer for TkECL PS development 43 tools Here the trace line is printed on a synchronous from ECL PS queue and handled by a Tcl data consumer handler which prints the trace line and waits for the user to type in a debugger command This debugger command is sent to the ECL PS side using an asynchronous queue which is read by the ECL PS side when it returns Here is a much simplified version of the code Tcl code ec queue
122. loading It is strongly recommended to copy the makefile Makefile external provided in your installation directory under lib SARCH and adapt it for your purposes If the makefile is not used the command to compile a C source with ECL PS library calls looks something like this cc G I usr local eclipse include sparc_sunos5 o eg externals so eg externals c or cc shared I usr local eclipse include i386_linux o eg externals so eg externals c If the external is to be used in a standalone ECL PS it is possible to dynamically load it using the load 1 predicate 18 load eg_externals so On older UNIX platforms without dynamic loading the following method may work Compile the source using cc c I usr local eclipse include sparc_sunos5 eg externals c and load it with a command like load eg externals o lg 1m The details may vary depending on what compiler and operating system you use Refer to the Makefile external for details Once the object file containing the C function has been loaded into ECL PS the link between the function and a predicate name is made with external 2 external sumlist 2 p sumlist The new predicate can now be called like other predicates Note that the external 2 declaration must precede any call to the declared predicate otherwise the ECL PS compiler will issue an inconsistent redefinition error Alternatively the external 1 forward declaration can be used to prevent this 4
123. n attachment and then disconnect immediately when ECLiPSe side returns control test Host Port make the remote attachment For this simple example there is no application specific initialisations and the default pass term of an empty string is used remote attach Host Port true Control Ec rpc _ control has been given to ECLiPSe side wait for ECLiPSe side to return control read exdr Control _ immediately disconnect from ECLiPSe side write exdr Control disconnect flush Control wait for ECLiPSe side to acknowledge disconnect read exdr Control disconnect yield 94 clean up close Control close Ec_rpc In addition to the attachment the example contains a very simple example of using the protocol by exchanging control messages with the ECL PS side After attachment it disconnects the remote attachment as soon as control is handed back to it For more details on the messages see next section To try out the example start an ECL PS session and initiate a remote attachment This process is the ECL PS side ECLiPSe side eclipse 1 remote connect Host Port Control _ Socket created at address chicken icparc ic ac uk 32436 Now start another ECL PS session compile the example program and make the attachment to the ECL PS side Remote side eclipse 4 test chicken icparc ic ac uk 32436 On the ECL PS side remote connect 3 should now succeed
124. n this process e g string vs atom Since Tcl is an untyped language all commands which create EXDR terms accept in addition to the data an optional format argument which allows all EXDR data types to be specified The syntax is as follows To create EXDR type use format data required String S string binary String U string utf8 Integer I integer Double D double List lt formats gt fixed length list List lt formats gt list Struct formats fixed list first elem functor name Struct lt formats gt list first elem functor name Anonymous Variable string 7 7 Here are some examples that show which Tcl data format pair corresponds to which ECL PS term the curly brackets are just Tcl quotes and not part of the format string Tcl data Tcl format Eclipse term hello S hello hello O hello 123 S 123 123 I 123 123 D 123 0 123 O 7123 a 3 4 5 SID a 3 4 5 a 3 4 5 S a 34 5 1 2 3 4 I 1 2 3 4 f 1 2 3 I f 1 2 9 fis 121 _ 1I _ is 1 2 5 8 Incompatible and obsolete commands Here is a list of commands in the embedding interface that are retained for compatibility purposes with previous versions They have no equivalent in the Tcl remote interface and their use for new code is discouraged ec post goal goal format post a goal that will be executed when ECL PS is resumed If no format argument is given the goal is taken to be a str
125. nctor to the relevant outgoing stream and flush the outgoing stream 8 5 4 Access to ECL PS s standard streams If the object representing the ECL PS implements the EclipseEngine interface then the API user may have access to the ECL PS s standard streams see Section 8 6 2 These are returned as FromEclipseQueues and ToEclipseQueues by the methods getEclipseStdin getEclipseS tdout and getEclipseStderr 8 6 Managing connections to ECL PS As of ECL PS 5 3 and later there are three Java classes which can be used to provide in teraction with ECL PS These are EmbeddedEclipse OutOfProcessEclipse and RemoteEclipse Although the three classes all implement the EclipseConnection interface there are some im portant differences in initialisation termination and use which are explained in this section On the ECL PS side as of version 5 3 and later there is a unified interface for interaction with Java based around the concept of a peer This is explained in Section 8 6 1 Section 8 6 2 discusses how to create an ECL PS engine from within Java this covers both EmbeddedEclipse and OutOfProcessEclipse Section 8 6 3 discusses the RemoteEclipse class which allows Java to connect to an existing ECL PS engine Finally Section 8 6 4 compares the three connection classes assessing the advantages and disadvantages of each 8 6 1 A unified ECL PS side interface to Java the peer concept To allow ECL PS code to be independen
126. nd and the handler continues its execution beyond the tkwait The buttons are disabled the command sent to ECL PS side on the debug input queue using flush This is the asynchronous sending of data on the asynchronous queue control is not handed over to ECL PS to process this command Instead the execution on the Tcl side carries on and happens to finish immediately after the flush Control is then returned to the ECL PS side as the Tcl handler has finished and the ECL PS side continues execution after the flush debug traceline goal Next debug input is read for the tracer command and this command is acted on Using the queue synchronously to ECL PS If the Tcl remote interface command ec stream input popup see section 6 6 2 is used to send data to the ECL PS side in sec tion 6 6 2 the command was initiated by a read operation on the ECL PS side here the com mand is invoked directly when Tcl side has control then the following is a possible ECL PS handler Tcl code create the asynchronous queue with 3 from ECLiPSe Tcl consumer handler data to window to ECLiPSe ECLiPSe handler event flush myqueue ec async queue create myqueue data to window textwin flush myqueue get input for the queue and send to ECLiPSe side ec stream input popup Data ec channel to streamnum myqueue ECLiPSe code 45 set event handler flush myqueue read remote data 2 Len is known when ec stream input popup is us
127. ndler If at least one peer indicates that it is interested in the multitasking phase then after the initial start phase the control will be repeatedly handed over to each multitasking peer by invoking the interact handler This phase is ended when one or more peer indicates that the multitasking phase should end at which point the end phase will be entered in which the end handler will be invoked for each multitasking peer 7 3 1 Summary of Tcl Commands Here is a more detailed description of the Tcl procedures ec_multi peer_register Multitask handlers Registers for peer multitasking and setup the optional multitask handlers There han dlers can be specified a start invoked at the start of a multitasking phase b end invoked at the end of a multitasking phase and c interact invoked at other times when the peer is given control during a multitasking phase Multitask handlers is a list specifying the handlers where each handler is specified as two list elements of the form type name where type is either start end or interact and name is the name of the user defined handler For example ec_multi peer_register list interact tkecl multi_interact_handler start tkecl multi_start_handler end tkecl multi_end_handler When control is handed over to the peer during a peer multitasking phase the appropriate handler if defined is invoked When the handler returns control is handed back to ECL PS and passed to the next multita
128. ne Java virtual machine can connect to many ECL PS engines using this Table 8 2 Feature comparison table for different ECL PS connection classes 84 Chapter 9 EXDR Data Interchange Format We have defined a data interchange format called EXDR for the communication between ECL PS and other languages The data types available in this format are integer double string list nil structure and anonymous variable This is intended to be the subset of ECL PS types that has a meaningful mapping to many other languages data types The mapping onto different languages is given in the following table For details of the mapping between Java classes interfaces and EXDR ECL PS types see Section 8 3 1 EXDR type ECLiPSe type TCL type Java type Integer integer int java lang Integer e g 123 123 123 Long integer string java lang Long e g 5000000000 5000000000 5000000000 Double float double java lang Double Float e g 12 3 12 3 12 3 String string string java lang String e g abc abc abc List 2 list java util Collection e g a b c a b c Nil 0 empty string java util Collection eg g Struct compound list CompoundTerm Atom e g foo bar 3 foo bar 3 Variable variable string null e g 3 z The EXDR Integer data type is a 32 bit signed integer the EXDR Long data type is a 64 bit signed integer bigger ECL PS integers cannot be represented The EXDR Variable
129. ng interface 23 ec_flush Tcl remote interface 39 ec_handle_events 29 ec_init 22 ec_interface_type Tcl embedding interface 27 ec_interface_type Tcl remote interface 52 ec_multi get_multi_status Tcl peer multi tasking 57 128 ec_multi peer_deregister Tcl peer multitask ing 57 ec_multi peer_register Tcl peer multitask ing 56 ec_post_event 29 ec_post_goal 28 ec_queue_close Tcl embedding interface 24 ec_queue_close Tcl remote interface 36 42 ec_queue_connect Tcl embedding interface 29 ec_queue_create Tcl embedding interface 24 ec queue create Tcl remote interface 36 ec read exdr 27 ec remote init Tcl remote interface 33 ec resume Tcl embedding interface 23 ec resume Tcl remote interface 49 ec rpc Tcl embedding interface 22 ec rpc Tcl remote interface 34 ec running Tcl embedding interface 23 ec running Tcl remote interface 49 ec running set commands Tcl remote inter face 49 ec set option 21 ec set queue handler Tcl embedding inter face 30 ec stream input popup Tcl embedding in terface 26 ec stream input popup Tcl remote inter face 40 ec stream nr Tcl embedding interface 24 ec stream nr Tcl remote interface 47 ec stream output popup Tcl embedding in terface 26 ec stream output popup Tcl remote inter face 37 ec stream to window Tcl embedding inter face 26 ec stream to window Tc
130. ng whether the Tcl end of the queue is readable or writable For readable queues the handler is invoked when the ECL PS side flushes the queue The Tcl handler is expected to read and empty the queue For writable queues the handler is invoked when the ECL PS side reads from the empty queue The Tcl handler is expected to write data into the queue In any case the handler command will be invoked with the ECL PS stream number appended as an extra argument 30 Chapter 6 Remote Tcl Interface This chapter describes the remote Tcl interface which allows a separate external Tcl program to interact with ECL PS in much the same fashion as the embedding Tcl interface see chapter 5 Like the embedding interface Tcl and ECL PS code communicates by sending and receiving streams of bytes via I O queues the ec rpc mechanism is implemented on top of these queues The interface can thus be used in similar fashion to the embedding interface e g for the de velopment of graphical user interfaces to an ECLiPSe application with the difference that the ECL PS program is a separate program and not embedded into the Tcl program The main features of the interface are e The connection between the Tcl and ECL PS processes are established via sockets using TCP network protocol Thus the Tcl process can be run on a different machine and platform from the ECL PS process e The Tcl process can be attached to any running ECL PS process including an
131. nitialisation during attachment remote connect localhost MyPort Control set event handler Control my disconnect handler 1 my disconnect handler Remote just print out a message about the disconnection printf Disconnected from remote attachment w Remote 10 6 Support for the Remote Interface ECL PS 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 accord ing 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 side this can be used for example to define a disconnection handler that will be called when 106 the two sides disconnect The predicate succeeds when the attachment is successfully made and the remote side returns control to the ECL PS side Peer is the name of the control connection and is used to identify a particular remote peer an ECL PS 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
132. nputs from the user via the GUI Note that these data providers can only exist for the synchronous queues For each queue and for a particular direction of data flow a handler can be defined on either the Tcl or the ECL PS side but not both The handler either consumes or provides data as described above The reason that handlers cannot be defined on both sides is that this avoids possible infinite loop of alternately triggering the data provider and the data consumer 6 6 2 Synchronous Queues These queues can be created on the Tcl side This is done with the ec_queue_create command from within Tcl code ec_queue_create eclipse_stream_name mode command event Creates a synchronous queue between Tcl and ECL PS sides On the Tcl side a Tcl channel is created On the ECL PS side the queue would be given the symbolic name eclipse stream name The mode argument indicates the direction of the queue and can either be fromec or toec The procedure returns a channel identifier for use in commands like puts read ec read exdr ec write exdr or close The optional arguments com mand and event specifies the data handler for the queue command is the name of the Tcl procedure for handling the data with its user defined arguments event is the name of the event that will be raised on the ECL PS side see the section 6 6 1 for more details As a handler can only be defined for one side either event or command should be undefined ec_que
133. nterest no do nothing return of_interest An error is raised if this procedure is called while the peer is already registered for multi tasking ec_multi peer_deregister Deregisters peer from multitasking After calling this procedure the peer will not partici pate in any further multitasking If this procedure is called during a multitasking phase the peer will not participate further in that multitasking phase once control is returned The multitasking phase will continue unless there are no multitasking peers left in which case an error will be raised on the ECL PS side The peer multitask control queue will be automatically closed An error is raised if this procedure is called while the peer is not registered for multitasking ec_multi get_multi_status Returns the current peer multitasking status for the peer The values can be e not registered the peer is not registered for peer multitasking e off the peer is registered for peer multitasking but is not currently in a multitasking phase 57 e on the peer is registered for peer multitasking and is currently in a multitasking phase Note that the peer multitasking code is implemented using peer queue handlers Thus the peer multitask status is set to on before the multitask start handler is called but after the ECL PS end handler Conversely the peer multitask status is set to off after the multitask end handler but before the ECL PS star
134. o sides are carried out checking that the remote protocols on the two sides are compatible checking the pass term 2 Establishing the ERPC connections and exchange of information remote language ECL PS name for the peer 3 User defined initialisations The remote protocol version is stored in the flag remote protocol version accessible via get flag 2 This should be a remote protocol 1 term with an integer version number This version number should only change when the protocol is modified Checking of the version 90 Actions performed by ECLiPSe side Actions performed on remote by remote_connect 3 or side remote_connect_setup 3 and remote_connect_accept 5 accept controlsocket connection request ae ms ES Um Um Rm create a client socket for control read remote version write remote version on control from control flush contro write yes if version read version compare resultsl matches flush control from contro read pass term from write pass term on control flush control control write ECLiPSe name for read ECLiPSe name for control control on control from contro flush control read remote language write remote language name on name from control control flush control SE east mom mo m m m m m m m m m m m m Create a client socket for rpc write ECLiPSe name read ECLiPSe name for control for control on rpc from rpc flush rpc perform optional user defined perform option users initial
135. ocket connections from the remote side the ECL PS side is informed of the host of the remote side This should either be the client s hostname or localhost After accepting the control connection subsequent connections for ec rpc and any peer queues are checked to ensure that they are from the same client If not the attachment is terminated by ECL PS Using localhost as the name on either side will restrict the two sides to be on the same machine and they must both use localhost for Host in the address rather than the actual hostname 10 3 1 An example The following is a simple example of making a remote attachment on the remote side In this case the remote side is also an ECL PS program A remote attachment by a program written in another programming language will need to provide a similar function in that language Example code for making a remote attachment on the remote side local variable ecsidehost remote attach 6 makes a remote attachment to a host ECLiPSe program Args Host host name on ECLiPSe side Port port on ECLiPSe side Pass pass term used to verify the connection Init goal to call to perform any application specific initialisation Control the remote side local name of the control connection Ec rpc the remote side name of the ec rpc connection EcSideControl the ECLiPSe side name for the control connection remote attach Host Port Pass Init Control Ec
136. ode indicates success or failure Note however that if attributed variables are involved their handlers have not been invoked yet this happens after the external predicate returns int EC word unify EC word same as method int ec unify pword pword same for C Apart from that all functions for constructing testing and decomposing ECL PS data can be used in writing the external predicate see chapter 3 Here are two examples working with lists the first one constructing a list in C include eclipse h int p_string_to_list string_to_list String List pword list char s long len int res res ec_get_string_length ec_arg 1 amp s amp len if res PSUCCEED return res 17 list ec_nil build the list backwards while len list ec_list ec_long s len list return ec_unify ec_arg 2 list The next example uses an input list of integers and sums up the numbers It is written in C include eclipseclass h extern C int p sumlist 1 int res long x sum 0 EC word list EC arg 1 EC word car cdr for list is list car cdr EC succeed list cdr res car is_long amp x if res EC_succeed return res sum x res list is_nilQ if res EC_succeed return res return unify EC_arg 2 EC_word sum The source code of these examples can be found in directory doc examples within the ECL PS installation 4 2 Compiling and
137. ons that maintain some state This state is the complete execution state of the ECL PS engine its stack of goals its success and failure continuations and its global stack of all constructed data At particular points during its execution ECL PS will yield control back to the C level This is implemented by returning from a function ECL PS can then be restarted from the exact point it left off This is implemented by a function call 2 2 1 Initialisation You initialise ECL PS by calling the parameterless function int ec_init A process should do this just once ec_init returns 0 on success or 1 if an error occurred It is possible to influence the initialisation of ECL PS by setting initialisation options as described in Appendix A None of the functions of the interface work before this initialisation In particular in C if you use static variables which are constructed by calling ECL PS functions you must arrange for the initialisation to occur before the constructors are called 2 3 Control flow ECL PS and a C or C main program are like threads running in a single process Each maintains its state and methods for exchanging data and yielding control to the other thread The main method of sending data from C to ECL PS is by posting goals for it to solve All posted goals are solved in conjunction with each other and with any previously posted goals that have succeeded Data is passed back by binding logical variables
138. ontrol is passed back to ECL PS Note that ec stream to window is a predefined handler which reads the whole queue contents and dis plays it in the given text widget From ECL PS queues Similarly a from ECL PS queue could be created as follows Tcl ec_queue_connect my_in_queue fromec fec stream input popup Type here Assume that ECL PS is then resumed and reads from my in queue This will briefly yield control back to Tcl the ec stream input popup handler will be executed afterwards control is passed back to ECL PS Three predefined handlers are provided ec stream to window tag tert widget stream_nr Inserts all the current contents of the specified queue stream at the end of the existing text widget using tag ec stream to window sync tag tert widget stream mr length This is provided for compatibility with the Tcl remote interface This command is essen tially an alias for ec stream to window with an optional dummy argument length that is ignored ec stream output popup label text stream nr Pops up a window displaying the label text a text field displaying the contents of the specified queue stream and an ok button for closing ec stream input popup abel text stream nr Pops up a window displaying the label text an input field and an ok button The text typed into the input field will be written into the specified queue stream When ECL PS is initialised with the default options its output and er
139. ory e g C Eclipse include 1386 nt e In the Link settings specify eclipse lib as an additional object library module and the location of this library e g C Eclipse 1ib 1386 nt as an additional library path At runtime your application must be able to locate eclipse d1l i e you should either e copy eclipse dll into the folder where your application is located or e copy eclipse dl1 into one of Windows standard library folders or e add the path to the folder where eclipse d1l can be found to your PATH environment variable The eclipse d1l finds its own support files e g ECL PS libraries through the ECLIPSEDIR registry entry under the registry key HKEY LOCAL MACHINENSOFTWARENMIC ParcNECLiPSeWX Y X Y is the version number This must be set to the location where ECL PS is installed e g C Eclipse Alternatively the application can invoke ec set option to specify the ECLIPSEDIR location before initialising the embedded ECL PS with ec init 2 2 Creating an ECL PS context ECL PS runs as a special thread we will call it ECL PS engine within your application maintaining its own execution state This section is about when and how to initialise it There are parameters to be applied before initialisation but these are usually acceptable These parameters are described in Appendix A Although it is useful to think of ECL PS as a thread it is not an operating system thread but is rather implemented as a set of C functi
140. peer queue 10 4 1 Synchronous peer queues The implementation of a synchronous peer queue on the ECL PS side is shown in figure 10 2 There is an in memory buffer which is implemented as a memory queue in ECL PS i e Name Queue vo Memory buffer S socket connection ECLiPSe Side Remote Side Figure 10 2 ECL PS implementation of remote synchronous peer queue queue option for open 3 Associated with the memory queue is the actual socket stream to the remote side The memory queue is the queue that the user sees on the ECL PS side with name Name and a unique integer id Queue which is the stream id for the memory queue The id is used by both sides to identify the queue as it is unique a symbolic name can always be reassigned and is used in the control messages To conform to normal ECL PS streams these queues appear uni directional to the user i e data can be either written to or read from the queue The direction is fromec if the direction of the data is from ECL PS to the remote side i e ECL PS can output to the queue and toec if the direction is from the remote side to ECL PS i e ECL PS can read from the queue The user perform normal I O operations on the memory queue and the protocol ensures that the data is transferred correctly to the remote side without blocking The socket stream is largely hidden from the user on the ECL PS side with data automatically transferred between it and the buff
141. phical display monitoring the state of search in ECL PS We would like ECL PS to be able to send a message along a queue every time an element of the search state updates and have Java react with some appropriate graphical action according to the message Similarly ECL PS may require information from a Java database at some point during its operation Again we could use a queue to transfer this information If ECL PS tries to read from this queue when it is empty we would like Java to step in and supply the next piece of data The QueueListener interface is the means by which handlers are attached to queues on the Java side so that Java reacts automatically to ECL PS s interaction with the queue Any object which implements the QueueListener interface can be attached to either a FromE clipseQueue or a ToEclipseQueue using the setListener method The QueueListener can be removed using removeListener Queues can only have one Java listener at any one time The QueueListener interface has two methods dataAvailable and dataRequest dataAvailable is invoked only if the QueueListener is attached to a FromEclipseQueue It is invoked when the queue is flushed on the ECL PS side dataRequest is invoked only if the QueueListeneris attached to a ToEclipseQueue It is invoked when ECL PS tries to read from the queue when it is empty Both methods have a single Object parameter named source When they are invoked this parameter is the FromEclips
142. ples directory eclipse dir doc examples JavaInterface The rest of the pro gram sends ECL PS a goal which tells it to write the term created by construct term to stdout In this example we use an CompoundTermImpl constructor whose first parameter is a string which becomes the functor of the term The remaining parameters are instances of java lang Object They may be instances of any class or interface which appears in Table 8 1 These become the arguments of the term Compound TermImpl has a number of other convenient constructors See the API documentation for details of these Note that the object returned by construct term is declared not as a Compound TermImpl but as a CompoundTerm Compound Term is the Java interface for objects representing com pound terms Anything which implements CompoundTerm can be sent to ECL PS as a com pound term Instead of using CompoundTermImpl you may wish to implement CompoundTerm yourself The benefit of this is that you can pass any object implementing CompoundTerm to an rpc invocation and it can supply a functor and arguments without the unnecessary creation of another object To do this you may wish to subclass AbstractCompound Term 8 3 3 Lists Whenever you want to construct a list for ECL PS or deconstruct a list coming from ECL PS you use the java util Collection interface Look at the following method taken from the example Java program DataExample2 java which can be found in the exampl
143. queue is passed to the remote side via the socket client message The remote side should then connect a client socket with Port as the port and the Host used for the initial attachment which is either localhost or the hostname of the eclipse side for the host It should also perform any additional setups for the peer queue using the information sent with the message typically this involve setting up book keeping information for the queue on the remote side When the remote side connection is established it returns control to ECL PS via a socket connect message socket connect Name Status Name is the name of the queue and should be the same as the Name sent by the socket client message This is used to verify that the messages refer to same interac tion The ECL PS side will raise an error and disconnect from the remote side if the name does not match Status is either success or fail depending on if the remote side successfully created the remote side of the queue or not If Status is success then the ECL PS side will complete the connection for the peer queue by accepting the socket connection Since the remote end of the socket exists the accept operation should succeed very quickly If not the operation will time out using the time out interval specified when the attachment was made The server socket is closed immediately after the accept operation On successful connection ECL PS first checks that this client s host is indeed
144. r compatibility purposes ec streamname to channel eclipse stream name Returns the Tcl channel name for the queue with the symbolic name eclipse name ec streamnum to channel eclipse stream number Returns the Tcl channel name for the queue with the ECL PS stream number eclipse stream number ec async queue create eclipse stream name mode command event This is provided mainly for compatibility with the Tcl remote interface The command is an alias for ec queue create in the embedding interface Certain uses of the queues in the embedding interface cannot be duplicated using the synchronous queues of the remote interface Instead asynchronous queues are needed see chapter 6 for more details This command is provided to allow the same code to be used for both interfaces Note that it is possible to use the asynchronous queues of the remote interface in ways that are incompatible with the embedding interface 5 4 1 From ECL PS to Tcl To create a queue from ECL PS to Tcl use ec queue create with the mode argument set to fromec e g Tcl set my in channel ec_queue_create my out queue fromec Once the queue is created it can be used e g by writing into it with ECL PS s write 2 builtin and reading using Tcl s read command For compatibility with previous versions of the embedding Tcl interface the mode can also be specified as r equivalent to fromec or w equivalent to toec These can be somewhat confusing as rea
145. returns TYPE ERROR if EC succeed w is handle amp ec xt double arr amp obj obj gt my_method else cerr lt lt unexpected type n 3 4 2 The method table Apart from the predefined method tables ec_xt_double_arr ec_xt_long_arr and ec xt char arr new ones can easily be defined The address of the table is used as a type identifier so when you get an external object back from ECL PS you can check its type to determine the kinds of operations you can do on it You can choose not to implement one or more of these functions by leaving a null pointer void 0 in its field 13 typedef void t_ext_ptr typedef struct void free t_ext_ptr obj t ext ptr copy t ext ptr obj void mark dids t ext ptr obj int string size t ext ptr obj int quoted int to string t ext ptr obj char buf int quoted int equal t ext ptr obji t ext ptr obj2 t ext ptr remote copy t ext ptr obj EC word get t_ext_ptr obj int idx int set t_ext_ptr obj int idx EC_word data t_ext_type free t ext ptr obj This is called by ECL PS if it loses a reference to the external data This could happen if the ECL PS execution were to fail to a point before the external object was created or if a permanent copy was explicitly removed with built ins like setval 2 erase 2 or bag dissolve 2 Note that an invocation of this function only means that one reference has been deleted while
146. rface Messages in EXDR for mat are sent in both directions according to the remote protocol to co ordinate the two processes Rpc This is used to send ec rpc goals from the remote process to ECL PS and return the results The goal is sent in EXDR format More than one remote attachment can be established in an ECL PS process Each attachment is independent and is a remote peer identified by its control connection Each remote attachment has two sides the ECL PS side and the remote side 89 At any one time either the ECL PS or the remote side has control When a side has control it is able to send messages to the other side via the control connection The side that does not have control waits for messages to arrive on the control connection On the ECL PS side execution is suspended while it does not have control In general once a control message is sent the control is passed to the other side and the side that sent the message waits for a reply message from the other side The ec rpc mechanism is designed to be the main way for the remote side to interact with the ECL PS side The remote side can send an ECL PS goal in EXDR format to be executed by the ECL PS side This can only be done while the remote side has control and when the goal is issued a message is sent via the control connection to the ECL PS side and control is passed to the ECL PS side Control is passed back to the remote side when ECL PS completes
147. rgument so it could be missed out After creating the queue it can be used on the ECL PS side The programmer can write to the queue and to send the data to the Tcl side the queue should be flushed 37 ECLiPSe code write myqueue hello flush myqueue When the queue is flushed as shown above then control is handed over to Tcl and the Tcl handler in this case ec stream to window sync would be invoked This reads the data on the queue hello and anything else that has been written since the last flush and puts it into the text widget textwin with the tag red The procedure is also called with the ECL PS stream number for the queue and the number of bytes sent as extra arguments The textwin widget and the tag red must be defined already in the Tcl program presumably red means printing the text in red colour if no tag is desired can be used The procedure ec stream to window sync is predefined in the interface but here is a slightly simplified version of it proc ec stream to window sync Tag Window Stream Length 1 set channel ec streamnum to channel Stream set data read channel Length Window insert end data Tag Window see end ECL PS Handler for From ECL PS Queue Currently the Tcl remote interface does not support ECL PS handlers which will be a data provider for from ECL PS queues Thus the event argument for ec queue create is currently a dummy argument that is ignored The a
148. ror streams are queues and have the ec stream output popup handler associated Similarly the input stream is a queue with the ec stream input popup handler attached These handler settings may be changed by the user s T cl code 26 5 5 2 ECL PS handlers A to ECL PS queue can be configured to raise an ECL PS event see event 1 and the User Manual chapter on event handling whenever the Tcl program writes something into the previ ously empty queue To allow that the queue must have been created with the event argument of ec queue create set e g Tcl set my out channel ec queue create my queue toec my queue event Assuming something was written into the queue from within Tcl code the ECL PS event will be handled if the queue is flushed on the Tcl side with the command ec flush Tcl puts my out channel hello ec flush ec streamname to streamnum myqueue If myqueue was empty then the puts would raise the event my queue event The ec flush transfer control over to ECL PS so that the event can be handled 5 6 Obtaining the Interface Type Generally the Tcl embedded and remote interfaces are designed to allow the user to write code that can be used via both interfaces However sometimes it may be necessary to distinguish the two This can be done via ec interface type returns embedded for the embedding interface and remote for the remote interface 5 7 Type conversion between Tcl and ECL PS EXDR ECL PS E
149. rovides a single method rpc Remote Predicate Call for executing goals in the ECL PS This method takes as a parameter the goal to be executed How to construct this parameter is dealt with in Section 8 4 1 Section 8 4 2 explains how to deal with the results returned by rpc Finally some more details about the execution of the goal are given in Section 8 4 3 8 4 1 Passing the goal parameter to rpc There are main two variants of rpc which differ in the class of the goal parameter The simplest way to use rpc is to pass it an instance of java lang String which should be the goal as it would be typed into the ECL PS command line Just like with the ECL PS command line the goal can be a conjunction of several subgoals An example of this is the use of rpc in the example program QuickTest java Also please note a full stop is not necessary The string parameter rpc variant is somewhat inefficient and it is also inflexible because creating goals dynamically or goals involving strings is tricky It should really only be used for short simple goals A more flexible and efficient alternative is to invoke rpc passing it a parameter object which implements the CompoundTerm interface discussed in Section 8 3 2 In this case the term becomes the goal Here is an example of using this version of rpc taken from DataExample1 java CompoundTerm a_term construct_term Get Eclipse to write the term to stdout and flush eclipse rpc new Compound
150. rts a C string to an ECL PS string The string is copied 113 EC_word const int const char converts a C string of given length to an ECL PS string The string is copied and can contain NUL bytes EC word const EC atom creates an ECL PS atom from an atom identifier EC word const long converts a C long to an ECL PS integer EC word const double converts a C double to an ECL PS double float EC word const EC ref amp retrieves the ECL PS term referenced by the EC ref see below EC word term const EC functor const EC word args EC word term const EC functor const EC word argl creates an ECL PS compound term from the given components EC word list const EC word hd const EC word tl Construct a single ECL PS list cell EC word list int n const long Construct an ECL PS list of length n from an array of long integers EC word list int n const char Construct an ECL PS list of length n from an array of chars EC word list int n const double Construct an ECL PS list of length n from an array of doubles EC word array int const double creates an ECL PS array a structure with functor of appropriate arity of doubles from the given C array The data is copied EC word matrix int rows int cols const double creates an ECL PS array size rows of arrays size cols of doubles from the given C array The data is copied EC word handle const t ext type cl con
151. s These two functions provide an alternative method for posting goals and retrieving results They are intended for applications with a simple structure that require only infrequent call return style 125 control transfers and little information passing between ECL PS and C It is less powerful and less efficient that the primitives described above int ec_exec_string char ec_ref Vars let ECL PS execute a goal given in a string ECL PS syntax Return value is PSUCCEED or PFAIL depending on the result of the execution If successful Vars holds a list mapping the variables names within the string to their values after execution int ec var lookup ec ref Vars char pword pw Lookup the value of the variable with the given name Vars is a list as returned by ec exec string 126 Appendix D Foreign C Interface This library loaded with lib foreign allows to use external functions written for Quin tus or SICStus Prolog or to interface C functions which are independent of ECL PS It accepts the syntax and semantics of the predicates foreign 3 load foreign files 2 and load foreign files 2 of Quintus SICStus Since their external interface is incompatible with the ECL PS one this library generates a C source file which converts the ECL PS interface into the foreign one by defining a new C function for every C function defined in the foreign interface Note that this approach uses more C code but it is still more efficient
152. s a solution to a set of posted goals and we print out the value of Pred otherwise EC resume returns EC fail to indicate that no more solutions to any set of posted goals is available It is possible also to cut such search So for example one could modify the example above to only print the 10th answer Initially one simply fails but at the tenth solution one cuts further choices Then one prints the value of Pred include eclipseclass h main X ec init EC ref Pred Choice int i 0 post goal term EC functor current built in 1 Pred while EC succeed EC resume Choice 1 if i 10 x Choice cut to break post goal term EC atom fail post goal term EC functor writeln 1 Pred EC resume ec_cleanup 0 When EC_resume is called with an EC_ref argument this is for data returned by the EC_resume If the return code is EC_succeed The EC_ref is set to a choicepoint identifier which can be used for cutting further choices at that point 2 3 2 Asynchronous events The posting of goals and building of any ECL PS terms in general cannot be done asyn chronously to the ECL PS execution It has to be done after the EC_resume function has returned Sometimes it may be necessary to signal some asynchronous event to ECL PS for example to implement a time out To do this one posts a named event to ECL PS At the next synchronous point within the eclipse execution the
153. s an ECL PS list of integers containing the chars in the given array The data is copied pword ec listofdouble int const double creates an ECL PS list of doubles containing the doubles in the given array The data is copied pword ec arrayofdouble int const double creates an ECL PS array a structure with functor of appropriate arity of doubles from the given C array The data is copied pword ec matrixofdouble int rows int cols const double creates an ECL PS array size rows of arrays size cols of doubles from the given C array The data is copied pword ec handle const t ext type const t ext ptr creates an ECL PS handle that refers to the given C data and its method table pword ec newvar creates a fresh ECL PS variable pword ec nil creates an ECL PS nil ie the empty list Auxiliary functions to access the ECL PS dictionary dident ec did char int looks up or enters the given string with arity into the ECL PS dictionary and returns a unique identifier for it char DidName dident returns the name string of the given dictionary identifier int DidArity dident returns the arity of the given dictionary identifier C 2 Decomposing ECL PS terms in C The following group of functions type check an ECL PS term and retrieve its contents if it is of the correct type The return code is PSUCCEED for successful conversion If a variable was encountered instead INSTANTIATION FAULT is r
154. s as well as subsequent waking will only happen once control is returned to ECL PS int EC word unify EC word Similar but a method of EC word B 5 Operations on ECL PS Data Interfaces to some basic operations on ECL PS Data int compare const EC word amp pwl1 const EC word amp pw2 Similar to the compare 3 built in predicate returns 0 if the arguments are identical a negative number if pwl is smaller than pw2 and a positive number if pw1 is greater than pw2 in the standard term ordering int EC word schedule suspensions int Similar to the schedule suspensions 2 built in predicate Waking will only happen once control is returned to ECL PS and the wake 0 predicate is invoked Return code is EC succeed or an error code B 6 Initialising and Shutting Down the ECL PS Subsystem These are the functions needed to embed ECL PS into a C main program int ec init Initialise the ECL PS engine This is required before any other functions of this interface can be used int ec cleanup Shutdown the ECL PS engine B 7 Passing Control and Data to ECL PS from C These are the functions needed to embed ECL PS into C code void post goal const EC word void post goal const char post a goal constraint that will be executed when ECL PS is resumed int EC resume EC word FromC EC ref amp ToC int EC resume EC word FromC 117 int EC_resume resume execution of the ECL PS engine All posted goals wi
155. s be success except when an asynchronous ECL PS thread is still running in which case the return value is running and it is undefined whether the events may have been handled by that thread or not first create an ECL PS queue stream using ECL PS s open 3 or open 4 predicate then connect that stream to a Tcl channel by invoking the ec queue connect command from within Tcl code ec queue connect eclipse stream name mode command Creates a Tcl channel and connects it to the given ECL PS stream eclipse stream name can be a symbolic name or the ECL PS stream number The mode argument is either r or w indicating a read or write channel The procedure returns a channel identifier for use in commands like puts read ec read exdr ec write exdr or close The channel identifier is of the form ec queueX where X is the ECL PS stream number of the queue This identifier can either be stored in a variable or reconstructed using the T cl expression ec queue ec stream nr eclipse stream name If a command argument is provided this command is set as the handler to be called when data needs to be flushed or read from the channel see ec set queue handler 29 ec_set_queue_handler eclipse_stream_name mode command Sets command as the Tcl handler to be called when the specified queue needs to be serviced from the Tcl side Unlike ec_queue_connect this command does not create a Tcl channel The mode argument is either r or w indicati
156. s sent when ECL PS requests input from a remote syn chronous queue and the data is not available in the queue s buffer ECLiPSe Remote ECLiPSe Remote ren Aushio O L L bytes via Q reno ayshior data via Q anid vield resume resume This interaction is triggered when the ECL PS side attempts a read operation on the empty buffer of a peer queue The operation is suspended and control is yielded to remote side so that it can provide the required data There should be a data provider handler associated with the queue on the remote side This handler should obtain the data and send the data to the ECL PS side The data will arrive from the remote side via a rem flushio message which initiates a remote flushio interaction nested within the ECL PS waitio interaction The data arrives on the socket associated with the remote peer queue Queue and is automatically copied by ECL PS into the peer queue buffer Control is then yielded back to the remote side completing the flushio interaction The remote side then hands control back to ECL PS side by the resume message The suspended read operation is resumed on the now non empty buffer The remote flushio interaction is described in more detail in its own section The main difference between a remote flushio initiated on the remote side and one initiated by an ECL PS waitio described here is that there must not be a data consumer handler on the
157. s than the synchronous queues They can also be more efficient in that there is no buffering of the data is performed by the interface 6 6 1 Queue Data Handlers The processing of data on queues synchronous and to some extent asynchronous can be per formed via handlers A handler is a piece of code a procedure in Tcl a goal in ECL PS whose execution is data driven it is invoked to deal with the transfer of data on a queue on their respective sides 35 In ECL PS the handler goal is invoked using the events mechanism That is an event is raised and the event handler goal associated with the event see set_event_handler 2 is then executed when ECL PS has control A handler can be called under two situations Data consumer To consume data that has been sent over from the other side Here the other side has sent data over the queue invoking the handler The handler is expected to read the data off the queue and process it An example of a data consumer handler is a Tcl handler which is invoked when the ECL PS side sends data that is intended to be displayed on a Tcl window The handler would be invoked to read the data off the queue and display it on the window Data provider To provide data that has been requested by the other side In this case the handler is expected to generate the data and write the data onto the queue and send it to the other side For example on the Tcl side a Tcl handler might be invoked to ask for i
158. sEclipse to terminate both the child ECL PS process and our association with it Once the destroy method has been invoked the invocation of any methods on the destroyed OutOfProcessEclipse object which require use of the ECL PS engine will throw an EclipseTer minatedException Unlike EmbeddedEclipse invoking destroy on an OutOfProcessEclipse does not affect our ability to create new OutOfProcessEclipse instances during the lifetime of the Java virtual machine If the child process ECL PS crashes or is killed while ECL PS has control the Java thread which handed control to ECL PS should throw an EclipseTerminatedException If this happens while Java has control usually the next invocation of a method on the OutOfProcesEclipse should throw an EclipseTerminatedException although it is possible that some operations will throw a different class of IOException If this should happen it is worth calling the destroy method to do a final clean up 8 6 3 Connecting to an existing ECL PS engine using RemoteEclipse In some applications for example where Java is used to visualise search in ECL PS the life of the ECL PS engine may begin before the connection with Java is initialised or end after the connection with Java is terminated Furthermore it may also be useful for the eclipse engine 78 and the Java virtual machine to be running on physically separate computers for example if the ECL PS tasks are being executed on a compute server but
159. se ec running to check whether there is not a thread still running ec flush stream nr nbytes flushes the Tcl end of a to ECL PS queue see section 5 4 that has the ECL PS stream number stream nr Control is then briefly transferred to ECL PS so that any events that are raised can be handled Afterwards the control is passed back to Tcl nbytes is a dummy argument and is provided for compatibility with the Tcl remote interface only 5 4 Communication via Queues The most flexible way of passing data between ECL PS and Tcl is via the I O facilities of the two languages ie via ECL PS queue streams which can be connected to Tcl channels Currently a communication channel between ECL PS and Tcl is created from Tcl which appears as an ECL PS queue in ECL PS and a channel in Tcl The queue has a symbolic name and a stream number in ECL PS and has a channel name in Tcl Facilities are provided to interconvert between these names Queues pass data between ECL PS and Tcl in one direction either from ECL PS to Tcl from ECL PS or from Tcl to ECL PS to ECL PS Queues are created with the direction specified The queues should be viewed as communication channels data is written to the queue and it only becomes available to the other side when the queue is flushed This is done by calling the predicate flush 1 on the ECL PS side and by invoking ec flush on the Tcl side The flush also has the effect of briefly transferring
160. should get a single line of output hello world How QuickTest java works is explained in Section 8 2 8 2 Functionality overview A closer look at QuickTest java To give a broad overview of how the Java ECL PS Interface works we take a closer look at QuickTest java Here is the Java source code from QuickTest java import com parctechnologies eclipse import java io public class QuickTest public static void main String args throws Exception 62 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 The structure of the main method in QuickTest java contains elements which will appear in any Java code which uses the Java ECL PS interface These are as follows Always import the com parctechnologies eclipse package Note the first line using import We need to have this in every Java source file which uses the Java ECL PS Interface so that it can load classes from the package Declare a reference to an EclipseConnection or an EclipseEngine EclipseConne
161. sking peer Note that events are not processed while the peer does not have control The Tcl command update is therefore called each time the peer is given control to allow any accumulated events to be processed As long as the peer is given control frequently enough then any interactions with the peer would appear to be continuous The handlers are invoked with the type of the multitasking phase supplied as the first argument This will for example allow the start handler to determine if it is interested in this multitasking phase They can also set one of the following return codes continue indicates that the peer wants to continue the multitasking phase In particular this should be returned by the start handler if it is interested in the multitasking 56 phase Note that the multitasking phase is not guaranteed to continue as it can be terminated by another multitasking peer terminate indicates the termination of a multitasking phase The multitasking phase will enter the end phase where the end handlers will be invoked once per peer before the multitasking phase finishes For example here is the start handler used in the Tk development tools proc tkecl multi_start_handler type switch type tracer multitasking phase is tracer only do handling of port if the tracer window exists if winfo exists ec_tools ec_tracer tkecl handle_tracer_port_start set of_interest continue default set of_i
162. st t ext ptr data Construct an ECL PS handle for external data attaching the given method table EC word newvar Construct a fresh ECL PS variable EC word nil Construct the empty list 114 B 2 Decomposing ECL PS terms in C The following methods type check an ECL PS term and retrieve its contents if it is of the correct type The return code is EC succeed for successful conversion an error code otherwise int EC word is atom EC atom checks whether the ECL PS pword is an atom and if so return its atom identifier int EC word is string char checks whether the EC word is a string or atom and converts it to a C string This string is volatile ie it should be copied when it is required to survive resuming of ECL PS int EC word is string char long checks whether the EC word is a string or atom and converts it to a C string This string is volatile ie it should be copied when it is required to survive resuming of ECL PS The string s length is returned in the second argument int EC word is long long checks whether the EC word is a word sized integer and if so returns it as a C long int EC word is double double checks whether the ECC word is a floating point number and if so returns it as an C double int EC word is list EC word amp EC word amp checks whether the EC word is a list and if so returns its head and tail int EC word is nil checks whet
163. t handler 7 4 Example Here we present a simple example use of the Tcl peer multitasking facilities The full programs Tcl and ECL PS code are available in the ECL PS distribution as example multi ecl and example multi tcl The Tcl program uses the remote Tcl peer interface to create a window that interacts with the ECL PS process it is attached to Multiple copies of the program can be run and attached to the same ECL PS process with a different remote peer Each window has three buttons e run a button to send an ERPC goal to ECL PS in this case a simple writeln with the peer name e end a button to end interaction with ECL PS and return control to ECL PS e reg a button to toggle the registration deregistration of the peer for peer multitasking The program interacts with ECL PS when the run button is pressed This can be done either during a peer multitasking phase or when the program s specific peer is given control on its own When the peer is given control on its own only it can interact with ECL PS while during peer multitasking all the multitasking peers the copies of the program that are running can interact with ECL PS i e the run buttons in all the windows can all be pressed After attaching to ECL PS with ec remote init the program sets various handlers for the handing of control between ECL PS and itself with ec running set commands ec running set commands ec start ec end disable buttons The
164. t n EC word pw create a data structure capable of holding n non volatile references to ECL PS data items They are all initialised with the value pw which must be of a simple type EC refs destroy the ECL PS references It is important that this is done otherwise the ECL PS garbage collector will not be able to free the references data structures which may even tually lead to memory overflow EC word EC refs operator int i return the ECL PS term referred to by the i th reference void EC refs set int i EC word new assign the term new to the i th reference This is a backtrackable operation very similar to setarg 3 EC_word list EC_refs amp creates an ECL PS list containing all the elements of the EC refs EC ref EC ref EC word pw EC_ref analogous to the corresponding EC_refs constructors destructor EC_ref amp operator const EC_word assign a value to the EC_ref EC_word const EC_ref amp retrieves the ECL PS term referenced by the EC ref B 4 Passing Data to and from External Predicates in C These two functions are only meaningful inside C functions that have been called from ECL PS as external predicates EC word EC_arg int i If inside a C function called from ECL PS this returns the i th argument of the call 116 int unify EC_word EC_word Unify the two given pwords Note that if attributed variables are involved in the unifi cation the associated unification handler
165. t of the way it is interfacing with Java there is a unified technique in ECL PS for interfacing to Java and other non ECL PS programs based on the concept of a peer A peer is a computation environment which is external to ECL PS either in the sense of being a different computer language or being a different process possibly on a different machine When ECL PS is communicating with one or more Java virtual machines using the Java ECL PS interface including cases where ECL PS is embedded it stores some global information to keep track of each peer 74 Each peer of the ECL PS engine is indexed within ECL PS by a unique peer name which is an atom This is set during the initialisation of the connection between ECL PS and Java the details vary according to the Java class used to make the connection The peer name is used in those ECL PS predicate calls related to the peer connection In particular those related to the opening and closing of peer queues see Section 8 5 1 The EclipseConnection interface includes the method getPeerName which can be used to retrieve this name on the Java side 8 6 2 Creating and managing ECL PS engines from Java There are at present two options for creating an ECL PS engine from Java With EmbeddedE clipse the engine takes the form of a dynamically loaded shared library within the Java virtual machine With OutOfProcessEclipse it is a separate child process of the Java virtual machine These t
166. t_yi This message is sent as an acknowledgement to the disconnect message Once the dis connect yield is sent the connection is considered terminated and the ECL PS side will close all the connections and clean up After the clean up abort is called This is done because the application on the ECL PS side such as the remote development tools may be deep inside some interaction loop with the remote side and abort is the most general way of escaping from such a loop It can be caught see remote yield 1 in section 10 6 if the user wants a more graceful termination Messages from remote side to ECL PS side resume this message hands over control from remote side to ECL PS side This is used to either implicitly return control to the ECL PS side at the end of an interaction initiated from the ECL PS side or to explicitly hand over control to the remote side ECLiPSe Remote ECLiPSe Remote resume ec flushio Q L L bytes via Q resume ECL Remote ECL Remote ec waitio Q ec waitio rem flushio Q L L bytes via Q scit BasbiotO data via Q yield yield resume resume ECLiPSe Remote socket client P N T D socket connect N S socket accept N Q ECLiPSe Remote queue close Q resume resume rpc this message is sent before the remote side sends an ec rpc goal on the rpc connection 102 yield answer via rpc After sending th
167. ta on the Tcl side on a pop up window The Tcl side GUI has just one button which allows the application to terminate This but ton is disabled when ECL PS side has control and this is done by setting up the appropriate call backs to disable and enable the button in ec running set commands on the Tcl side On disconnection which can be initiated either by pressing the button on the Tcl side or by quitting from ECL PS the handlers for disconnection ensures that both the ECL PS and Tcl program terminates 50 6 9 Differences From the Tcl Embedding Interface The remote Tcl interface is designed to be largely compatible with the embedded Tcl interface so that a user GUI can be written that allows either interfaces to be used while sharing most of the code in both ECL PS and Tcl An example of this is the Tkeclipse development tools Some remote specific code would need to be written This includes code to handle the connection and disconnection of the Tcl and ECL PS sides In addition the user may need to provide code to restrict the interaction within the Tcl Tk GUI when control is transferred to ECL PS Aside from this the rest of the code should be reusable if the user exercises some care The supported compatible methods of communicating between Tcl and ECL PS in the two interfaces is via the ec rpc calls and the use of the I O queues The ec rpc mechanism should behave the same in both interfaces For the queues there are some diff
168. tails The use queues flag eclipse use queues If false the default case the ECL PS en gine s standard streams stdin stdout and stderr will be connected to the standard streams of the JVM So for example if as in QuickTest java a message is written to stdout from within ECL PS this will appear on the stdout stream of the JVM Simi larly if ECL PS requests input from the stdin stream input will be requested from the stdin stream of the JVM If the flag is set true FromEclipseQueue and ToEclipseQueue objects are used to represent the ECL PS s standard streams The peer name eclipse peer name is the peer name by which the Java side can be refer enced within ECL PS for example when queues are created from the ECL PS side By default the peer name for the Java side when using an EmbeddedEclipse or an OutOfPro cessEclipse is host Using EmbeddedEclipse This section discusses issues specific to using the EmbeddedEclipse class With EmbeddedEclipse the ECL PS engine is a dynamically loaded native library in the Java virtual machine Figure 8 1 shows this deployment model in UML notation The important consequences of this deployment model are e The ECL PS engine shares memory and other resources with Java e Only one such engine can exist in a Java virtual machine at any one time e Communication between Java and ECL PS is very efficient Initialising an EmbeddedEclipse The embedded ECL PS which runs within the
169. tasking phase is started by calling the predicate peer do multitask 1 in ECL PS To participate in peer multitasking a peer must be registered initialised for peer multitasking This is done by executing the procedure ec multi peer register from Tcl Once registered the peer will take part in subsequent multitasking phases 55 The registration can set up three user defined handlers the start handler the interact handler and the end handler During a multitasking phase control is handed over to a multitasking peer which invokes one of these handlers and when the handler returns control is handed to the next multitasking peer The interact handler is normally invoked except at the start first and end last of a multitasking phase In these cases the start and end handlers are invoked respectively A type specified in the call to peer_do_multitask 1 is associated with every multitasking phase to allow multitasking phases for different purposes distinguished by different type s This type is passed to the handlers as an argument At the start of a multitasking phase a peer should indicate if it is interested in this particular multitasking phase or not If no peer is interested in the multitasking phase then the multitasking phase enters the end phase after the initial round of passing control to all the multitasking peers i e control is passed one more time to the multitasking peers this time invoking the end ha
170. the different environments to make the integration as close as possible Example sources can be found in the ECL PS installation directory under doc examples Chapter 2 Calling ECL PS from C This chapter describes how ECL PS can be included in an external program as a library how to start it and how to communicate with it Code examples are given in C For the equivalent C functions please refer to chapter C 2 1 To get started This section is about the prerequisites for working with ECL PS in your development environ ment The directory structure the libraries and the include files are described 2 1 1 Directories The libraries and include files needed to use ECL PS as an embedded component are available under the ECL PS directory which was set up during installation If you have access to a stand alone ECL PS it can be found using the following query at the ECL PS prompt eclipse 1 get flag installation directory Dir Dir usr local eclipse yes eclipse 2 We will assume from here that ECL PS was installed in usr local eclipse You would find the include files in usr local eclipse include SARCH and the the libraries in usr local eclipse lib SARCH where ARCH is a string naming the architecture of your machine This can be found using the following ECL PS query eclipse 2 get flag hostarch Arch Arch sun4 yes eclipse 3 You will need to inform your C or C compiler and
171. the copy function indicates that a reference is added copy t ext ptr obj This is called by ECL PS when it wants to make a copy of an object This happens when calling ECL PS built ins like setval 2 or recordz 2 which make permanent copies of data The return value is the copy If no copy method is specified these operations will not be possible with terms that contain an object of this type A possible implementation is to return a pointer to the original and e g increment a reference counter and decrement the counter in the free method correspondingly mark dids t ext ptr obj This is called during dictionary garbage collection If an exter nal object contains references to the dictionary dident then it needs to mark these as referenced string size t ext ptr obj int quoted to string t ext ptr obj char buf int quoted When ECL PS wants to print an external object it calls string size to get an estimate of how large the string would be that represents it This is used by ECL PS to allocate a buffer The string representation must be guaranteed to fit in the buffer Finally the to stringO function is called This should write the string representation of the object into the buffer equal t ext ptr objl t ext ptr obj2 This is called when two external objects are unified or compared Prolog views the external object as a ground atomic element remote copy t ext ptr obj This is called by parallel ECL PS when it needs
172. the same as the one previously recorded for the remote side If so the ECL PS will finish creating the ECL PS side of the queue If not the connection is closed and the operation is considered to have failed If Status from the socket connect message is fail then the ECL PS side will clean up the preparation for the peer queue The ECL PS side then returns control to the remote side via a socket accept message socket accept Name Queue 100 Name is again the name of the queue and Queue the stream id If the accept was un successful or if Status for socket_connect was fail then Queue will be the atom fail indicating that the peer queue connection was unsuccessful The remote side should then record the id Queue for later use it is needed for the control messages connected with this peer queue If instead fail was received then the remote side should clean up the attempted queue connection When the remote side has finished the final stage of the connection control is returned to the ECL PS side via a resume message and the socket client interaction completes Note that the socket connect and socket accept messages are always exchanged dur ing a socket client interaction even if the connection failed on the remote side before socket connect is sent They also can only occur in this context If these messages occur in any other occasion an error should be raised queue close Queue this message is sent when the ECL
173. this event is invoked when the rem flushio message is received The event handler goal in this case is invoked with the culprit argument being the term rem flushio Queue Length It is up to the user defined event handler goal to properly read the data queue create Name Type Dir Event this message is sent when the remote side wish to initiates the creation of a new peer queue Name is the name of the peer queue Type is its Type sync for synchronous async for asynchronous Dir is the data direction fromec or toec and Event is the name of the event that will be raised for the event handler goal on the ECL PS side if no event is to be associated with the queue this should be the empty atom ECLiPSe Remote ueue create N T D E socket client P N T D socket connect N S socket accept N Q resume yield Control is handed over to ECL PS side which should then set up a new server socket for connecting the socket stream for the peer queue Once this server socket is set up the creation of the queue proceeds via a socket client interaction from the ECL PS i e the ECL PS side sends a socket client message For more detail see the description for the socket client message At the end of the socket client interaction the peer queue would be established and ECL PS side has control The ECL PS side will yield control back to the remote side completing the queue create interaction Note th
174. tle s ces Sorti m e Te uS eoe nhe e REA 5 6 Obtaining the Interface Type 22r s 5 7 Type conversion between Tcl and ECL PS 0 00 000005 5 8 Incompatible and obsolete commands Remote Tcl Interface 6 1 Basic Concepts of the Interface 22h 6 2 Loading the Interface 2 222 leen 6 8 Attaching and Initialising the Interface a a a a a a 6 3 1 A Note on Security au iasa ie lerne 6 4 Type Conversion Between Tcl and ECL PS 0 0 000005 6 5 Executing an ECL PS Goal From Tel 2 0 ee 6 6 Communication via Queues 2 6 6 1 Queue Data Handlers 2 0 2 a 6 6 2 Synchronous Queues 2 0 e 6 6 3 Asynchronous Queues 2 2 rs 6 6 4 Reusable Queue Names 2 s 6 6 5 Translating the Queue Names 2 2 002 ee 6 7 Additional Control and Support 000000 eee eee 6 7 1 Initialisation During Attachment leen 6 7 2 Disconnection and Control Transfer Support 6 8 Example 2 aur pre oh Sit LS eh Goce ee Pete es HOS 6 9 Differences From the Tcl Embedding Interface Tcl Peer Multitasking Interface ed IGFOAUGUION C 3 eve X Bunny uoi ahs Seah ah hake eat eet SUME EE UM ES ETT dies 1 2 Loading the interface e ood Lugo ue owed Eee gk ee dnd Ae fad OVervieWw s e Sch Rome ee ee Be foem od Sete Pw tee 7 3 1 Summary of Tcl Commands 0 202000 040 TA EXAM plenis ette Aa as
175. to make a copy of an object in another worker If the object is in shared memory this method can be the same as the copy method get t ext ptr obj int idx Returns the value of a field of the C object This methods gets invoked when the ECL PS predicate xget 3 is called The mapping of index values to fields is defined by the get set method pair 14 set t ext ptr obj int idx EC word data Set the value of a field of the C object This methods gets invoked when the ECL PS predicate xset 3 is called The mapping of index values to fields is defined by the get set method pair Example of the simplest possible user defined method table t ext type my type NULL NULL NULL NULL NULL NULL NULL NULL NULL my struct data in creating a handle for data in EC word w handle amp my type amp data in checking a handle and extracting the data pointer my struct data out if EC_succeed w is handle amp my type amp data out data out my method else cerr lt lt unexpected type n 15 16 Chapter 4 External Predicates in C and C 4 1 Coding External Predicates External Predicates are C C functions that can be called like predicates from ECL PS Two following extra interface functions are provided for this purpose EC_word EC_arg int i returns the i th argument of the predicate call pword ec_arg int i same for C int unify EC_word EC_word unify two pwords The return c
176. to send an ECL PS term that matches the one specified in calling the predicate This is done before the Tcl side is given the ability to run rpc goals on the ECL PS side It is also possible to limit the remote connection to the same machine as the ECL PS process by specifying localhost as the host name in the Host Port address of remote connect 3 The Tcl side must also use localhost for the Host name in its client connection Each peer queue is created by creating a new server socket on the ECL PS side and then accepting a client connection from the Tcl side The accept command is told where the client connection is from and the client host is checked against the client s host from the attachment to ensure that the same host has been connected If not the ECL PS side will reject the particular connection At this point the security has probably been compromised and the two side should disconnect Note also that by default none of the information sent through the queues between the remote side and the ECL PS side is encrypted If the programmer requires these communication channels to be secure then such encryptions need to be provided by the programmer 6 4 Type Conversion Between Tcl and ECL PS The EXDR ECL PS External Data Representation see chapter 9 representation is fully sup ported by the interface The same type conversions commands as in the embedding Tcl interface described in section 5 7 ec write exdr ec r
177. tream nr length Inserts all the current contents of the specified queue at the end of the existing tert widget using tag as the tag for the text For data transfer from Tcl to ECL PS the queue can be used either asynchronously or syn chronously If the queue is used asynchronously then the standard Tcl command flush should be used to flush the queue There would not be any transfer of control and so there would not be an immediate corresponding read on the ECL PS side In fact no handler would be invoked automatically on the ECL PS side even when control is transferred Output and flush operations do not block on the T cl side as the Tcl side of the queue is put into non blocking mode so that the data is buffered and the operations carried out when they will not block It is the programmer s responsibility to write and call the code to read the data from the queue on the ECL PS side when the ECL PS side is given control This asynchronous use to send data to ECL PS should be useful when the queue is used as an auxiliary data channel where the main data is sent either via ec rpc or another queue The desired effect is that data can be sent on the auxiliary channel without triggering processing on the ECL PS side until it is told to do so on the main data channel which would be handled synchronously To use the queue synchronously for to ECL PS data ec flush should be used to flush the queue on the Tcl side With ec flush control wi
178. trol is transferred to ECLiPSe proc disable button 1 b configure state disabled enable the terminate button when control is transferred back to Tcl proc enable button b configure state normal the initialisation procedure called when the remote side is attached this creates the gui_output from ECLiPSe queue and then uses an ec_rpc to cause the queue to flush at every newline proc initialise ec_queue_create gui_output fromec ec_rpc set_stream_property gui_output flush end_of_line this button initiates disconnection and terminates the Tcl program pack button b text Terminate command ec disconnect terminate only start and end commands given the others default to no commands ec running set commands disable button enable button disable button initially as ECLiPSe side has initial control disable button the attachment to ECLiPSe includes the initialisation ec init which creates the gui output queue The connection is at the fixed port address ec remote init localhost 5000 initialise Tcl side initially has control hand it over to ECLiPSe ec resume resume Figure 6 2 Example use of interface Tcl code 53 54 Chapter 7 Tcl Peer Multitasking Interface 7 1 Introduction This chapter describes how to use the peer multitasking interface with the Tcl peer interfaces The usage is the same regardless of if the Tcl interface is of the embedded or remote vari
179. troyed getEclipse can no longer be used during the lifetime of the JVM to initialise an embedded ECL PS engine In other words by invoking destroy one removes the ability to use embedded ECL PS engines within the current instance of the JVM Using OutOfProcessEclipse This section discusses issues specific to the OutOfProcessEclipse class With OutOfProcessE clipse the ECL PS engine is a child process of the Java virtual machine Figure 8 2 shows this deployment model in UML notation The important consequences of this deployment model are e The ECL PS engine uses separate memory and other resources depending on how the operating system allocates these between processes e Several instances of OutOfProcessEclipse can exist in a Java virtual machine at any one time e Communication between Java and ECL PS is less efficient TT Java virtual machine host Jaya virtual machine process eclipse OutOfProcessEclipse parentichild process 1 host peer ECLiPSe process Figure 8 2 UML deployment diagram for OutOfProcessEclipse Initialisation of an OutOfProcessEclipse OutOfProcessEclipse has a single constructor which takes an EclipseEngineOptions object as its only parameter See Section 8 6 2 for details of how to create and configure this object Unlike EmbeddedEclipse multiple OutOfProcessEclipse instances are allowed Termination of an OutOfProcessEclipse We invoke the instance method destroy O in Out OfProces
180. type only allows singleton anonymous variables which means that it is not possible to construct a term where a variable occurs in several places simultaneously The main use of these variables is as placeholders for result arguments in remote procedure calls 85 9 1 ECL PS primitives to read write EXDR terms The ECL PS predicates to create and interpret EXDR representation read from and write di rectly to ECL PS streams This means that EXDR format can be used readily to communicate via files pipes sockets queues etc write exdr 4 Stream Term This predicate writes terms in exdr format The type of the generated EXDR term is the type resulting from the natural mapping of the Eclipse terms Atoms are written as structures of arity 0 not as strings Note that all information about variable sharing variable names and variable attributes is lost in the EXDR representation read exdr Stream Term This predicate reads exdr format and constructs a corresponding Eclipse term Please refer to chapter 5 for the Tcl primitives and to chapter 8 for the Java primitives for manipulating EXDR terms 9 2 Serialized representation of EXDR terms The following is the specification of what is actually send over the communication channels This is all the information needed to create new language mappings for EXDR terms This definition corresponds to EXDR VERSION 2 ExdrTerm i V Version CompactFlag Term CompactFlag z G
181. u have a valid term The interface is designed to make it hard to construct terms with uninitialised sub terms which is what you would need if you were to construct the list starting with the first elements 3 1 5 Building ECL PS structures The term functor args function is used to build ECL PS structures A number of different functions each with a different number of arguments is defined so as not to disable C casting which would be the case if we defined a function with variable arguments making s 1 2 3 in C EC_functor s_3 s 3 EC_word w term s_3 1 2 3 The above interface is convenient for terms with small fixed arities for much larger terms an array based interface is provided making s 1 2 n 1 n EC word args n for int i20 i n i args i i 1 EC word w term EC_functor s n args 3 2 Converting ECL PS data to C data There are several aspects to examining the contents of a term These include decomposing compound terms such as lists and structures converting simple terms to C data types and testing the types of terms The functions for decomposing and converting check that the type is appropriate If it is they return EC succeed if not they return a negative error code 3 2 Converting simple ECL PS terms to C data types To convert from an ECL PS term to a C type you first have to declare a variable with that type For fixed size data types you can convert to double
182. ue_close eclipse_stream_name Closes the synchronous or asynchronous queue with the ECL PS name of ec_stream_name The queue is closed on both the Tcl and ECL PS sides and book keeping information for the queue is removed For compatibility with previous versions of the embedded Tcl interface the mode can also be specified as r equivalent to fromec or w equivalent to toec These can be somewhat confusing as read write status depends on from which side the queue is viewed a read queue in ECL PS is a write queue in Tcl 36 It is strongly recommended that the queues should be used for long term I O connections be tween the two sides and so the queues should not be created and closed on a short term basis For quick interchange of data it is recommended that the user use the ec_rpc mechanism Handlers for a Synchronous From ECL PS Queue Tcl Handler for From ECL PS Queue For a from ECL PS queue the Tcl handler com mand would be a data consumer This handler is initiated when ECL PS side initially has control and flushes the queue by calling flush 1 With a Tcl handler defined control is trans ferred to the Tcl side where command is invoked to consume the data When the handler finishes control is returned to the ECL PS side The general sequence of actions are ECL PS side Tcl side Writes to the from ECL PS queue Flush the from ECL PS queue Handler invoked to handle data on the from ECL PS queue ECL PS
183. use of ec flush inside a Tcl data provider handler the sequence of events that appears to the user is that the ec flush flushes the data and the Tcl side then continues executing Tcl code until the handler s execution is finished Control is then returned to ECL PS where the original read operation can now read the available data The actual sequence of event is slightly more complex for synchronous queues when ec flush is invoked control is actually transferred to ECL PS and the data flushed is then read into a buffer by ECL PS which then returns control to Tcl to continue the execution of the handler When the handler finally finishes control returns to ECL PS and the original read operation reads the data from the buffer and continues This extra complexity should be transparent to the programmer except when the intermediate ECL PS read to buffer does not complete e g because nbytes is greater than the actual amount of data sent The Tcl handler is specified by command in ec queue create command includes the name of the Tcl procedure to invoke and any user defined arguments When the handler is invoked an additional argument is appended the ECL PS stream number for the queue This command should get the data required output it onto the queue and call ec flush to flush the data to 39 ECL PS side If the command does not flush data to ECL PS ECL PS will print a warning and return control to Tcl side The following pre
184. vailable alternative is to use ec rpc to obtain the required information instead of reading from a from ECL PS queue an ec rpc should be called with argument s left to be filled in by the ECL PS side with the required data Handlers for a Synchronous To ECL PS Queue Tcl Handler for a To ECL PS Queue For a to ECL PS queue the Tcl handler command defined in ec queue create would be a data producer This handler is initiated when ECL PS side has control and reads from the to ECL PS queue which is initially empty With a Tcl handler defined control is transferred to the Tcl side where command is invoked to provide the data The handler should write the data to the queue and call the Tcl remote interface command ec flush to send the data to ECL PS side When the handler finishes control is returned to the ECL PS side and the read operation is performed to read the now available data The general sequence of actions are 38 ECL PS side Tcl side Reads an empty to ECL PS queue Handler invoked to supply data to the to ECL PS queue The data is written to the queue and flushed with ec flush ECL PS returns from the initial read operation reading the data supplied by the Tcl handler and continue execu tion the following code The Tcl remote interface command ec flush instead of the standard Tcl flush command should be used to flush a queue so that the data would be transferred and processed on the ECL PS side
185. wly established ec rpc connection This is also sent in EXDR format This is designed to verify that the ec rpc connection is indeed connected to the ECL PS side 12 Remote side the remote side now has control Any user defined initialisations on the remote side can now be performed to make the remote side ready for the interaction The remote side has the control initially Note that user defined initialisations on the ECL PS side is also performed after sending the control name on the ec rpc connection After the initialisation ECL PS side will suspend and listen on the control connection for the remote side to give control back to the ECL PS side At the end of this the remote side should be ready for normal interaction with the ECL PS side 92 The remote connect 3 or remote_connect_accept 6 predicate wait for the control to be handed back by the remote side before exiting Thus when the predicate succeeds the remote side has been attached and properly initialised with ECL PS side having control The protocol does not specify how the remote side should be informed of the Host Port address for the initial socket connection The Address can be fixed before hand with the Address argument instantiated or the information can be transmitted either manually or via files In addition the remote process can be started from within ECL PS using the exec 3 command with the host and port supplied as arguments In accepting client s
186. wo options have in common that they are both initialised using an EclipseEngineOptions object and that both classes implement EclipseEngine Configuring an EclipseEngineOptions object Before an ECL PS engine is created using either option an EclipseEngineOptions object must be created and configured An instance of the EclipseEngineOptions class represents our con figuration choices for a new ECL PS engine The options can be specified by either looking them up in a java util Properties instance or by calling set methods on the EclipseEngineOptions instance In the first case you can either specify system properties by passing D command line options to the JVM or you can use an EclipseEngineOptions constructor which takes a Properties parameter Each option has a standard property name detailed below Once the EclipseEngineOptions object is created there are also set methods we can invoke on it to set the different options The ECL PS installation directory eclipse directory This must be the correct path of an ECL PS installation so that Java can find the files it needs to start ECL PS If an EclipseEngineOptions constructor is invoked without a directory having been set either using a constructor parameter or as a property an exception will be thrown The default module eclipse default module is the default ECL PS module where goals are executed If no setting is made then the default module will be eclipse
187. xternal Data Representation see also chapter 9 is a data encoding that allows to represent a significant subset of the ECL PS data types The following Tcl primitives are provided to handle EXDR format ec write exdr channel data format write an EXDR term onto the given channel The term is constructed using the data argument and the additional type information provided in the format argument If no format is specified it defaults to S string ec read exdr channel reads an EXDR term from the given channel and returns it as a Tcl data structure ac cording to its type Note that since Tcl does not have a strong type system some typing information can get lost in this process e g string vs atom ec tcl2exdr data format This is the low level primitive to encode the given data and type information in format to an EXDR string which is suitable for sending over communication links to ECL PS or other agents which can decode EXDR format If no format is specified it defaults to S string It is possible to use the same name for both the queue stream itself and the event This simplifies the event handler code because it receives that name as an argument 27 ec exdr2tcl exdr_string This is the low level primitive to decode an EXDR string It returns a Tcl data structure according to the type information encoded in the EXDR string Note that since Tcl does not have a strong type system some typing information can get lost i

pdf format

Contents

Download Pdf Manuals

Related Search

Related Contents