engine_join(+Engine, +Timeout, -Status)

Engine

An engine handle

Timeout

Timeout in seconds (integer or float), or the atom 'block'

Status

Output: engine status term

Description

Waits for an (asynchronously resumed) engine to stop executing, then returns its status. The status descriptors are the same as in get_engine_property/3 (except that 'running' does normally not occur). If the engine does not stop within Timeout seconds, the predicate fails. If the engine is already stopped at the time of the join, it succeeds immediately.

It is an error if the engine is running, but was not resumed in its own thread (e.g. it was resumed using engine_resume/3 by another thread). Moreover, one cannot join an engine that is running in the same thread as the caller of engine_join/3.

If multiple joins are waiting for the same engine, they will all succeed when the engine stops. In this special case, some of these joins may return the status 'running'.

If Timeout is the atom 'block', no timeout is used, the operation can block indefinitely, and never fails.

Instead of waiting for an engine to finish, the engine can use the report_to option to eagerly send a notification when it finishes. Such a notification means that the engine is ready to be joined.

NOTE: While blocked in engine_join/3, a thread does not respond to posted event goals (e.g. from engine_post/2 or event_after/2). In order to keep the thread responsive, one can replace

        engine_join(E, block, S)
    

        once (repeat, engine_join(E, 1, S))
    

Modes and Determinism

• engine_join(+, +, -) is semidet

Fail Conditions

Exceptions

(4) instantiation fault

Engine or Timeout is not instantiated

(5) type error

Engine is not an engine handle

(5) type error

Timeout is neither integer, float, nor the atom 'block'

(6) out of range

Timeout is a negative number

(181) engine not joinable

Engine running, but cannot be joined

Examples

    ?- engine_create(E, [thread]),
       engine_resume_thread(E, writeln(hello)),
       engine_join(E, block, Status).
    hello
    E = $&(engine,"376oe7")
    Status = true
    Yes (0.00s cpu)

    ?- engine_create(E, [thread]),
       engine_resume_thread(E, 1=2),
       engine_join(E, block, Status).
    E = $&(engine,"376oe7")
    Status = false
    Yes (0.00s cpu)

    ?- engine_create(E, [thread]),
       engine_resume_thread(E, yield(hello,_)),
       get_engine_property(E, status, Status1),
       engine_resume_thread(E, true),
       engine_join(E, block, Status2).
    E = $&(engine,"376oe7")
    Status1 = yielded(hello)
    Status2 = true
    Yes (0.00s cpu)

    ?- engine_create(E, [thread]),
       engine_resume_thread(E, (repeat,fail)),
       ( engine_join(E, 5, S) -> writeln(status=S) ; writeln(timeout) ).
    timeout

    E = $&(engine,"376oe7")
    S = S
    Yes (5.00s cpu)

See Also