
set_event_handler(+EventId, ++PredSpec)

   Set an event handler PredSpec for the event EventId.



Arguments
   EventId             Atom or Integer.
   PredSpec            Term of the form Atom/Integer, or defers(Atom/Integer).

Type
   Event Handling

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 --- Either EventId or PredSpec is not instantiated.
     5 --- EventId is neither atom nor integer.
     5 --- PredSpec is not of the form Atom/Integer or defers(Atom/Integer).
     6 --- EventId is integer, but not a valid error number.
     6 --- 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
