Various aspects of the state of an instance of XSB -- information
about what predicates, modules, or dynamic clauses have been loaded,
their object files, along with other information can be inspected in
ways similar to many Prolog systems. However, because the atom-based
module system of XSB may associate structures with particular modules,
predicates are provided to inspect these elements as well. The
following descriptions of state predicates use the terms predicate indicator, term indicator and current module to
mean the following:
- current_input(?Stream)
- ISO
Succeeds iff stream Stream is the current input stream, or
procedurally unifies Stream with the current input stream.
Error Cases
- Stream is neither a variable nor a stream identifier
- domain_error(stream_or_variable,Stream))
- current_output(?Stream)
- ISO
Succeeds iff stream Stream is the current output stream, or
procedurally unifies Stream with the current output stream.
Error Cases
- Stream is neither a variable nor a stream identifier
- domain_error(stream_or_variable,Stream))
- current_prolog_flag(?Flag_Name, ?Value)
- ISO
current_prolog_flag/2 allows the user to examine both dynamic
aspects of XSB along with certain non-changeable ISO
flags 6.6. This predicate is based upon the predicate xsb_flag/2.
Error Cases
- Flag_Name is neither a variable nor an atom.
- domain_error(atom_or_variable,Flag_Name)
- set_prolog_flag(?Flag_Name, ?Value)
- ISO
set_prolog_flag/2 allows the user to change settable prolog
flags. Currently the only settable flag is the unknown flag.
Setting the flag unknown to fail results in calls to
undefined predicates to quietly fail. Setting it to warning
causes calls to undefined predicates to generate a warning and then
fail. Setting it to error (the default) causes calls to
undefined predicates to throw an error.
Error Cases
- Flag_Name is neither a variable nor an atom.
- domain_error(settable_flag,Flag_Name)
- current_predicate(?Predicate_Indicator)
- ISO
current_predicate/1 can be used to backtrack through indicators
for loaded user or system predicates. If Predicate_Indicator
unifies with Module:F/A all loaded predicates unifying with this
indicator is returned. If Predicate_indicator is F/A,
current_predicate/1 behaves as if it were called with the form
usermod:F/A. Unlike current_functor/1 current_predicate/1 does not return indicators for predicates that
have been imported but not actually loaded into code space. For more
detailed analysis of predicate properties, the predicate predicate_property/2 can be used.
As an example to backtrack through all of the predicates defined and loaded in
module blah, regardless of whether blah is a system or a
user defined module, use:
| ?- current_predicate(blah:Predicate).
|
In this case Predicate will have the form: Functor/Arity.
To backtrack through all predicates defined and loaded in any current
module, use:
| ?- current_predicate(Module:Functor/Arity).
|
This succeeds once for every predicate that is loaded in XSB's
database.
To find the predicates having arity 3 that are loaded in usermod, use:
| ?- current_predicate(usermod:Functor/3).
|
while to find all predicates loaded in the global modules of the system
regardless of their arity, use:
| ?- current_predicate(usermod:Predicate).
|
Error Cases
- Predicate_indicator is neither a variable nor a predicate indicator
- type_error(predicate_indicator,Predicate_indicator))
- current_module(?Module)
-
The standard predicate current_module/1 allows the user to
check whether a given module is current or to generate
(through backtracking) all currently known modules. Succeeds iff
Module is one of the modules in the database. This includes
both user modules and system modules. For more detailed analysis
of module properties, the predicate module_property/2
can be used.
Note that predicate current_module/1 succeeds for a given
module even if that module does not export any predicates. There
are no error conditions associated with this predicate; if its
argument does not unify with one of the current modules, current_module/1 simply fails.
- current_module(?Module, ?ObjectFile)
-
Predicate current_module/2 gives the relationship between
the modules and their associated object file names. The file name
ObjectFile must be absolute and end with the object file
extension for the system (by default, .xwam).
It is possible for a current module to have no associated file
name (as is the case for "usermod"), or for the system to be
unable to determine the file name of a current module. In both
cases, predicate current_module/1 will succeed for this
module, while current_module/2 will fail. The system is
unable to determine the file name of a given module if that module
is not in one of the directories of the search path (see
Section 3.6). Once again, there are no error conditions
associated with this predicate; if the arguments of current_module/2 are not correct, or Module has no
associated File, the predicate will simply fail.
- current_functor(?Predicate_Indicator)
-
current_predicate/1 can be used to backtrack through indicators
for all non-atomic terms occurring in loaded modules. If Predicate_Indicator unifies with Module:F/A all term
indicators unifying with F/A in a module unifying with Module are returned. If Predicate_indicator is F/A,
current_predicate/1 behaves as if it were called with the form
usermod:F/A. Unlike current_predicate/1 current_functor/1 returns not only structures occurring in
predicates but predicates that are imported into loaded modules but
are not yet themselves loaded.
As an example, to backtrack through all of the functors of positive
arity (function and predicate symbols) that appear in the global
modules of the system regardless of whether they are system or a user
defined, use:
| ?- current_functor(Functor/Arity), Arity > 0.
|
There are no error conditions associated with this predicate; if its
argument is not a predicate indicator the predicate simply fails.
- current_index(Functor/Arity,IndexSpec)
-
XSB has a variety of ways to index dynamic predicate including
alternate argument indexing, multiple argument indexing,
star-indexing, and tries, as discussed in Section 6.13.
In addition XSB allows a choice of which argument to index for
compiled predicates as well. current_index/2 returns the index
specification for each functor/arity pair unifying with Functor/Arity and visible from the calling context of current_index/2.
- current_atom(?Atom_Indicator)
-
Generates (through backtracking) all currently known atoms, and unifies
each in turn with Atom_Indicator.
- predicate_property(?Term_Indicator, ?Property)
-
The standard predicate predicate_property/2 can be used to find
the properties of any predicate that is visible to a particular module.
Succeeds iff Term_Indicator is a term indicator for a current
predicate whose principal functor is a predicate having Property
as one of its properties. Or procedurally, Property is unified
with the currently known properties of the predicate having
Term_Indicator as its skeletal specification.
A brief description of predicate_property/2 is as follows:
- If Term_Indicator is not a variable, and is a structure
or atom, then Property is successively unified with the
various properties associated with Term_Indicator. If
Term_Indicator is not a known to the system, the call
succeeds with Property successively unified to exported and unclassified. These properties can be
considered as a default for any structure or atom.
- If Property is bound to a valid predicate property, then predicate_property/2 successively unifies Term_Indicator with the skeletal specifications of all
predicates known to the system having the specified Property.
- If Term_Indicator is a variable, then
it is unified (successively through backtracking) with the
most general term for a predicate whose known properties are
unified with Property.
- If Term_Indicator
is not a term indicator, or if Property is not a valid
predicate property, the call fails.
For example, all the loaded predicate skeletal specifications in
module "usermod" may be enumerated using:
| ?- predicate_property(Pred, loaded).
|
Also the following query finds all predicate skeletal specifications that
are exported by module blah:
| ?- predicate_property(blah:Pred, exported).
|
Currently, the following properties are associated with predicates
either implicitly or by declaration. Double lines show property
categories, and a predicate can have at most one property of each
category.
| Property |
Explanation |
| unclassified |
The predicate symbol is not yet classified according |
| |
to this category. This property has various meanings. |
| |
Usually for exported predicate symbols in system or |
| |
user defined modules it means that the predicate is |
| |
yet unloaded (because it has not been used). |
| |
In usermod it usually means that the predicate |
| |
is either a function symbol, or an unloaded predicate |
| |
symbol (including constants). |
| dynamic |
The predicate is dynamic. |
| loaded |
The predicate (including internal predicates) is a |
| |
Prolog predicate loaded into the module in question; |
| |
this is always the case for predicates in usermod. |
| unloaded |
The predicate is yet unloaded into the module |
| |
in question. |
| foreign |
The predicate is a foreign predicate. This implies that |
| |
the predicate is already loaded in the system, because |
| |
currently there is no way for XSB to know that a |
| |
predicate is a foreign predicate until it is loaded in |
| |
the system. |
| exported |
The predicate symbol is exported by the module in |
| |
question; in other words the predicate symbol is |
| |
visible to any other module in the system. |
| local |
The predicate symbol is local to the module |
| |
in question. |
| imported_from(Mod) |
The predicate symbol is imported into the module in |
| |
question from module Mod. |
| spied |
The predicate symbol has been declared spied |
| |
(either conditionally or unconditionally). |
| tabled |
The predicate has been declared tabled. |
| shared |
The predicate has been declared shared in the |
| |
multi-threaded engine. This means that any dynamic |
| |
code or tables for this predicate will be shared among |
| |
threads, but it does not affect static, non-tabled code. |
| xsb_standard_pred |
The predicate symbol has the same Functor and Arity as |
| |
one of XSB's standard predicates, and is available to |
| |
the user without needing to load a file or import the |
| |
predicate from a module. |
Finally, since dynamic is usually declared as an operator with
precedence greater than 999, writing the following:
| ?- predicate_property(X, dynamic).
|
will cause a syntax error. The way to achieve the desired result is to
parenthesize the operator like in:
| ?- predicate_property(X, (dynamic)).
|
- module_property(?Module, ?Property)
-
The standard predicate module_property/2 can be used to find the
properties of any current module.
Succeeds iff Module is the name of a current module having
Property as one of its properties. Or procedurally, Property
is unified with the currently known properties of the module having
Module as its name.
Currently, the following properties are associated with modules
implicitly
| Property |
Explanation |
| unloaded |
The module (including system modules) though it is |
| |
current, is yet unloaded in the system. |
| loaded |
The module (including system modules) is loaded in the |
| |
system; this is always the case for usermod. |
- listing
-
Lists in the current output stream the clauses for all dynamic
predicates found in module usermod. Note that listing/0
does not list any compiled predicates unless they have the
dynamic property (see predicate_property/2). A
predicate gets the dynamic property when it is explicitly
declared as dynamic, or automatically acquires it when some
clauses for that predicate are asserted in the database. In
cases where a predicate was compiled but converted to dynamic
by asserting additional clauses for that predicate, listing/0
will just display an indication that there exist compiled clauses
for that predicate and only the dynamically created clauses of the
predicate will be listed. For example:
| ?- [user].
a(X) :- b(X).
a(1).
yes
| ?- assert(a(3)).
yes
| ?- listing.
a(A) :-
$compiled.
a(3).
yes
|
Predicate listing/0 always succeeds. The query:
is just a notational shorthand for the query:
- listing(+Predicate_Indicator)
-
If Predicate_Indicator is a variable then listing/1 is
equivalent to listing/0.
If Predicate_Indicator is an atom, then listing/1
lists the dynamic clauses for all predicates of that name found in
module usermod of the database.
The argument Predicate_Indicator can also be a predicate
indicator of the form Name/Arity in which case only the
clauses for the specified predicate are listed.
Finally, it is possible for Predicate_Indicator
to be a list of predicate indicators and/or atoms; e.g.
| ?- listing([foo/2, bar, blah/4]).
|
If Predicate_Indicator is not a variable, an atom or a predicate
indicator (or list of predicate indicators) of the form Name/Arity,
predicate listing/1 will simply fail.
In future releases of XSB, we intend to allow the user to
specify a predicate indicator of the form Module:Name/Arity
as argument of listing/1.
- xsb_configuration(Feature_Name, ?Value)
-
Succeeds iff the current value of the XSB feature Feature_Name is Value.
This predicate provides information on a wide variety of features
related to how XSB was built, including the compiler used, the compiler
and loader flags, the machine and OS on which XSB was built, the
release number, the various directories that XSB uses to find its
libraries, etc.
To find all features and their values, ask the following query:
| ?- xsb_configuration(FeatureName, Value), fail.
|
Here is how xsb_configuration might look like:
xsb_configuration(architecture, 'i686-pc-linux-gnu').
%% configuration is usualy the same as architecture, but it can also
%% contain special tags, {\it e.g.}, i686-pc-linux-gnu-dbg, for a verion
%% built with debugging enabled.
xsb_configuration(configuration, 'i686-pc-linux-gnu-dbg').
xsb_configuration(host_os, 'linux-gnu').
xsb_configuration(os_version, '2.34').
xsb_configuration(os_type, 'linux-gnu').
xsb_configuration(host_vendor, 'pc').
xsb_configuration(host_cpu, 'i686').
xsb_configuration(compiler, 'gcc').
xsb_configuration(compiler_flags, ' -ansi -pedantic -Wall -g').
xsb_configuration(loader_flags, ' -lm -ldl -Wl,-export-dynamic').
xsb_configuration(compile_mode, 'debug').
%% The following is XSB release information
xsb_configuration(major_version, '1').
xsb_configuration(minor_version, '9').
xsb_configuration(beta_version, '3').
xsb_configuration(version, '1.9-b3').
xsb_configuration(codename, 'Code Breaker').
xsb_configuration(release_date, date(1998, 10, 17)).
%% XSB query evaluation directive
xsb_configuration(scheduling_strategy, '(batched)').
%% Support for other languages
xsb_configuration(perl_support, 'yes').v
xsb_configuration(perl_archlib, '/usr/lib/perl5/i386-linux/5.00404').
xsb_configuration(perl_cc_compiler, 'cc').
xsb_configuration(perl_ccflags, '-Dbool=char -DHAS_BOOL -I/usr/local/include').
xsb_configuration(perl_libs, '-lnsl -lndbm -lgdbm -ldb -ldl -lm -lc -lposix -lcrypt').
xsb_configuration(javac, '/usr/bin/javac').
/* Tells where XSB is currently residing; can be moved */
xsb_configuration(install_dir, InstallDir) :- ...
/* User home directory. Usually HOME. If that is null, then it would
be the directory where XSB is currently residing.
This is where we expect to find the .xsb directory */
xsb_configuration(user_home, Home) :- ...
/* Where XSB invocation script is residing */
xsb_configuration(scriptdir, ScriptDir) :- ...
/* where are cmplib, syslib, lib, packages, etc live */
xsb_configuration(cmplibdir, CmplibDir) :- ...
xsb_configuration(libdir, LibDir) :- ...
xsb_configuration(syslibdir, SyslibDir) :- ...
xsb_configuration(packagesdir, PackDir) :- ...
xsb_configuration(etcdir, EtcDir) :- ...
/* architecture and configuration specific directories */
xsb_configuration(config_dir, ConfigDir) :- ...
xsb_configuration(config_libdir, ConfigLibdir) :- ...
/* site-specific directories */
xsb_configuration(site_dir, '/usr/local/XSB/site').
xsb_configuration(site_libdir, SiteLibdir) :- ...
/* site and configuration-specific directories */
xsb_configuration(site_config_dir, SiteConfigDir) :- ...
xsb_configuration(site_config_libdir, SiteConfigLibdir) :- ...
/* Where user's arch-specific libraries are found by default. */
xsb_configuration(user_config_libdir, UserConfigLibdir) :- ...
- xsb_flag(?Flag_Name, ?Value)
-
Succeeds iff the current value of the XSB flag Flag_Name is
Value. So, one can enumerate all the flag names which the system
currently understands, together with their current values by using the
following query:
| ?- xsb_flag(FlagName, Value), fail.
|
The flag names currently supported are:
- backtrace_on_error on iff system-handled errors
automatically print out the trace of the execution stack where the
error arose, off otherwise. Default is on. In the
multi-threaded engine, this flag is thread-specific and controls
whether the backtrace for a current execution will be printed to STDERR.
- dcg_style the DCG style currently used; xsb or standard (standard is used in Quintus, SICSTUS, etc.). See
Section 10.4 for more details. Default is xsb. This flag affects all threads in the process.
- debugging on iff debug mode is on; off otherwise.
This flag affects all threads in the process.
- heap_garbage_collection indirection, none, sliding, or copying depending on the heap garbage collection
strategy that is currently being employed (see also
Section 3.7). Default is indirection. This
flag is private to each thread.
- clause_garbage_collection on if garbage collection for
retracted clauses is allowed, and off otherwise. Default is on. This flag is private to each thread.
- atom_garbage_collection on if garbage collection for
atomic constants is allowed, and off otherwise. Default is on.
This flag is global for all threads (currently, string garbage
collection will only be invoked if there is a single active thread.)
- table_gc_action abolish_tables_transitively if
predicates or subgoals that depend on a conditional answer of an
abolished table are to be abolished automatically, and abolish_tables_singly if not. Default is abolish_tables_transitively. This flag affects all threads in
the process.
- goal the goal passed to XSB on command line with the `-e'
switch; `true.' if nothing is passed. This flag may be
examined, but not set.
- tracing on iff trace mode is on; off
otherwise. This flag affects all threads in the process.
- write_depth The depth to which a term is written by write-like predicates. Default is 64. This flag affects all
threads in the process.
- thread_glsize In the multi-threaded engine, the initial
size, in kbytes, of the global and local stack area of a newly
created thread if no such option is explicitly passed. By default
this is 768 (or 1536 for 64-bit configurations), or whatever was
passed in if the command-line option -m was used, but that
value may be modified at any time by resetting the flag. This flag
affects a thread created by any thread in the process.
- thread_tcpsize In the multi-threaded engine, the initial
size, in kbytes, of the trail and choice point area of a newly
created thread if no such option is explicitly passed. By default
this is 768 (or 1536 for 64-bit configurations), or whatever was
passed in if the command-line option -c was used, but that
value may be modified at any time by resetting the flag. This flag
affects a thread created by any thread in the process.
- thread_complsize In the multi-threaded engine, the
initial size, in kbytes, of the completion stack area of a newly
created thread if no such option is explicitly passed. By default
this is 64 (or 128 for 64-bit configurations), or whatever was
passed in if the command-line option -0 was used, but that
value may be modified at any time by resetting the flag. This flag
affects a thread created by any thread in the process.
- thread_pdlsize In the multi-threaded engine, the initial
size, in kbytes, of the unification stack area of a newly created
thread if no such option is explicitly passed. By default this is
64 (or 128 for 64-bit configurations), or whatever was passed in if
the command-line option -m was used, but that value may be
modified at any time by resetting the flag. This flag affects a
thread created by any thread in the process.
- thread_detached In the multi-threaded engine, this
specifies whether threads are to be created as detached or joinable
if no explicit option is passed. A value of true indicates
that threads are to be created as detached, and false as
joinable. If this flag is not set, its default is false.
- max_threads In the multi-threaded engine, the maximum
number of valid threads. By default this is 1024 and this value may
not be reset at runtime, but it may be set by the command-line
option -max_threads.
- max_queue_size In the multi-threaded engine, the default
maximum number of terms a message queue contains before writes to
the message queue block. By default this is 100.
Note that xsb_flag is used only for dynamic XSB settings, i.e., settings that might change between sessions (via command line
arguments) or within the same session (via modifiable flags). For
static configuration information, the predicate xsb_configuration/2 is used.
- set_xsb_flag(+Flag_Name, +Value)
-
Changes one of the dynamic XSB settings described for xsb_flag/2.
Error Cases
- Flag_Name or Value is a variable.
- Flag_Name is not the name of a recognized XSB flag.
- domain_error(xsb_flag,Flag_Name)
- hilog_symbol(?Symbol)
-
Succeeds iff Symbol has been declared as a HiLog symbol, or
procedurally unifies Symbol with one of the currently known
(because of a prior declaration) HiLog symbols. The HiLog symbols
are always atoms, but if the argument of hilog_symbol,
though instantiated, is not an atom the predicate simply fails.
So, one can enumerate all the HiLog symbols by using the following
query:
- current_op(?Precedence, ?Specifier, ?Name)
- ISO
This predicate is used to examine the set of operators currently
in force. It succeeds when the atom Name is currently an
operator of type Specifier and precedence Precedence. None
of the arguments of current_op/3 need to be instantiated at
the time of the call, but if they are, they must be of the
following types:
- Precedence
- must be an integer in the range from 1 to 1200.
- Specifier
- must be one of the atoms:
xfx xfy yfx fx fy hx hy xf yf
- Name
- it must be an atom.
Error Cases
- Precedence is neither a variable nor an integer in the
range from 1 to 1200.
- domain_error(operator_priority,Precedence)
- Specifier is neither a variable nor an operator
specifier of the types above.
- domain_error(operator_specifier,Specifier)
- Name is neither a variable nor an atom.
- domain_error(atom_or_variable,Name)
- hilog_op(?Precedence, ?Type, ?Name)
-
This predicate has exactly the same behaviour as current_op/3
with the only difference that Type can only have the values
hx and hy.
