7.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 computed using ‘mtc_union’, ‘mdice’ can be used to 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’ 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 columns 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 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 columns displays a number between 0 and 1 which gives an indication of how likely a particular goal is to contain a bug. The suspicion is calculated as Suspicion = F / (P + F) where F is the number of times the goal was executed in failing runs and P 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

‘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. ‘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 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 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 to sort descending on the Suspicion column.

The option ‘-l’ or ‘--limit’ can be used to limit the number of lines displayed.

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

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

The ‘-p’ or ‘--max-path-column’ 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’ 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.