prolog_profile.pl -- Execution profiler

This module provides a simple frontend on the execution profiler with a hook to the GUI visualiser for profiling results defined in library(swi/pce_profile).

 profile(:Goal)

 profile(:Goal, +Options)

Run once(Goal) under the execution profiler. If the (xpce) GUI is enabled this predicate is hooked by library(swi/pce_profile) and results are presented in a gui that enables navigating the call tree and jump to predicate implementations. Without the GUI, a simple textual report is generated. Defined options are:

time(Which)

Profile cpu or wall time. The default is CPU time.

sample_rate(Rate)

Samples per second, any numeric value between 1 and 1000. Default is defined by the Prolog flag profile_sample_rate, which defaults to 200.

ports(Bool)

Specifies ports counted - true (all ports), false (call port only) or classic (all with some errors). Accomodates space/accuracy tradeoff building call tree. Default is defined by the Prolog flag profile_ports, which defaults to true.

top(N)

When generating a textual report, show the top N predicates.

cumulative(Bool)

If true (default false), show cumulative output in a textual report.

See also

- show_coverage/2 from library(test_cover).

To be done

- The textual input reflects only part of the information.

 show_profile(+Options)

Display last collected profiling data. Options are

top(N)

When generating a textual report, show the top N predicates.

cumulative(Bool)

If true (default false), show cumulative output in a textual report.

 profile_data(-Data) is det

Gather all relevant data from profiler. This predicate may be called while profiling is active in which case it is suspended while collecting the data. Data is a dict providing the following fields:

summary:Dict

Overall statistics providing

• samples:Count: Times the statistical profiler was called
• ticks:Count Virtual ticks during profiling
• accounting:Count Tick spent on accounting
• time:Seconds Total time sampled
• nodes:Count Nodes in the call graph.
• sample_period: MicroSeconds Same interval timer period in micro seconds
• ports: Ports One of true, false or classic

nodes

List of nodes. Each node provides:

• predicate:PredicateIndicator
• ticks_self:Count
• ticks_siblings:Count
• call:Count
• redo:Count
• exit:Count
• callers:list_of(Relative)
• callees:list_of(Relative)

Relative is a term of the shape below that represents a caller or callee. Future versions are likely to use a dict instead.

node(PredicateIndicator, CycleID, Ticks, TicksSiblings,
     Calls, Redos, Exits)

 prof_statistics(-Node) is det[private]

Get overall statistics

Arguments:

Node	- term of the format prof(Ticks, Account, Time, Nodes)

 profile_procedure_data(?Pred, -Data:dict) is nondet

Collect data for Pred. If Pred is unbound data for each predicate that has profile data available is returned. Data is described in profile_data/1 as an element of the nodes key.

 value(+Key, +NodeData, -Value)[private]

Obtain possible computed attributes from NodeData.

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

 profile(Arg1, Arg2)