5.4 Passing Goals and Control to ECLiPSe
The control flow between Tcl and ECLiPSe is conceptually thread-based.
An ECLiPSe goal is executed by using the ec_rpc mechanism. The
goal is posted from Tcl, and control is transferred automatically to
ECLiPSe to allow the goal to be executed. Control can also be explicitly
transferred to ECLiPSe 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.5, with implicit
transfer of control.
The related commands are the following:
-
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.8.
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 ECLiPSe code from Tcl,
and passing the results back (via output arguments) to Tcl.
- ec_running
checks whether an asynchronous ECLiPSe 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 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_flush ?stream_nr?
?nbytes?
flushes the Tcl end of a to-ECLiPSe queue (see
section 5.5) that has the
ECLiPSe stream number stream_nr. Control is then
briefly transferred to ECLiPSe 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.