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.
- 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.
- Location is one of
first (default) or
and determines whether the new handler is expected as first or last.
- Give the handler a name. A new registration using the same name replaces
the existing handler rather than adding a new handler. Names are local
to the Channel, i.e., different channels can use the same
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.
- Called by abort/0.
- Called on an erased recorded database reference or clause. Note that a
retracted clauses is not immediately removed. Clauses are reclaimed by
which is normally executed automatially in the
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
- Indicates that a stack frame that has been examined using
and friends has been deleted. Used by the source level debugger to avoid
that the stack view references non-existing frames.
- Globally registered channel that is called by any thread just before the
thread is terminated.
- Globally registered channel that is called by any thread after the
thread initialization and before running the thread's goal.
- Thread local version of the
thread_exit channel that is
also used by the
at_exit(Closure) option of
- PredicateIndicator(Action, Context)
- Track changes to a predicate. This notably allows tracking modifications
to dynamic predicates. The channel also allows tracking changes to
monotonic tables (section
7.8). Both monotonic and incremental tabling use this to track
predicates. Below is an example illustrating events from changing a
:- dynamic p/1.
:- prolog_listen(p/1, updated(p/1)).
updated(Pred, Action, Context) :-
format('Updated ~p: ~p ~p~n', [Pred, Action, Context]).
Updated p/1: assertz <clause>(0x55db261709d0)
Updated p/1: retractall start(user:p(_12294))
Updated p/1: retract <clause>(0x55db261719c0)
Updated p/1: retractall end(user:p(_12294))
- A new clauses has been added as first (last) for the given predicate. Context
is a clause reference. The hook is called after the clause has been
added. If the hook fails the clause is removed.
- A clause was retracted from the given predicate using either
or retractall/1. Context
is a clause reference. The hook is called before the clause is removed.
If the hook fails, the clause is not removed.
- The begining and end of retractall/1
is indicated with the Action
context argument is
- Issued when rolling back (discarding) a transaction. Action
is the local action being reverted and is one of
retract. Context is the involved
clause. See transaction/1
- A new answer was added to a tabled predicate. The context is the answer
term. Currently implemented for monotonic tabling only. Future
versions may also implement this for normal tabling. See section
- Remove matching closures registered with prolog_listen/3.