statistics.pl -- 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.

 statistics is det

Print information about resource usage using print_message/2.

See also

- All statistics printed are obtained through statistics/2.

 statistics(-Stats:dict) is det

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.

 thread_statistics(?Thread, -Stats:dict) is nondet

Obtain statistical information about a single thread. Fails silently of the Thread is no longer alive.

Arguments:

Stats

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

 time(:Goal) is nondet

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

Arguments:

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.

 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.

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)

 call_time(Arg1, Arg2, Arg3)