8.4 Debugging

The CHR debugging facilities are currently rather limited. Only tracing is currently available. To use the CHR debugging facilities for a CHR file it must be compiled for debugging. Generating debug info is controlled by the CHR option debug, whose default is derived from the SWI-Prolog flag generate_debug_info. Therefore debug info is provided unless the -nodebug is used.

8.4.1 Ports

For CHR constraints the four standard ports are defined:

call

A new constraint is called and becomes active.

exit

An active constraint exits: it has either been inserted in the store after trying all rules or has been removed from the constraint store.

fail

An active constraint fails.

redo

An active constraint starts looking for an alternative solution.

In addition to the above ports, CHR constraints have five additional ports:

wake

A suspended constraint is woken and becomes active.

insert

An active constraint has tried all rules and is suspended in the constraint store.

remove

An active or passive constraint is removed from the constraint store.

try

An active constraint tries a rule with possibly some passive constraints. The try port is entered just before committing to the rule.

apply

An active constraint commits to a rule with possibly some passive constraints. The apply port is entered just after committing to the rule.

8.4.2 Tracing

Tracing is enabled with the chr_trace/0 predicate and disabled with the chr_notrace/0 predicate.

When enabled the tracer will step through the call, exit, fail, wake and apply ports, accepting debug commands, and simply write out the other ports.

The following debug commands are currently supported:

        CHR debug options:

                <cr>    creep           c       creep
                s       skip
                g       ancestors
                n       nodebug
                b       break
                a       abort
                f       fail
                ?       help            h       help

Their meaning is:

creep

Step to the next port.

skip

Skip to exit port of this call or wake port.

ancestors

Print list of ancestor call and wake ports.

nodebug

Disable the tracer.

break

Enter a recursive Prolog top level. See break/0.

abort

Exit to the top level. See abort/0.

fail

Insert failure in execution.

help

Print the above available debug options.

8.4.3 CHR Debugging Predicates

The library(chr) module contains several predicates that allow inspecting and printing the content of the constraint store.

chr_trace

Activate the CHR tracer. By default the CHR tracer is activated and deactivated automatically by the Prolog predicates trace/0 and notrace/0.

chr_notrace

Deactivate the CHR tracer. By default the CHR tracer is activated and deactivated automatically by the Prolog predicates trace/0 and notrace/0.

chr_leash(+Spec)

Define the set of CHR ports on which the CHR tracer asks for user intervention (i.e. stops). Spec is either a list of ports as defined in section 8.4.1 or a predefined `alias'. Defined aliases are: full to stop at all ports, none or off to never stop, and default to stop at the call, exit, fail, wake and apply ports. See also leash/1.

chr_show_store(+Mod)

Prints all suspended constraints of module Mod to the standard output. This predicate is automatically called by the SWI-Prolog top level at the end of each query for every CHR module currently loaded. The Prolog flag chr_toplevel_show_store controls whether the top level shows the constraint stores. The value true enables it. Any other value disables it.

find_chr_constraint(-Constraint)

Returns a constraint in the constraint store. Via backtracking, all constraints in the store can be enumerated.