[ Engines and Threads | Reference Manual | Alphabetic Index ]
engine_resume(+Engine, ?Term, -Status)
Resume execution of an engine
- Engine
- An engine handle
- Term
- A term passed to the engine
- Status
- Status term returned from the engine
Description
Resume execution of the given engine, and return with a status
code once execution has stopped. The computation is performed
by the same thread that is calling engine_resume/3.
This predicate can be used with any engine, independent of whether
the engine was created with or without the 'thread' option.
For details about the returned Status, see get_engine_property/3.
All status codes except 'running' are possible.
Term is an arbitrary term, a copy of which is is passed to the
resumed engine. The way the resumed engine interprets Term
depends on its status at resumption time:
- false and exception(_)
-
Term is interpreted as a goal, and called. This is the case
for a newly created engine.
- true
-
Term is also interpreted as a goal and called, but it forms a
conjunction with the previously succeeded goals (i.e. if it fails,
it backtracks into the goal given in the previous resume).
- yielded(_)
-
Term is unified with the second argument of the yield/2 call
in which the engine was stopped.
- flushio(_) and waitio(_)
-
Term is ignored.
- exited(_)
-
Engine cannot be resumed (error).
In the cases where Term is executed as a goal, note that the engine
works on a copy of Term, therefore any variable bindings performed
by the engine will not be visible to the caller of engine_resume/3.
Any results must be returned explicitly, either via yield/2, via
stream communication, or via nonlogical storage.
Modes and Determinism
- engine_resume(+, ?, -) is det
Modules
This predicate is sensitive to its module context (tool predicate, see @/2).
Exceptions
- (4) instantiation fault
- Engine is not instantiated
- (5) type error
- Engine is not an engine handle
- (180) engine not ready
- Engine is busy (running)
- (182) engine dead/exited
- Engine dead/exited
Examples
?- engine_create(E, []), engine_resume(E, writeln(hello), S).
hello
E = $&(engine,"376oe7")
S = true
Yes (0.00s cpu)
?- engine_create(E, [thread]), engine_resume(E, writeln(hello), S).
hello
E = $&(engine,"376oe7")
S = true
Yes (0.00s cpu)
?- engine_create(E, []), engine_resume(E, 3=4, S).
E = $&(engine,"376oe7")
S = false
Yes (0.00s cpu)
?- engine_create(E, []), engine_resume(E, throw(ball), S).
E = $&(engine,"376oe7")
S = exception(ball)
Yes (0.00s cpu)
?- engine_create(E, []), engine_resume(E, throw(ball), S).
E = $&(engine,"376oe7")
S = exception(ball)
Yes (0.00s cpu)
?- engine_create(E, []),
engine_resume(E, (member(X,[a,b]),writeln(X)), S1),
writeln(first_resume->S1),
engine_resume(E, fail, S2),
writeln(second_resume->S2),
engine_resume(E, fail, S3),
writeln(third_resume->S3).
a
first_resume -> true
b
second_resume -> true
third_resume -> false
See Also
engine_create / 2, engine_resume_thread / 2, get_engine_property / 3