[ 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