## B.7 Prolog events

Version 8.1.9 introduces a uniform mechanism to listen to events that happen in the Prolog engine. It replaces and generalises prolog_event_hook/1 , a hook that was introduced to support the graphical debugger. The current implementation deals with debug, thread and dynamic database events. We expect this mechanism to deal with more hooks in the future.

prolog_listen(+Channel, :Closure)
prolog_listen(+Channel, :Closure, +Options)
  Call Closure if an event that matches Channel happens inside Prolog. Possible choice points are pruned as by once/1. Possible failure is ignored, but exceptions are propagated into the environment. Multiple closures can be associated with the same channel. Execution of the list of closures may be terminated by an exception. Options:
  as(Location)
    Location is one of `first` (default) or `last` and determines whether the new handler is exected as first or last.

  Defined channels are described below. The Channel argument is the name of the term listed below. The arguments are added as additional arguments to the given Closure.

  abort
    Called by abort/0.
  erase(DbRef)
    Called on an erased recorded database reference or clause. Note that a retracted clauses is not immediately removed. Clauses are reclaimed by garbage_collect_clauses/0, which is normally executed automatially in the `gc` thread. This specific channel is used by clause_info/5 to reclaim source layout of reclaimed clauses. User applications should typically use the PredicateIndicator channel.
  break(Action, ClauseRef, PCOffset)
    Traps events related to Prolog break points. See library `library(prolog_breakpoints)`
  frame_finished(FrameRef)
    Indicates that a stack frame that has been examined using prolog_current_frame/1, prolog_frame_attribute/3 and friends has been deleted. Used by the source level debugger to avoid that the stack view references non-existing frames.
  thread_exit(Thread)
    Globally registered channel that is called by any thread just before the thread is terminated.
  this_thread_exit
    Thread local version of the `thread_exit` channel that is also used by the `at_exit(Closure)` option of thread_create/3.
  PredicateIndicator(Action, ClauseRef)
    Track changes to a (dynamic) predicate. For example:

        :- dynamic p/1.
        :- prolog_listen(p/1, updated(p/1)).

        updated(Pred, Action, Context) :-
            format('Updated ~p: ~p ~p~n', [Pred, Action, Context]).

        ?- assert(p(a)).
        Updated p/1: assertz <clause>(0x55db261709d0)
        ?- retractall(p(_)).
        Updated p/1: retractall start(user:p(_12294))
        Updated p/1: retract <clause>(0x55db261719c0)
        Updated p/1: retractall end(user:p(_12294))

    asserta
    assertz
      A new clauses has been added as first (last) for the given predicate.
    retract
      A clause was retracted from the given predicate using either retract/1, erase/1 or retractall/1.
    retractall
      The begining and end of retractall/1 is indicated with the Action `retractall`. The context argument is `start(Head)` or `end(Head)`.
prolog_unlisten(+Channel, :Closure)
  Remove matching closures registered with prolog_listen/3.