5.5.2 Predicates for Incremental Table Maintenance

The following directives support incremental tabling:

use_incremental_tabling(+PredSpecs)

standard
is a executable predicate that indicates that each tabled predicate specified in PredSpec is to have its tables maintained incrementally. PredSpec is a list of skeletons, i.e. open terms, or Pred/Arity specifications. The tables will be variant tables. If a predicate is already declared as subsumptively tabled, an error is thrown. This predicate, when called as a compiler directive, implies that its arguments are tabled predicates.

We also note that any tabled predicate that is called by a predicate marked as
use_incremental_tabling must also be declared with use_incremental_tabling (or with use_opaque_tabling.) A dynamic predicate that is called by a predicate declared with use_incremental_tabling may or may not be declared with use_incremental_dynamic. But if one is not declared use_incremental_dynamic, then changes to it will not be propagated to incrementally maintained tables.

use_incremental_dynamic(+PredSpecs)

standard
is an executable predicate that indicates that a predicate is dynamic and used to define an incrementally tabled predicate and will be updated using incr_assert and/or incr_retractall (or relatives.) This predicate, when called as a compiler directive, implies that its arguments are dynamic predicates.

use_opaque_tabling(+PredSpecs)

standard
is an executable predicate that indicates that a predicate is tabled and is used in the definition of some incrementally tabled predicate but it should not be maintained incrementally. In this case the system assumes that the programmer will abolish tables for this predicate in such a way so that re-calling it will always give semantically correct answers. So instead of maintaining information to support incremental table maintenance, the system re-calls the opaque predicate whenever its results are required to recompute an answer. One example of an appropriate use of opaque is for tabled predicates in a DCG used to parse some string. Rather than incrementally maintain all dependencies on all input strings, the user can declare these intermediate tables as opaque and abolish them before any call to the DCG. This predicate, when called as a compiler directive, implies that its arguments are tabled predicates.

The following predicates are used to manipulate incrementally maintained tables:

incr_assert(+Clause)

increval
is a version of assert/1 for dynamic predicates declared as
use_incremental_dynamic. This adds the clause to the database after any other clauses for the same predicate currently in the database. It then updates all incrementally maintained tables that depend on this predicate.

incr_assertz(+Clause)

increval
is the same as incr_assert/1.

incr_asserta(+Clause)

increval
is the same as incr_assert/1 except that it adds the clause before any other clauses for the same predicate currently in the database.

incr_retractall(+Clause)

increval
is a version of retractall/1 for dynamic predicates declared as use_incremental_dynamic. This removes all clauses in the database that match Clause. It then updates all incrementally maintained tables that depend on this predicate.

incr_assert_inval(+Clause)

increval
is similar to incr_assert/1 except that it does not update the incrementally maintained tables, but only marks them as invalid. The tables should be updated by an explicit call to incr_table_update/0 (or /1 or /2). This separation of function allows for more efficient processing of table maintenance after a batch of operations.

incr_assertz_inval(+Clause)

increval
is similar to incr_assertz/1 except that it does not update the incrementally maintained tables, but only marks them as invalid. The tables should be updated by an explicit call to incr_table_update/0 (or /1 or /2).

incr_asserta_inval(+Clause)

increval
is similar to incr_asserta/1 except that it does not update the incrementally maintained tables, but only marks them as invalid. The tables should be updated by an explicit call to incr_table_update/0 (or /1 or /2).

incr_retractall_inval(+Clause)

increval
is similar to incr_retractall/1 except that it does not update the incrementally maintained tables, but only marks them as invalid. The tables should be updated by an explicit call to incr_table_update/0 (or /1 or /2).

incr_retract_inval(+Clause)

increval
is similar to retract/1 but is applied to dynamic predicates declared with
use_incremental_dynamic. It removes the matching clauses through backtracking and marks the depending tables as invalid. All invalid tables should be updated by an explicit call to incr_table_update/0 (or /1 or /2).

incr_table_update

increval
is called after base predicates have been changed (by incr_assert_inval/1 and/or
incr_retractall_inval/1 or friends). This predicate updates all the incrementally maintained tables whose contents change as a result of those changes to the base predicates. This update operation is separated from the operations that change the base predicates (incr_assert_inval and incr_retractall_inval) so that a set of base predicate changes can be processed all at once, which may be much more efficient that updating the tables at every base update.

incr_table_update(-GoalList)

increval
is similar to incr_table_update/0 in that it updates the incrementally maintained tables after changes to base predicates. It returns the list of goals to incrementally maintained tables whose tables were changed in the update process.

incr_table_update(+SkelList,-GoalList)

increval
is similar to incr_table_update/1 in that it updates the incrementally maintained tables after changes to base predicates. The first argument is a list of predicate skeletons (open terms) for incrementally maintained tables. The predicate returns in GoalList a list of goals whose skeletons appear in SkelList and whose tables were changed in the update process. So SkelList acts as a filter to restrict the goals that are returned to those of interest. If SkelList is a variable or the empty list, all affected goals are returned in GoalList.

incr_invalidate_call(+Goal)

increval
is used to directly invalidate a call to an incrementally maintained table. Goal is the tabled call to invalidate. A subsequent invocation of incr_table_update will cause that tabled goal to be recomputed and all incrementally maintained tables depending on that goal will be updated. This predicate can be used if a tabled predicate depends on some external data and not (only) on use_incremental_dynamic predicates. If, for example, an incrementally maintained predicate depends on a relation stored in an external relational database (perhaps accessed through the ODBC interface), then this predicate can be used to invalidate the table when the external relation changes. The application programmer must know when the external relation changes and invoke this predicate as necessary.

incr_directly_depends(?DependentGoal,?Goal)

increval
accesses the dependency structures used by the incremental table maintenance subsystem to provide information about which incremental table calls depend on which others. At least one of DependentGoal and Goal must be bound. If DependentGoal is bound, then this predicate will return in Goal through backtracking the goals for all incrementally maintained tables that tables unifying (?) with DependentGoal directly depend on. If Goal is bound, then it returns the directly dependent tabled goals in DependentGoal. [check this out...]

incr_trans_depends(?DependentGoal,?Goal)

increval
is similar to incr_directly_depends except that it returns goals according to the transitive closure of the ``directly depends'' relation.