instrument(+File, +ITemplates)

File

Atom or string

ITemplates

itemplate, List of itemplate or PredSpec

Description

This is a variant of the ECLiPSe compiler that inserts user specified instrumentation predicates into the compiled code. This code can then be run, and the results analysed by printing them using instrument:module_result/0 or instrument:file_result/1.

ITemplates can be specified as:

PredSpec of arity two

If an arity two predicate specification is supplied, then this predicate is invoked in order to retrieve the template for the predicate being instrumented. Argument one is the predicate specification of the predicate undergoing instrumentation. Argument two is an output variable that is to be returned by this predicate as the template to use. The returned itemplate will be validated before instrumentation proceeds.

itemplate

A single template passed to instrument/2 or instrument/3 is adopted as the global template to be used for predicate instrumentation. If a template for the predicate currently being instrumented is not found in the template stores then if a global template exists, it is used.

PredSpec = itemplate

A template specification for instrumentation of a single predicate. If however, PredSpec is not actually a valid predicate specification but the atom iglobal, the template is adopted as the global template (see above).

List of itemplate

The list is of the form:

[itemplate{...} | PredSpec = itemplate{...} ... 
   PredSpec = itemplate{...}]

The itemplate at the head of the list is specifies the global template and is optional. The remaining elements of the list are itemplate specifying instrumentation for the PredSpec with which they are associated.

In addition to supplying the global template, an exclude list of PredSpec for predicates that should not be instrumented by the global template can be specified:

itemplate{...} - 
   predicate/1, my_module:my_predicate/8,...]

Modules

Exceptions

(4) instantiation fault

ITemplates is not instantiated.

(5) type error

ITemplates is not of the appropriate type.

See Also