Fast/concurrent update of facts (runtime)

Author(s): The Ciao Development Team, Daniel Cabeza, Manuel Carro.

This module implements the assert/retract family of predicates to manipulate data predicates (facts).

Usage and interface

Documentation on exports

asserta_fact(Fact)

Fact is added to the corresponding data predicate. The fact becomes the first clause of the predicate concerned.

Usage:

  • The following properties should hold at call time:
    (basic_props:cgoal/1)Fact is a term which represents a goal, i.e., an atom or a structure.
Meta-predicate with arguments: asserta_fact(fact).

asserta_fact(Fact,Ref)

Same as asserta_fact/1, instantiating Ref to a unique identifier of the asserted fact.

Usage:

  • The following properties should hold at call time:
    (basic_props:cgoal/1)Fact is a term which represents a goal, i.e., an atom or a structure.
    (term_typing:var/1)Ref is a free variable.
  • The following properties should hold upon exit:
    (datafacts_rt:reference/1)Ref is a reference of a dynamic or data clause.
Meta-predicate with arguments: asserta_fact(fact,?).

assertz_fact(Fact)

Fact is added to the corresponding data predicate. The fact becomes the last clause of the predicate concerned.

Usage:

  • The following properties should hold at call time:
    (basic_props:cgoal/1)Fact is a term which represents a goal, i.e., an atom or a structure.
  • The following properties should hold upon exit:
    (basic_props:cgoal/1)Fact is a term which represents a goal, i.e., an atom or a structure.
Meta-predicate with arguments: assertz_fact(fact).

assertz_fact(Fact,Ref)

Same as assertz_fact/1, instantiating Ref to a unique identifier of the asserted fact.

Usage:

  • The following properties should hold at call time:
    (basic_props:cgoal/1)Fact is a term which represents a goal, i.e., an atom or a structure.
    (term_typing:var/1)Ref is a free variable.
  • The following properties should hold upon exit:
    (datafacts_rt:reference/1)Ref is a reference of a dynamic or data clause.
Meta-predicate with arguments: assertz_fact(fact,?).

current_fact(Fact)

Gives on backtracking all the facts defined as data or concurrent which unify with Fact. It is faster than calling the predicate explicitly, which do invoke the meta-interpreter. If the Fact has been defined as concurrent and has not been closed, current_fact/1 will wait (instead of failing) for more clauses to appear after the last clause of Fact is returned.

Usage:

  • The following properties should hold at call time:
    (basic_props:cgoal/1)Fact is a term which represents a goal, i.e., an atom or a structure.
  • The following properties should hold upon exit:
    (basic_props:cgoal/1)Fact is a term which represents a goal, i.e., an atom or a structure.
Meta-predicate with arguments: current_fact(fact).

current_fact(Fact,Ref)

Fact is a fact of a data predicate and Ref is its reference identifying it uniquely.

Usage 1:

Gives on backtracking all the facts defined as data which unify with Fact, instantiating Ref to a unique identifier for each fact.

  • The following properties should hold at call time:
    (basic_props:cgoal/1)Fact is a term which represents a goal, i.e., an atom or a structure.
    (term_typing:var/1)Ref is a free variable.
  • The following properties should hold upon exit:
    (datafacts_rt:reference/1)Ref is a reference of a dynamic or data clause.

Usage 2:

Given Ref, unifies Fact with the fact identified by it.

  • Call and exit should be compatible with:
    (basic_props:cgoal/1)Fact is a term which represents a goal, i.e., an atom or a structure.
  • The following properties should hold at call time:
    (datafacts_rt:reference/1)Ref is a reference of a dynamic or data clause.
  • The following properties should hold upon exit:
    (basic_props:cgoal/1)Fact is a term which represents a goal, i.e., an atom or a structure.
Meta-predicate with arguments: current_fact(fact,?).

retract_fact(Fact)

Unifies Fact with the first matching fact of a data predicate, and then erases it. On backtracking successively unifies with and erases new matching facts. If Fact is declared as concurrent and is non-closed, retract_fact/1 will wait for more clauses or for the closing of the predicate after the last matching clause has been removed.

Usage:

  • The following properties should hold at call time:
    (basic_props:cgoal/1)Fact is a term which represents a goal, i.e., an atom or a structure.
  • The following properties should hold upon exit:
    (basic_props:cgoal/1)Fact is a term which represents a goal, i.e., an atom or a structure.
