Module dump

The shape of the clause index depends on the call pattern history of the predicate. We do not provide a programming interface to selectively inspect the clause index. Instead the end-user can dump the clause index for predicates in one go.

The detected call patterns can be read off from the detected argument positions. The clause index need not follow a simple collection of call patterns. Sub-indexes can have individual call patterns. Let’s give a simple example:

?- [user].
p(7, a).
p(7, b).
p(9, c).
^D
?- p(7, a).
Yes

The query will deterministically succeed. This is an indicative that a clause index has been built that covers multiple arguments. Clause indexing based on first argument indexing only would not be able to detect this determinism. Although the clause index is multi argument, it does so only for the key “7”:

?- dump(p/2).
-------- p/2 ---------
length=3
at=0
key=7, length=2
at=1
key=a, length=1
key=b, length=1
key=9, length=1

Since release 1.2.5 of the Prolog runtime different data structures are used depending on a low and a high water mark. For small indexes a simple key-value pair list is used and no hash is computed. For large indexes a hash table is used.

The following index attributes are shown during a clause index dump:

length=<len>: Gives the size of indexed clause set.
arg=<pos>: Gives the argument position that is indexed.
map=<size>: Gives the hash table size of the argument position.
<key>=: Gives the key and corresponding sub index.
hash=<index>: Gives the hash code module hash table size of the key.
nonguard: Gives the non-guard hash table miss fallback index.
guard: Gives the guard hash table miss fallback index.

The following clause index predicates are provided:

dump:
The predicate dumps the clause index of the clauses of the user predicates.
dump(P):
The predicate dumps the clause index of the clauses of the user predicate P.

Comments