
engine_post(+Engine, +EventGoal)

   Post an event goal to an engine

Arguments
   Engine              An engine handle
   EventGoal           Callable term, or event handle

Type
   Engines and Threads

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
