## A.48 library(statistics): Get information about resource usage

This library provides predicates to obtain information about resource usage by your program. The predicates of this library are for human use at the toplevel: information is printed. All predicates obtain their information using public low-level primitives. These primitives can be use to obtain selective statistics during execution.

[det]statistics
  Print information about resource usage using print_message/2.
  See also
    All statistics printed are obtained through statistics/2.
[det]statistics(-Stats:dict)
  Stats is a dict representing the same information as statistics/0. This convience function is primarily intended to pass statistical information to e.g., a web client. Time critical code that wishes to collect statistics typically only need a small subset and should use statistics/2 to obtain exactly the data they need.
[nondet]thread_statistics(?Thread, -Stats:dict)
  Obtain statistical information about a single thread. Fails silently of the Thread is no longer alive.

  Stats | is a dict containing status, time and stack-size information about Thread.

[nondet]time(:Goal)
  Execute Goal, reporting statistics to the user. If Goal succeeds non-deterministically, retrying reports the statistics for providing the next answer.

  Statistics are retrieved using thread_statistics/3 on the calling thread. Note that not all systems support thread-specific CPU time. Notable, this is lacking on MacOS X.

  See also
    - statistics/2 for obtaining statistics in your program and understanding the reported values.
    - call_time/2, call_time/3 to obtain the timing in a dict.
  bug
    Inference statistics are often a few off.
call_time(:Goal, -Time:dict)
call_time(:Goal, -Time:dict, -Result)
  Call Goal as call/1, unifying Time with a dict that provides information on the resource usage. Currently Time contains the keys below. Future versions may provide additional keys.

  - wall:Seconds
  - cpu:Seconds
  - inferences:Count

  Result | is one of `true` or `false` depending on whether or not the goal succeeded.

profile(:Goal)
profile(:Goal, +Options)
  Run Goal under the execution profiler. Defined options are:
  time(Which)
    Profile `cpu` or `wall` time. The default is CPU time.
  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.
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
    - ticks:Count Virtual ticks during profiling
    - accounting:Count Tick spent on accounting
    - time:Seconds Total time sampled
    - nodes:Count Nodes in the call graph.
  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)

[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.