[ library(instprofile) | Reference Manual | Alphabetic Index ]

# statprofile(+File, +Statistics)

Instrument a file with statistics profiling code.

File
  Atom or string
Statistics
  List of statistic keywords

## 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 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.

statprofile/3 should be used for instrumentation profiling of code at a finer granularity than the clause definition. statprofile/3 provides options to prevent the profiling of recursive predicates. It also, provides an option to produce the results for a single execution of a profiled piece of code, in addition to the aggregated results.

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]).

       Yes (0.06s cpu)

## See Also

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