B.2 Intercepting the Tracer

prolog_trace_interception(+Port, +Frame, +Choice, -Action)

Dynamic predicate, normally not defined. This predicate is called from the SWI-Prolog debugger just before it would show a port. If this predicate succeeds the debugger assumes the trace action has been taken care of and continues execution as described by Action. Otherwise the normal Prolog debugger actions are performed.

Port denotes the reason to activate the tracer (`port' in the 4/5-port, but with some additions:

call

Normal entry through the call-port of the 4-port debugger.

redo

Normal entry through the call-port of the 4-port debugger. The redo port signals resuming a predicate to generate alternative solutions.

unify

The unify-port represents the neck instruction, signalling the end of the head-matching process. This port is normally invisible. See leash/1 and visible/1.

exit

The exit-port signals the goal is proved. It is possible for the goal to have alternative. See prolog_frame_attribute/3 to examine the goal-stack.

fail

The fail-port signals final failure of the goal.

exception(Except)

An exception is raised and still pending. This port is activated on each parent frame of the frame generating the exception until the exception is caught or the user restarts normal computation using retry. Except is the pending exception-term.

break(PC)

A break instruction is executed. PC is program counter. This port is used by the graphical debugger.

cut_call(PC)

A cut is encountered at PC. This port is used by the graphical debugger. to visualise the effect of the cut.

cut_exit(PC)

A cut has been executed. See cut_call(PC) for more information.

Frame is a reference to the current local stack frame, which can be examined using prolog_frame_attribute/3. Choice is a reference to the last choice-point and can be examined using prolog_choice_attribute/3. Action should be unified with one of the atoms continue (just continue execution), retry (retry the current goal) or fail (force the current goal to fail). Leaving it a variable is identical to continue.

Together with the predicates described in section 4.38 and the other predicates of this chapter this predicate enables the Prolog user to define a complete new debugger in Prolog. Besides this it enables the Prolog programmer monitor the execution of a program. The example below records all goals trapped by the tracer in the database.

prolog_trace_interception(Port, Frame, _PC, continue) :-
        prolog_frame_attribute(Frame, goal, Goal), 
        prolog_frame_attribute(Frame, level, Level), 
        recordz(trace, trace(Port, Level, Goal)).

To trace the execution of `go' this way the following query should be given:

?- trace, go, notrace.

prolog_skip_level(-Old, +New)

Unify Old with the old value of `skip level' and than set this level according to New. New is an integer, or the special atom very_deep (meaning don't skip). The `skip level' is a global variable of the Prolog system that disables the debugger on all recursion levels deeper than the level of the variable. Used to implement the trace options `skip' (sets skip level to the level of the frame) and `up' (sets skip level to the level of the parent frame (i.e., the level of this frame minus 1).