[ Event Handling | Reference Manual | Alphabetic Index ]

set_event_handler(+EventId, ++PredSpec)

Set an event handler PredSpec for the event EventId.
EventId
Atom or Integer.
PredSpec
Term of the form Atom/Integer, or defers(Atom/Integer).

Description

Assigns the procedure specified by PredSpec as the event handler for the event specified by EventId. The event name can be either an arbitrary atom or a valid error number (as returned by current_error/1).

An event handler which is used as an error handler can have 4 optional arguments:

The error handler is free to use less than 4 arguments.

Handlers for events raised by event/1 or posted to the system from the outside usually have no arguments or just the event name.

Events can be raised by

   - one of the builtins event/1, error/2 or error/3.
   - posting an event from external code using ec_post_event().
   - an interrupt whose handler has been specified as event/1.
The latter two have the effect of dynamically inserting an event/1 goal into the current execution at the next synchronous point, which is usually just before the next predicate call.

If the handler is specified as defers(Name/Arity), then the event has the defer-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

Modules

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

Exceptions

(4) instantiation fault
Either EventId or PredSpec is not instantiated.
(5) type error
EventId is neither atom nor integer.
(5) type error
PredSpec is not of the form Atom/Integer or defers(Atom/Integer).
(6) out of range
EventId is integer, but not a valid error number.
(6) out of range
PredSpec specifies an illegal handler arity.

Examples

Success:
    ?- event(hello).
    warning: no handler for event in hello
    yes.

    ?- set_event_handler(hello, writeln/1).    
    yes.

    ?- event(hello).
    hello
    yes.

See Also

current_error / 1, get_event_handler / 3, error / 2, error / 3, event / 1, reset_event_handler / 1, events_nodefer / 0