[ 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