next up previous index
Next: Communication via Queues Up: Embedding into Tcl/Tk Previous: Initialising the ECLiPSe Subsystem   Index

Passing Goals and Control to ECLiPSe

The control flow between Tcl and ECLiPSe is conceptually thread-based. An ECLiPSe goal is executed by first posting it and then transferring control via the ec_resume command.

The related commands are the following:

ec_post_goal goal ?format?

post a goal that will be executed when ECLiPSe is resumed. If no format argument is given, the goal is taken to be a string in ECLiPSe syntax. Note that (unlike with the C/C++ interface) it is not possible to retrieve any variable bindings from ECLiPSe after successful execution of the goal. To pass information from ECLiPSe to Tcl, use queue streams as described later on. Example:
	ec_post_goal {go("hello",27)}

If a format argument is provided, the ECLiPSe goal is constructed from goal data and format, according to the conversion rules explained in section 5.6. 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 ECLiPSe engine. This will lead to the execution of the corresponding event handler once the ECLiPSe 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_resume ?async?

resume execution of the ECLiPSe 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 ECLiPSe code. No parameters can be passed.

If the async parameter is 1 (default 0), the ECLiPSe 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 ECLiPSe is running, so the GUI does not freeze during computation. However, only one ECLiPSe thread can be running at any time, so before doing another call to ec_resume, ec_handle_events or ec_rpc one should use ec_running to check whether there is not a thread still running.

ec_handle_events

resume execution of the ECLiPSe 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 always be "success", except when an asynchronous ECLiPSe 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.

ec_running

checks whether an asynchronous ECLiPSe thread is still running. If that is the case, the only interface function that can be invoked realiably is ec_post_event.

ec_rpc goal ?format?

Remote ECLiPSe 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 nested and can be used from within Tcl queue event handlers.

If no format argument is given, the goal is assumed to be in ECLiPSe syntax. If a format argument is provided, the ECLiPSe goal is constructed from goal and format, according to the conversion rules explained in section 5.6.

On success, ec_rpc returns the (possibly more instantiated) goal as a Tcl data structure, otherwise "fail" or "throw" respectively.


next up previous index
Next: Communication via Queues Up: Embedding into Tcl/Tk Previous: Initialising the ECLiPSe Subsystem   Index

1999-08-06