[ Engines and Threads | Reference Manual | Alphabetic Index ]

# engine_post(+Engine, +EventGoal)

Post an event goal to an engine

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

This predicate is sensitive to its module context (tool predicate, see @/2).

## 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

event / 1, event_after / 2, event_create / 3, engine_create / 2, engine_resume_thread / 2, engine_join / 3