[ Event Handling | The ECLiPSe Built-In Predicates | Reference Manual | Alphabetic Index ]

# event_create(+Goal, ++Options, -EventHandle)

Create an ECLiPSe event from an arbitrary goal.

Goal
  An arbitrary goal
Options
  A list of atoms.
EventHandle
  A free variable

## Description

This creates an event from the goal provided, which can be raised with the standard event handling predicates (e.g. event / 1, event_after / 2 and event_after_every / 2) using the associated handle.

The event creation requires non-logical copying of the goal. As a result, if the goal contains variables, they lose their identity and are replaced with fresh ones.

The intended use of such events are for localised event handling or when it is necessary to pass ground parameters to the event goal, i.e. when the use of a global event handler is unnecessary or does not suffice.

It should be noted that the event handle is the only way to uniquely identify a given event. E.g. if an event has been scheduled as an after-event (using event_after/3 or events_after/2), it can only be cancelled by invoking cancel_after_event/2 with the correct handle.

The following options are recognised:

defers
  Give the event the defers-property. This means that event handling is automatically deferred on entering the event's handler, thus preventing other events from interrupting the handler. Such handlers must always explicitly invoke events_nodefer/0 before exiting in order to reenable event handling.

### Modes and Determinism

- event_create(+, ++, -) is det

### Modules

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

### Exceptions

(4) instantiation fault
  Goal is not instantiated
(5) type error
  Goal is not a valid goal
(5) type error
  EventHandle is not a free variable
(5) type error
  Options is not a list of atoms
(6) out of range
  Some element of Options is not a valid option

## Examples

        % Create and raise a single event
        ?-  event_create(writeln('Goodbye cruel world!'), [], Event),
        	writeln('Hello world!'),
    	event(Event).
        Hello world!
        Goodbye cruel world!
        Event = 'EVENT'(16'503f0238)
        Yes (0.00s cpu)

        % Raise events via a timer
        ?-  event_create(writeln('e1'), [], E1Event),
    	event_create(writeln('e2'), [], E2Event),
        	events_after([E1Event-every(0.2), E2Event-0.5]),
        	repeat, fail.
        e1
        e1
        e2
        e1
        e1
        ^C
        interruption: type a, b, c, e, or h for help : ? e1
        abort
        Aborting execution ...

        % By default, event handlers are allowed to interrupt each other,
        % which can make it seem that they are handled in reverse order:
        ?-  event_create(writeln('e1'), [], E1Event),
    	event_create(writeln('e2'), [], E2Event),
    	event([E1Event,E2Event]).	% raise both events together
        e2
        e1
        E1Event = 'EVENT'(16'ed9b0010)
        E2Event = 'EVENT'(16'ed770b20)
        Yes (0.00s cpu)

        % By default, event handlers are allowed to interrupt each other,
        % which can make it seem that they are handled in reverse order:
        ?-  event_create((writeln('e1'),events_nodefer), [defers], E1Event),
    	event_create((writeln('e2'),events_nodefer), [defers], E2Event),
    	event([E1Event,E2Event]).	% raise both events together
        e1
        e2
        E1Event = 'EVENT'(16'ed9b0010)
        E2Event = 'EVENT'(16'ed770b20)
        Yes (0.00s cpu)

## See Also

event_retrieve / 3, event / 1, event_after / 2, event_after / 3, event_after_every / 2, set_event_handler / 2, current_after_events / 1, cancel_after_event / 2, is_event / 1, events_nodefer / 0