6.14.3.1 Table Deletion Predicates

abolish_table_pred(+Pred)

Tabling
Invalidates all tabled subgoals for the predicate denoted by the predicate or term indicator Pred. If any subgoal for Pred contains an answer $A$ that is active in the current enviornment, Pred space reclamation for the Pred tables will be delayed until $A$ is no longer active; otherwise the space for the Pred tables will be reclaimed immediately.

If Pred has a subgoal that contains a conditional answer, the default behavior will be to transitively abolish any tabled predicates with subgoals having answers that depend on any conditional answers of $S$. This default may be changed either by setting an XSB flag:

?- set_xsb_flag(table_gc_action,abolish_tables_singly).

or by calling abolish_table_pred/2 with the appropriate option. If the transitive abolishes are turned off, and Pred contains a conditional answer, the warning

abolish_table_pred/[1,2] is deleting a table with conditional answers:
delay dependencies may be corrupted.

will be issued.

In the multi-threaded engine, if Pred is shared, reclamation for Pred will be delayed until there is a single active thread and no answer in Pred is active in the current execution environment. Otherwise, the behavior of abolish_table_pred/1 is the same as in the sequential engine.

Error Cases

• Pred is not instantiated
  • instantiation_error
• PredSpec is not a predicate_indicator or a term_indicator
  • domain_error(predicate_or_term_indicator,Pred)
• PredSpec does not indicate a tabled predicate
  • table_error
• There is currently an incomplete table for an atomic subgoal of Pred
  • table_error

abolish_table_pred(+CallTerm,+Options)

Tabling
Behaves as abolish_table_pred/1, but allows the default table_gc_action to be over-ridden with a flag, which can be either abolish_tables_transitively or abolish_tables_singly.

Error Cases Error cases are the same as abolish_table_pred/1 but with the additions:

• Options is a variable, or contains a variable as an element
  • instantiation_error
• Options is not a list
  • type_error(list,Options)