Meta-predicate with arguments: retract_fact(fact).

retractall_fact(Fact)

Erase all the facts of a data predicate unifying with Fact. Even if all facts are removed, the predicate continues to exist.

Usage:

  • The following properties should hold at call time:
    (basic_props:cgoal/1)Fact is a term which represents a goal, i.e., an atom or a structure.
  • The following properties should hold upon exit:
    (basic_props:cgoal/1)Fact is a term which represents a goal, i.e., an atom or a structure.
Meta-predicate with arguments: retractall_fact(fact).

current_fact_nb(Fact)

Behaves as current_fact/1 but a fact is never waited on even if it is concurrent and non-closed.

Usage:

  • The following properties should hold at call time:
    (basic_props:cgoal/1)Fact is a term which represents a goal, i.e., an atom or a structure.
  • The following properties should hold upon exit:
    (basic_props:cgoal/1)Fact is a term which represents a goal, i.e., an atom or a structure.
Meta-predicate with arguments: current_fact_nb(fact).

retract_fact_nb(Fact)

Behaves as retract_fact/1, but never waits on a fact, even if it has been declared as concurrent and is non-closed.

Usage:

  • The following properties should hold at call time:
    (basic_props:cgoal/1)Fact is a term which represents a goal, i.e., an atom or a structure.
  • The following properties should hold upon exit:
    (basic_props:cgoal/1)Fact is a term which represents a goal, i.e., an atom or a structure.
Meta-predicate with arguments: retract_fact_nb(fact).

close_predicate(Pred)

Changes the behavior of the predicate Pred if it has been declared as a concurrent predicate: calls to this predicate will fail (instead of wait) if no more clauses of Pred are available.

Usage:

  • The following properties should hold at call time:
    (basic_props:cgoal/1)Pred is a term which represents a goal, i.e., an atom or a structure.
  • The following properties should hold upon exit:
    (basic_props:cgoal/1)Pred is a term which represents a goal, i.e., an atom or a structure.
Meta-predicate with arguments: close_predicate(fact).

open_predicate(Pred)

Reverts the behavior of concurrent predicate Pred to waiting instead of failing if no more clauses of Pred are available.

Usage:

  • The following properties should hold at call time:
    (basic_props:cgoal/1)Pred is a term which represents a goal, i.e., an atom or a structure.
  • The following properties should hold upon exit:
    (basic_props:cgoal/1)Pred is a term which represents a goal, i.e., an atom or a structure.
Meta-predicate with arguments: open_predicate(fact).

PREDICATEset_fact/1
set_fact(Fact)

Sets Fact as the unique fact of the corresponding data predicate.

Usage:

  • The following properties should hold at call time:
    (basic_props:cgoal/1)Fact is a term which represents a goal, i.e., an atom or a structure.
  • The following properties should hold upon exit:
    (basic_props:cgoal/1)Fact is a term which represents a goal, i.e., an atom or a structure.
Meta-predicate with arguments: set_fact(fact).

PREDICATEerase/1
erase(Ref)

Deletes the clause referenced by Ref.

Usage:

  • The following properties should hold at call time:
    (datafacts_rt:reference/1)Ref is a reference of a dynamic or data clause.
  • The following properties should hold upon exit:
    (datafacts_rt:reference/1)Ref is a reference of a dynamic or data clause.
  • The following properties should hold globally:
    (basic_props:native/1)This predicate is understood natively by CiaoPP.

Usage:reference(R)

R is a reference of a dynamic or data clause.

    Documentation on internals

    DECLARATIONdata/1

    Usage::- data(Predicates).

    Defines each predicate in Predicates as a data predicate. If a predicate is defined data in a file, it must be defined data in every file containing clauses for that predicate. The directive should precede all clauses of the affected predicates. This directive is defined as a prefix operator in the compiler.

    DECLARATIONconcurrent/1

    Usage::- concurrent(Predicates).

    Defines each predicate in Predicates as a concurrent predicate. If a predicate is defined concurrent in a file, it must be defined concurrent in every file containing clauses for that predicate. The directive should precede all clauses of the affected predicates. This directive is defined as a prefix operator in the compiler.

    Documentation on imports

    This module has the following direct dependencies: