4.42.1 library(prolog_profile): 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.

exact(Exact)

If true, do not sample, but read the clock each time execution moves to another node of the call tree. This gives exact wall times, also for short running goals. For CPU time, the thread's CPU time is read once per sample period (see sample_rate(Rate)) and after each long interval, where the thread may have been off the CPU. If auto, use exact timing if reading the clock is cheap and, for CPU time, the thread CPU clock is precise. This is typically not the case in virtual machines. Otherwise use sampling. Default is defined by the Prolog flag profile_exact, which defaults to auto.

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.

[det]profile_data(-Data)

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 or, if exact is true, the number of times execution moved to another node of the call tree.
• ticks:Count Nanoseconds sampled during profiling
• accounting:Count Nanoseconds spent on accounting. This is the profiler's own overhead. The exact modes measure it and exclude it from the times of the predicates.
• 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
• clock: Clock One of cpu or wall, the time that was profiled.
• exact: Bool Whether the data was collected using exact(true)

nodes

List of nodes. Each node provides:

predicate:PredicateIndicator

or a blob that represents another profiled object, such as an XPCE method.

ticks_self:Count

ticks_siblings:Count

Nanoseconds sampled in the predicate itself and in its callees.

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)

[nondet]profile_procedure_data(?Pred, -Data:dict)

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.