[ 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 1st argument is the event number/identifier itself
       
- the 2nd argument is the culprit (a structure corresponding to
	   the call which caused it)
       
- the 3rd argument is the context module (or the lookup module
       	   if the context module is unknown)
       
- the 4th argument is the lookup module for the call
   
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
- set_event_handler(+, ++) is det
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