4.42 Execution profiling
All Application Manual Name SummaryHelp

  • Documentation
    • Reference manual
      • Built-in Predicates
        • Execution profiling
          • library(prolog_profile): Execution profiler
            • profile/1
            • profile/2
            • show_profile/1
            • profile_data/1
            • profile_procedure_data/2
          • Visualizing profiling data
          • Information gathering
    • Packages

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.
measure(Measure)
When generating a textual report, show time (default) or memory, 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 (default false), show cumulative output in a textual report.
measure(Measure)
One of time (default) or memory. 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, for p :- \+ \+ 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 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)
  • 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.
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.
alloc_self:Bytes
alloc_siblings:Bytes
Global stack allocated by the predicate itself and by its callees.
discarded_self:Bytes
discarded_siblings:Bytes
Global stack discarded by backtracking into a choicepoint of the predicate itself and of 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, 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_* and discarded_*` 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 nodes key.