6.13.1 Reading Dynamic Code from Files

Several built-in predicates are available that can assert the contents of a file into XSB's database. These predicates are useful when code needs to be dynamic, or when the they contain a large number of clauses or facts. Configured properly, files containing millions of facts can be read and asserted into memory in under a minute, making XSB suitable for certain kinds of in-memory database operations ^6.9.

Each of the predicates in this section allow loading from files with proper prolog extensions, and makes use of the XSB library paths. See Sections 3.6 and 3.3 for details.

load_dyn(+FileName)

Asserts the contents of file FileName into the database. All existing clauses of the predicates in the file that already appear in the database, are retracted, unless there is a multifile/1 declaration for them. An indexing declaration of a predicate p/n in FileName will be observed as long as the declarations occur before the first clause of p/n. file will be observed as Clauses in FileName must be in a format that read/1 will process. So, for example, operators are permitted. As usual, clauses of predicates are not retracted if they are compiled instead of dynamically asserted. All predicates are loaded into usermod. Module declarations such as :- export are ignored and a warning is issued.

Dynamically loaded files can be filtered through the XSB preprocessor. To do this, put the following in the source file:

    :- compiler_options([xpp_on]).

Of course, the name compiler_options might seem like a misnomer here (since the file is not being compiled), but it is convenient to use the same directive both for compiling and loading, in case the same source file is used both ways.

Error Cases

• FileName is a variable
  • instantiation_error
• FileName is not an atom.
  • type_error(atom,Filename)
• FileName has been loaded previously in the session and there is more than one active thread.
  • misc_error

load_dyn(+FileName,+Dir)

Asserts the contents of file FileName into the database. Dir indicates whether assertz or asserta is to be used. If Dir is z, then assertz is used and the behavior of load_dyn(FileName) is obtained. If Dir is a, then asserta is used to add the clauses to the database, and clauses will be in the reverse order of their appearance in the input file. asserta is faster than assertz for predicates such that their indexing and data result in many hash collisions. Dir is ignored for facts in FileName that are trie-indexed.

Error Cases

• FileName is a variable
  • instantiation_error
• FileName is not an atom:
  • type_error(atom,FileName)
• Dir is not equal to a or z ^6.10:
  • domain_error(a_or_z,Dir)
• FileName has been loaded previously in the session and there is more than one active thread.
  • misc_error

load_dync(+FileName)

Acts as load_dyn/1, but assumes that facts are in ``canonical'' format and is much faster as a result. In XSB, a term is in canonical format if it does not use any operators other than list notation and comma-list notation. This is the format produced by the predicate write_canonical/1. (See cvt_canonical/2 to convert a file from the usual read/1 format to read_canonical format.) As usual, clauses of predicates are not retracted if they are compiled instead of dynamically asserted. All predicates are loaded into usermod. :- export declarations are ignored and a warning is issued.

Notice that this predicate can be used to load files of Datalog facts (since they will be in canonical format). This predicate is significantly faster than load_dyn/1 and should be used when speed is important. (See load_dync/2 below for further efficiency considerations.) A file that is to be dynamically loaded often but not often modified by hand should be loaded with this predicate.

As with load_dyn/1, the source file can be filtered through the C preprocessor. However, since all clauses in such a file must be in canonical form, the compiler_options/1 directive should look as follows:

     :-(compiler_options('.'(xpp_on,[]))).

Error Cases

• FileName is a variable
  • instantiation_error
• FileName is not an atom.
  • type_error(atom,FileName)
• FileName has been loaded previously in the session and there is more than one active thread.
  • misc_error

load_dync(+FileName,+Dir)

consult
Acts as load_dyn/2, but assumes that facts are in ``canonical'' format. Dir is ignored for trie-asserted code, but otherwise indicates whether assertz or asserta is to be used. If Dir is z, then assertz is used and the exact behavior of load_dync(FileName) is obtained. If Dir is a, then asserta is used to add the clauses to the database, and clauses will end up in the reverse order of their appearance in the input file.

Setting Dir to a for non trie-asserted code can sometimes be much faster than the default of z. The reason has to do with how indexes on dynamic code are represented. Indexes use hash tables with bucket chains. No pointers are kept to the ends of bucket chains, so when adding a new clause to the end of a bucket (as in assertz), the entire chain must be run. Notice that in the limiting case of only one populated bucket (e.g., when all clauses have the same index term), this makes assertz-ing a sequence of clauses quadratic. However, when using asserta, the new clause is added to the beginning of its hash bucket, and this can be done in constant time, resulting in linear behavior for asserta-ing a sequence of clauses.

Error Cases

• FileName is a variable
  • instantiation_error
• FileName is not an atom:
  • type_error(atom,FileName)
• Dir is not instantiated to a or z ^6.11:
  • domain_error(a_or_z,Dir)
• FileName has been loaded previously in the session and there is more than one active thread.
  • misc_error

ensure_loaded(+FileName,+Action)

This predicate does nothing if FileName has been loaded or consulted into XSB, and has not changed since it was loaded or consulted. Otherwise

• If Action is instantiated to dyn the behavior is as load_dyn/1 (or load_dyn(FileName,z)).

• If Action is instantiated to dyna the behavior is as load_dyn(FileName,a).

• If Action is instantiated to dync the behavior is as load_dync/1 (or load_dync(FileName,z)).

• If Action is instantiated to dynca the behavior is as load_dync(FileName,a).

• If Action is instantiated to consult, FileName is consulted.

Error Cases

• FileName is not instantiated:
  • instantiation_error
• FileName is not an atom:
  • type_error(atom,FileName)
• Action is not a valid load action as described above
  • domain_error(loadAction,Action)

cvt_canonical(+FileName1,+FileName2)

consult
Converts a file from standard term format to ``canonical'' format. The input file name is FileName1; the converted file is put in FileName2. This predicate can be used to convert a file in standard Prolog format to one loadable by load_dync/1.