[ library(instprofile) | The ECLiPSe Libraries | Reference Manual | Alphabetic Index ]

# statprofile(+File, +Statistics, +OptionsList)

Instrument a file with statistics profiling code.

File
  Atom or string
Statistics
  List of statistic keywords
OptionsList
  List of Name:Value pairs

## Description

The predicate inserts into the user code of File, instrumentation for the collection of the statistics (statistics/2 metric keywords) specified in Statistics. The instrumentation is inserted by default at clause entry and exit points (i.e. the start, end, fail and redo ports of the conceptual predicate box model) and aggregates the cost for each of the metrics as the program executes. The source code can be annotated with these aggregated results using the result/0 predicate. Additionally, the results may be dumped to a file in a format suitable for offline analysis and graphing.

OptionList may contain the following options:

`instrument_style` (default:`clause`)
  Valid values for this option are `clause`, `block`, `subgoal` and `call`. These values correspond to the instrument insertion points of instrument library. Each provides a different level of granularity for the profiling of code fragments.
`delta_results` (default:`off`)
  Specifying this option as `on` indicates that the instrumentation results for execution of individual profiled code fragments (associated by instrument's callsite identifier) should be written to the file specified using open_delta_file/1. More specifically, these are the delta results, the difference for each of the statistics between the start and end of the profiled code fragment's execution.
Instrument library options
  In addition to the above options, options valid to the instrument library can also be passed in OptionsList. The most useful of which are `verbose` and `instrument_recursive`. `instrument_recursive` is used to prevent the incorrect aggregation of results accumulated during the execution of recursive predicates, by default it is off, i.e. recursive predicates will not be instrumented.

The instrumentation profiler places an overhead on the execution of the code undergoing profiling due to the insertion of the profiling code. The sample based profiler is implemented using after events and is therefore less intrusive in its effect on the performance of the executing code than the instrumentation profiler. However, it is used to indicate the trend of resource usage over time of a running program not to attribute specific costs of a statistic to a specific piece of code. The instrumentation based profiler is used to do this.

### Modules

This predicate is sensitive to its module context (tool predicate, see @/2).

### Fail Conditions

Statistics is empty or contains an invalid statistic/2 keyword.

### Resatisfiable

no

### Exceptions

(5) type error
  File is not an atom or string.

## Examples

       [eclipse 1]: instprofile:statprofile(queen,[global_stack_used, trail_stack_used],
                                            [instrument_style:block, delta_results:on]).

       Yes (0.06s cpu)

## See Also

open_delta_file / 1, close_delta_file / 0, result / 0, aggregate_result / 1, reset / 0, statprofile / 2, statistics / 2, library(instprofile), library(instrument), instrument : instrument / 3