tableutil.pl -- Table inspection and statistics utilities

This library provides tools intended to be used at the interactive toplevel for inspecting tables, table dependencies and table statistics.

table_statistics(?Stat, -Value) is nondet

table_statistics(?Variant, ?Stat, -Value) is nondet

Give summary statistics for the tables associated with all subgoals of Variant. The table_statistics/2 version considers all tables.

The values for Stat are:

tables: Total number of answer tries
answers: Total number of answers in the combined tries
duplicate_ratio: Ratio of generated (and thus ignored) duplicate answers. 1 means no duplicates. 2 means for every answer there was (on everage) a duplicate generated.
space_ratio: Number of nodes with a value divided by the total number of nodes in a trie. The maximum is 1. A low number implies that a large amount of differently shaped data is included in the answer tries.
complete_call: Number of times answers are generated from a completed table, i.e., times answers are reused.
invalidated: Number of times an incremental table was invalidated.
reevaluated: Number of times an invalidated table wa reevaluated. If lower than invalidated this implies that dependent nodes of the IDG were reevaluated to the same answer set.
space: Summed memory usage of the answer tries in bytes.
compiled_space: Summed size for the compiled representation of completed tables.

table_statistics

Print a summary of statistics relevant to tabling.

See also: - table_statistics/2 for an explanation

table_statistics(:Variant)

Print a summary for the statistics of all tables for subgoals of Variant. See table_statistics/2 for an explanation.

table_statistics_by_predicate is det

table_statistics_by_predicate(+Options) is det

Print statistics on memory usage and lookups per predicate. The version without options dumps all predicates without ordering. Options:

order_by(+Key): Order the predicates according to Key. Default is tables, the number of answer tables. See table_statistics/2 for a list of values for Key.
top(N): Only show the top N predicates.
module(Module): Limit the results to predicates of the given module.

tstat(?Value, ?Top)

tstat(?Variant, ?Value, ?Top)

Print the top-N (for positive Top) or bottom-N (for negative Top) for Stat for all tabled subgoals of Variant (or all tabled subgoals for tstat/2). Stat is one of

answers
duplicate_ratio
space_ratio
gen(call)
space
compiled_space: See table_statistics/2.
deadlock: Times this table was involved in a deadlock (cycle of threads waiting for each others table to complete)
wait: Times a thread waited for this table.
variables: The number of variables in the variant. The tabling logic adds a term ret(...) to the table for each answer, where each variable is an argument of the ret(...) term. The arguments are placed in depth-first lef-right order they appear in the variant. Optimal behaviour of the trie is achieved if the variance is as much as possible to the rightmost arguments. Poor allocation shows up as a low space_ratio statistics.

Below are some examples

tdump is det

tdump(:Goal) is det

tdump(:Goal, +Options) is det

Dump all tables and their status that unify with Goal. Options:

scope(Scope): Limit displayed tables to local or global.
limit(Count): Limit the number of answers displayed to Count
reset(Boolean): If true, also show reset (fresh) global tables. These are tables that have been abolished.

tidg is det

tidg(:Goal) is det

Dump the incremental dependency graph. idg/1 dumps the graph around a given node

summarize_idg is det

summarize_idg(+TopN) is det

Implements XSB's statistics(summarize_idg)

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

tdump(Arg1)
tdump(Arg1, Arg2)
summarize_idg(Arg1)
tidg(Arg1)
tstat(Arg1, Arg2, Arg3)
table_statistics(Arg1, Arg2, Arg3)
table_statistics_by_predicate(Arg1)