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 bylibrary(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
cpuorwalltime. 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 (seesample_rate(Rate)) and after each long interval, where the thread may have been off the CPU. Ifauto, 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 toauto. - 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) orclassic(all with some errors). Accomodates space/accuracy tradeoff building call tree. Default is defined by the Prolog flag profile_ports, which defaults totrue. - top(N)
- When generating a textual report, show the top N predicates.
- cumulative(Bool)
- If
true(defaultfalse), show cumulative output in a textual report. - measure(Measure)
- When generating a textual report, show
time(default) ormemory, the global stack allocated and discarded by backtracking. See show_profile/1.
- 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(defaultfalse), show cumulative output in a textual report. - measure(Measure)
- One of
time(default) ormemory. The latter shows the global stack allocated by the predicate itself and by its callees, and the global stack discarded by backtracking into the predicate. For example, forp :- \+ \+ q, q allocates and p discards. The predicates are sorted on the allocated memory.
- [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
exactistrue, 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,falseorclassic - clock: Clock One of
cpuorwall, the time that was profiled. - exact: Bool Whether the data was collected using
exact(true) - allocated: Bytes
- discarded: Bytes
- gc_reclaimed: Bytes Global stack allocated, discarded by backtracking and reclaimed by garbage collection while profiling.
- gc_count: Count Number of garbage collections while profiling.
- samples:Count: Times the statistical profiler was called or, if
- nodes
- List of nodes. Each node provides:
predicate:PredicateIndicator- or a blob that represents another profiled object, such as an XPCE method.
ticks_self:Countticks_siblings:Count- Nanoseconds sampled in the predicate itself and in its callees.
alloc_self:Bytesalloc_siblings:Bytes- Global stack allocated by the predicate itself and by its callees.
discarded_self:Bytesdiscarded_siblings:Bytes- Global stack discarded by backtracking into a choicepoint of the predicate itself and of its callees.
call:Countredo:Countexit:Countcallers: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, Memory)Memory is a term
mem(Alloc, AllocSiblings, Discarded, DiscardedSiblings), the global stack in bytes allocated and discarded by these calls, by the called predicate itself and by its callees, as the ‘alloc_*anddiscarded_*` keys of the node. - [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
nodeskey.