
engine_resume(+Engine, ?Term, -Status)

   Resume execution of an engine

Arguments
   Engine              An engine handle
   Term                A term passed to the engine
   Status              Status term returned from the engine

Type
   Engines and Threads

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 --- Engine is not instantiated
     5 --- Engine is not an engine handle
   180 --- Engine is busy (running)
   182 --- 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