• Options contains an option O that is not a table abolish option.
  • domain_error([abolish_tables_transitively, abolish_tables_singly,O)

abolish_table_call(+CallTerm)

Tabling
Invalidates all entries from the table for the any subgoals that unify with CallTerm. If a subgoal $S$ unifying with CallTerm contains an answer $A$ that is active in the current enviornment, the table entry for $S$ will not be reclaimed until $A$ is no longer active; otherwise the space for $S$ will be reclaimed immediately.

If $S$ contains a conditional answer, the default behavior will be to transitively abolish any subgoals that depend on any conditional answers of $S$. This default may be changed either by setting an XSB flag:

?- set_xsb_flag(table_gc_action,abolish_tables_singly).

or by calling abolish_table_call/2 with the appropriate option. If the transitive abolishes are turned off, and $S$ contains a conditional answer, the warning

abolish_table_call/1 is deleting a table with conditional answers:
delay dependencies may be corrupted.

will be issued.

In the multi-threaded engine, if $S$ is a subgoal for a predicate that is shared, reclamation for $S$ will be delayed until there is a single active thread and no answer in $S$ is active in the current execution environment. Otherwise, the behavior of abolish_table_call/1 is the same as in the sequential engine on tabled predicates that are thread-private.

Error Cases

• The term spec CallTerm does not correspond to a tabled predicate:
  • table_error
• The term spec CallTerm unifies with a tabled subgoal that is incomplete:
  • table_error
• CallTerm unifies with a table that is formed from a predicate that does not use variant tabling.
  • table_error

abolish_table_call(+CallTerm,+Options)

Tabling
Behaves as abolish_table_call/1, but allows the default table_gc_action to be over-ridden with a flag, which can be either abolish_tables_transitively or abolish_tables_singly.

Error Cases Error cases are the same as abolish_table_call/1 but with the additions:

• Options is a variable, or contains a variable as an element
  • instantiation_error
• Options is not a list
  • type_error(list,Options)
• Options contains an option O that is not a table abolish option.
  • domain_error([abolish_tables_transitively, abolish_tables_singly,O)

abolish_all_tables

Tabling
In the single-threaded engine, removes all tables presently in the system and frees all the memory held by XSB for these structures. Predicates that have been declared tabled remain so, but information in their table is deleted. abolish_all_tables/0 works directly on the memory structures allocated for table space. This makes it very fast for abolishing a large amount of tables, and to maintain its speed it throws an error if any completed answer $A$ is active in the current execution environment.

In the multi-threaded engine abolish_all_tables/0 raises an error unless it is called when there is a single active thread. In that case, all shared tables are abolished as well as all private tables for the main thread. An error will be thrown if any completed answer $A$ is active in the current environment, regardless of whether $A$ is thread-private or thread-shared.

Error Cases

• There are incomplete tables at the time of the predicate's call;
  • table_error
• The current execution environment has an active answer $A$
  • table_error
• (Multi-threaded engine only) More than one thread is active:
  • table_error

abolish_all_private_tables

Tabling
In the multi-threaded engine, removes all tables private to the thread and frees all the memory held by XSB for these structures, including space for conditional answers. Predicates that have been declared tabled remain so, but information in their table is deleted. abolish_all_private_tables/0 works directly on the memory structures allocated for table space. This makes it very fast for abolishing a large amount of tables, and to maintain its speed it throws an error if any completed answer $A$ for a private table is active in the current execution environment.

Error Cases

• There are incomplete tables at the time of the predicate's call;
  • table_error
• The current execution environment for the thread has an active answer $A$ for a private table.
  • table_error

abolish_all_shared_tables

Tabling
In the multi-threaded engine, removes all tables private to the thread and frees all the memory held by XSB for these structures, including space for conditional answers. Predicates that have been declared tabled remain so, but information in their table is deleted. abolish_all_private_tables/0 works directly on the memory structures allocated for table space. This makes it very fast for abolishing a large amount of tables, and to maintain its speed it throws an error if any completed answer $A$ for a private table is active in the current execution environment. abolish_all_shared_tables/0 raises an error unless it is called when there is a single active thread. In that case, all shared tables are abolished, but private tables for the main thread are unaffected.

Error Cases

• There are incomplete tables at the time of the predicate's call;
  • table_error
• The current execution environment has an active answer $A$
  • table_error
• More than one thread is active:
  • table_error

abolish_module_tables(+Module)

Tabling
Given a module name (or the default module, usermod), this predicate abolishes all tables for each tabled predicate in Module. It is implemented using a series of calls to abolish_table_pred/1 and so inherits the behavior of that predicate.

gc_tables(-Number)

Tabling
When a tabled subgoal or predicate is abolished, reclamation of its space may be postponed if the subgoal or predicate has an answer that is active in the current environment. A garbage collection routine is called at various points in execution to check which answers are active in the current environment, and to reclaim the space for subgoals and predicates with no active answers. In particular, space for all abolished tables is reclaimed whenever the engine re-executes the main command-line or C thread interpreter code. However for certain applications this strategy may not be adequate. For this reason, the user can explicitly call the table garbage collector to reclaim space for any deleted tabled predicates or subgoals that no longer have active answers.

gc_tables/1 always succeeds, unifying Number to $-1$ if garbage collection was not attempted (due to multiple active threads) and otherwise to the number of tables still unreclaimed at the end of garbage collection.

Error Cases

• Number is not a variable
  • type_error(variable)

delete_return(+TableEntryHandle,+ReturnHandle)

Tabling
Removes the answer indicated by ReturnHandle from the table entry referenced by TableEntryHandle. The value of each argument should be obtained from some previous invocation of a table-inspection predicate.

This predicate is low-level so no error checking is done. In Version 3.0 , this predicate does not reclaim space for deleted returns, but simply marks the returns as invalid.

Warning: While useful for purposes such as tabled aggregation, delete_return/2 can be difficult to use, both from an implementation and semantic perspective.

invalidate_tables_for(+DynamicPredGoal,+Mode)

Tabling

This predicate supports invalidation of tables. Tables may become invalid if dynamic predicates on which they depend change, due to asserts or retracts. By default XSB does not change or delete tables when they become invalid; it is the user's responsibility to know when a table is no longer valid and to use the abolish_table_* primitives to delete any table when its contents become invalid.

This predicate gives the XSB programmer some support in managing tables and deleting them when they become invalid. To use this predicate, the user must have previously added clauses to the dynamic predicate, invalidate_table_for/2. That predicate should be defined to take a goal for a dynamic predicate and a mode indicator and abolish (some) tables (or table calls) that might depend on (any instance of) that fact.
invalidate_tables_for(+DynamicPredGoal),+Mode simply backtracks through calls to all unifying clauses of
invalidate_table_for(+DynamicPredGoal,+Mode). The Mode indicator can be any term as long as the two predicates agree on how they should be used. The intention is that Mode will be either 'assert' or 'retract' indicating the kind of database change being made.

Consider a simple example of the use of these predicates: Assume the definition of tabled predicate ptab/3 depends on dynamic predicate qdyn/2. In this case, the user could initially call:

      :- assert((invalidate_table_for(qdyn(_,_),_) :-
                    abolish_table_pred(ptab(_,_,_)))).

to declare that when qdyn/2 changes (in any way), the table for ptab/3 should be abolished. Then each time a fact such as qdyn(A,B) is asserted to, or retracted from, qdyn/2, the user could call

      :- invalidate_table_for(qdyn(A,B),_).

The user could use the hook mechanisms in XSB (Chapter 8) to automatically invoke
invalidate_tables_for whenever assert and/or retract is called.