[ ECLiPSe Event built-in.|Group Index| Full Index]

set_event_handler(+EventName, +PredSpec)

Set an event handler PredSpec for the event EventName.

+EventName
Atom or Integer.
+PredSpec
Term of the form Atom/Integer.

Description

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

An event handler which is used as an error handler can have 3 optional arguments: the 1st argument is the event number; the 2nd argument is the culprit (a structure corresponding to the call which caused it); the 3rd is the caller module or a free variable (if the module is unknown). The error handler is free to use less than 3 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.

Fail Conditions

None.

Resatisfiable

No.

Exceptions

(4) Instantiation fault
Either EventName or PredSpec is not instantiated.
(5) Type error
EventName is neither atom nor integer.
(5) Type error
PredSpec is not of the form Atom/Integer.
(6) Range error
EventName is integer, but not a valid error number.
(6) Range error
PredSpec specifies an illegal handler arity.
(60)
PredSpec is of the form Atom/Integer, but no such predicate has been defined.

Examples


Success:
    [eclipse 1]: event(hello).
    warning: no handler for event in hello
    yes.
    [eclipse 2]: set_event_handler(hello, writeln/1).    
    yes.
    [eclipse 3]: event(hello).
    hello
    yes.



See Also

current_error / 1, get_error_handler / 3, error / 2, error / 3, event / 1, reset_event_handler / 1