[ Engines and Threads | Reference Manual | Alphabetic Index ]
engine_resume_thread(+Engine, ?Term)
Asynchronously resume execution of an engine
- Engine
- An engine handle
- Term
- A term passed to the engine
Description
Resume execution of the given engine in a separate thread.
The predicate returns immediately, while the resumed engine
enters the 'running' state. To wait for the engine to stop,
and to retrieve its status, use engine_join/3.
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 the status it was in:
- 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.
- running and 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_thread/2.
Any results must be returned explicitly, either via yield/2, via
stream communication, or via nonlogical storage.
It is recommended to use the [thread] option to create engines that
are intended to be resumed with engine_resume_thread/2 -- this will
create a physical thread eagerly, and any possible resource errors
will show up in engine_create/2. However, if an engine was not
created with this option, a thread will be created lazily the first
time it is resumed with engine_resume_thread/2.
Modes and Determinism
- engine_resume_thread(+, ?) 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)
Examples
?- engine_create(E, [thread]),
engine_resume_thread(E, writeln(hello)),
engine_join(E, block, Status).
hello
E = $&(engine,"375am7")
Status = true
Yes (0.00s cpu)
?- engine_create(E, [thread]),
engine_resume_thread(E, (writeln(hello),sleep(1),writeln(done))),
get_engine_property(E, status, Status1),
writeln(Status1),
engine_join(E, block, Status2).
running
hello
done
E = $&(engine,"375am7")
Status1 = running
Status2 = true
Yes (0.00s cpu)
See Also
engine_create / 2, engine_resume / 3, get_engine_property / 3