9.12.4 Dicing

A dice is a comparison between passing and failing runs of a program.

Dice are created using the ‘mdice’ tool. To use the ‘mdice’ tool, one must first generate a set of trace count files for passing runs and a set of trace count files for failing runs using the ‘mtc’ tool (Generating trace counts). Once this has been done, and the union of each set (the set of passing runs and the set of failing runs) has been computed using ‘mtc_union’, invoking ‘mdice’ will display a table of statistics that compares the passing runs to the failing runs.

Here is an example of the output of the ‘mdice’ tool:

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’ event in ‘s.m’ on line 74 was executed once in the failing test run, but never during the passing test runs, so this would be a good place to start looking for a bug.

Each row corresponds to an event in the program. The meanings of the columns are as follows:

• ‘Procedure’: This column displays the procedure the event relates to.
• ‘Path/Port’: For interface events this column displays the event port, while for internal events it displays the goal path. (See Tracing of Mercury programs for an explanation of interface and internal events.)
• ‘File:Line’: This column displays the context of the event.
• ‘Pass (total passing test runs)’: This column displays the total number of times the event was executed in all the passing test runs. This is followed by a number in parentheses which indicates the number of passing test runs the event was executed in. The heading of this column also has a number in parentheses which is the total number of passing test cases.
• ‘Fail’: This column displays the number of times the goal was executed in the failing test run(s).
• ‘Suspicion’: This column displays a number between 0 and 1 which gives an indication of how likely a particular goal is to contain a bug. This number is calculated as Suspicion = Fail / (Pass + Fail) where Fail is the number of times the goal was executed in failing runs and Pass is the number of times the goal was executed in passing runs.

The ‘mdice’ tool is invoked with a command of the form:

mdice [-s sortspec] [-l N] [-m module] [-n N] [-p N] [-f N] passfile failfile

where

• ‘passfile’ is a trace count file, generated either directly by a passing program run, or as the union of the trace count files of passing program runs, and
• ‘failfile’ is a trace count file, generated either directly by a failing program run, or as the union of the trace count files of failing program runs.

The table is normally sorted on the identification of the event, meaning it is sorted

• first on the identification of the procedure containing the event (consisting of a pred/func indication, the name of the predicate or function, its arity, and its mode number),
• then on the port (if any),
• then on the path (if any),
• then on the file name, and
• then on the line number.

However, users can also ask for it to be sorted on the Pass, Fail and/or Suspicion columns, or on a combination of these. This can be done with the ‘-s’ or ‘--sort’ option. The argument of this option is a nonempty string consisting of any combination of the letters ‘pPfFdDsS’. The letters in the string indicate how the table should be sorted:

• ‘p’: Pass ascending
• ‘P’: Pass descending
• ‘f’: Fail ascending
• ‘F’: Fail descending
• ‘d’: Difference (Pass minus Fail) ascending
• ‘D’: Difference (Pass minus Fail) descending
• ‘s’: Suspicion ascending
• ‘S’: Suspicion descending

For example the string "SF" means sort the table by suspicion in descending order, and if any two suspicions are the same, then by number of executions in the failing run(s), also in descending order.

The default is "S", meaning to only sort descending by suspicion. (Note that this is different from the default for the ‘dice’ command in ‘mdb’.)

To limit the number sorted lines displayed, users can specify the ‘-n’ option or its ‘--top’ synonym, which take an integer argument; this will cause only specified number of the top lines of the table to be displayed.

The ‘-m’ or ‘--module’ option, if specified, limits the output to the given module and (if they exist) its submodules.

The ‘-n’ or ‘--max-name-column-width’ option’s argument gives the maximum width of the column containing predicate and function names. If the argument is zero, there is no maximum width.

The ‘-p’ or ‘--max-path-column-width’ option’s argument gives the maximum width of the column containing ports and goal paths. If the argument is zero, there is no maximum width.

The ‘-f’ or ‘--max-file-column-width’ option’s argument gives the maximum width of the column containing file names and line numbers. If the argument is zero, there is no maximum width.