7.10.10 Experimental commands

histogram_all filename

Prints (to file filename) a histogram that counts all events at various depths since the start of the program. This histogram is available only in some experimental versions of the Mercury runtime system.

histogram_exp filename

Prints (to file filename) a histogram that counts all events at various depths since the start of the program or since the histogram was last cleared. This histogram is available only in some experimental versions of the Mercury runtime system.

clear_histogram

Clears the histogram printed by ‘histogram_exp’, i.e. sets the counts for all depths to zero.

dice [-pfilename] [-ffilename] [-nnum] [-s[pPfFsS]+] [-o filename] [-m module]

Display a program dice on the screen.

A dice is a comparison between some successful test runs of the program and a failing test run. Before using the ‘dice’ command one or more passing execution summaries and one failing execution summary need to be generated. This can be done by compiling the program with deep tracing enabled (either by compiling in a .debug or .decldebug grade or with the ‘--trace deep’ or ‘--trace rep’ compiler options) and then running the program under mtc. This will generate a file with the prefix ‘.mercury_trace_counts’ and a unique suffix, that contains a summary of the program's execution This summary is called a slice. Copy the generated slice to a new file for each test case, to end up with a failing slice, say ‘fail’, and some passing slices, say ‘pass1’, ‘pass2’, ‘pass3’, etc. Union the passing slices with a command such as ‘mtc_union -p passes pass1 pass2 pass3’.

The ‘dice’ command can use these files to display a table of statistics comparing the passing test runs to the failing run. Here is an example of a dice displayed in an mdb session:

          mdb> dice -f fail -p passes -s S -n 4
          Procedure        Path/Port  File:Line Pass (3) Fail Suspicion
          pred s.mrg/3-0   <s2;c2;e;> s.m:74       0 (0)    1      1.00
          pred s.mrg/3-0   <s2;c2;t;> s.m:67      10 (3)    4      0.29
          pred s.mrg/3-0   CALL       s.m:64      18 (3)    7      0.28
          pred s.mrg/3-0   EXIT       s.m:64      18 (3)    7      0.28

This example tells us that the ‘else’ in ‘s.m’ on line 74 was executed once in the failing test run, but never in the passing test runs, so this would be a good place to start looking for a bug.

Each row in the table contains statistics about the execution of a separate goal in the program. Six columns are displayed:

• ‘Procedure’: The procedure in which the goal appears.
• ‘Path/Port’: The goal path and/or port of the goal. For atomic goals, statistics about the CALL event and the corresponding EXIT, FAIL or EXCP event are displayed on separate rows. For other types of goals the goal path is displayed, except for NEGE, NEGS and NEGF events where the goal path and port are displayed.
• ‘File:Line’: The file name and line number of the goal. This can be used to set a breakpoint on the goal.
• ‘Pass (total passing test runs)’: The total number of times the goal was executed in all the passing test runs. This is followed by a number in parentheses which indicates the number of test runs the goal was executed in. The heading of this column also has a number in parentheses which is the total number of passing test cases. In the example above we can see that 3 passing tests were run.
• ‘Fail’: The number of times the goal was executed in the failing test run.
• ‘Suspicion’: A number between 0 and 1 which gives an indication of how likely a particular goal is to be buggy. The is calculated as Suspicion = F / (P + F) where F is the number of times the goal was executed in the failing test run and P is the number of times the goal was executed in passing test runs.

The name of the file containing the failing slice can be specified with the ‘-f’ or ‘--fail-trace-counts’ option or with a separate ‘set fail_trace_count filename’ command.

The name of the file containing the union of the passing slices can be given with the ‘-p’ or ‘--pass-trace-counts’ option. Alternatively a separate ‘set pass_trace_counts filename’ command can be given. See Trace counts for more information about trace counts.

The table can be sorted on the Pass, Fail or Suspicion columns, or a combination of these. This can be done with the ‘-s’ or ‘--sort’ option. The argument of this option is a string made up of any combination of the letters ‘pPfFsS’. The letters in the string indicate how the table should be sorted:

• ‘p’: Pass ascending
• ‘P’: Pass descending
• ‘f’: Fail ascending
• ‘F’: Fail descending
• ‘s’: Suspicion ascending
• ‘S’: Suspicion descending

For example the string "SF" means sort the table by suspicion, descending, and if any two suspicions are the same, then by number of executions in the failing test case, descending.

The option ‘-n’ or ‘--top’ can be used to limit the number lines displayed. Only the top num lines, with respect to the ordering specified by the ‘-s’ option, will be displayed. By default the table is limited to 50 lines.

If the ‘-o’ or ‘--output-to-file’ option is given then the output will be written to the specified file instead of being displayed on the screen. Note that the file will be overwritten without warning if it already exists.

The ‘-m’ or ‘--module’ option limits the output to the given module and its submodules, if any.