1.11.2 Low-level Trie Manipulation Utilities

The utilities in this section are very low-level and require good understanding of the trie mechanism in XSB. Improper calls to these predicates can cause core dumps, particularly if an improper trie value is passed to them. Despite these drawbacks, they can be used to implement modules such as the storage module described in Volume 1.

trie_intern(+Term,+Root,-Leaf,-Flag,-Skel)

intern
Acts as trie_intern/2 but returns additional information: Leaf is the handle for the interned Term in the trie. Flag is 1 if the term is ``old'' (already exists in the trie); it is 0, if the term is newly inserted. Skel represents the collection of all the variables in Term. It has the form ret(V1,V2,...,VN), exactly as in get_calls (see Vol. 1 of the XSB manual).

Error Cases

• Root is uninstantiated
  • instantiation_error
• Root is instantiated, but not an integer (trie handle)
  • type_error(integer,Root)

trie_intern(+Term,-Leaf,-Skel)

intern
Acts as trie_intern/5, but interns Term into the default trie and does not return the new/old flag.

trie_interned(?Term,+Root,?Leaf,-Skel)

intern
This predicate backtracks through the terms that unify with Term interned into the trie represented by the handle Root if Leaf is a free variable. Otherwise, if Leaf is bound, it will backtrack over the terms in the trie that unify with the term pointed to by Leaf to. Term is the term to be retrieved; it can be either (partially) bound or free. Skel is the collection of all the variables in Term; it has the form ret(V1,...,Vn).

Error Cases

• Root is uninstantiated
  • instantiation_error
• Root is instantiated, but not an integer (trie handle)
  • type_error(integer,Root)

trie_interned(?Term,?Leaf,-Skel)

intern
Similar to trie_interned/4 but uses the default trie.

trie_unintern(+Root,+Leaf)

intern
Uninterns a term indicated by Leaf from the trie indicated by root. If there are failure continuations that point to trie nodes in Root, the term is marked as deleted but space is not reclaimed. Otherwise, the term is really deleted.

trie_unintern_nr(+Root,+Leaf)

intern
This is a safe version of trie_unintern/2. The term pointed to by Leaf is marked as deleted, but is not deleted from the trie. This permits an efficient implementation of backtrackable updates.

Error Cases

• Root or Leaf is uninstantiated
  • instantiation_error
• Root or Leaf is instantiated, but not an integer (trie handle or trie leaf)
  • type_error(integer,Root) or type_error(integer,Leaf)

unmark_uninterned_nr(+Root,+Leaf)

intern
The term pointed to by Leaf should have been previously marked for deletion using trie_unintern_nr/2. This term is then ``unmarked'' (or undeleted) and becomes again a normal interned term.

Error Cases

• Root or Leaf is uninstantiated
  • instantiation_error
• Root or Leaf is instantiated, but not an integer (trie handle or trie leaf)
  • type_error(integer,Root) or type_error(integer,Leaf)

reclaim_uninterned_nr(+Root)

intern
Runs through the chain of leaves of the trie Root and deletes the terms that have been marked for deletion by trie_unintern_nr/2. This is a garbage collection step that should be done just before returning to the top level or when it can otherwise be ensure that no failure continuations point to a node in Root.

Error Cases

• Root is uninstantiated
  • instantiation_error
• Root is instantiated, but not an integer (trie handle)
  • type_error(integer,Root)