engine_post(+Engine, +EventGoal)

Engine

An engine handle

EventGoal

Callable term, or event handle

Description

Posts an event goal to the specified engine. The receiving engine can be in any state. If the receiving engine is running, the event goal will be handled at the next synchronous point in execution, usually the next predicate call. If the receiving engine is stopped, the event will be handled immediately after it is resumed.

The goal can be given either as a callable term (in which case a copy of EventGoal will be executed on Engine), or as an event handle, as created with event_create/3.

The event goal should either succeed, throw an exception (throw/1), or exit the engine (exit/1). It makes little sense for the goal to fail, because it is inserted in an unknown position during execution and the scope of the failure is not known. These considerations are similar to those for after-events.

The most likely use for this mechanism is to abort an asynchronously running engine. But one could also cause the engine to initiate an exchange of information (via yield/2, streams or shared storage objects).

The following special EventGoals are handled more urgently than general ones:

throw(Ball)

will abort running code at synchronous points in execution, and additionally during certain built-in operations like long-running unifications.

exit(Code)

will exit running code at synchronous points in execution and during long-running built-ins. It will also immediately exit a stopped engine and free its resources.

abort

equivalent to throw(abort)

Modes and Determinism

• engine_post(+, +) is det

Modules

Examples

    % aborting an asynchronously running engine:
    ?- engine_create(E, [thread]),
       engine_resume_thread(E, (repeat,fail)),   % run forever
       sleep(1),
       engine_post(E, abort),
       engine_join(E, block, Status).

    E = $&(engine,"376oe7")
    Status = exception(abort)
    Yes (0.00s cpu)


    % exiting an asynchronously running engine:
    ?- engine_create(E, [thread]),
       engine_resume_thread(E, (repeat,fail)),   % run forever
       sleep(1),
       engine_post(E, exit(7)),
       engine_join(E, block, Status).
    E = $&(engine,"376oe7")
    Status = exited(7)
    Yes (0.00s cpu)


    % exiting a stopped engine:
    ?- engine_create(E, []),
       get_engine_property(E, status, S1),
       engine_post(E, exit(7)),
       get_engine_property(E, status, S2).
    E = $&(engine,"376oe7")
    S1 = false
    S2 = exited(7)
    Yes (0.00s cpu)

See Also