1
\section{Information about the System State} \label{State}
2
%========================================================
3
\index{state of the system} \index{system, state of}
5
Various aspects of the state of an instance of XSB --- information
6
about what predicates, modules, or dynamic clauses have been loaded,
7
their object files, along with other information can be inspected in
8
ways similar to many Prolog systems. However, because the atom-based
9
module system of XSB may associate structures with particular modules,
10
predicates are provided to inspect these elements as well. The
11
following descriptions of {\em state} predicates use the terms {\em
12
predicate indicator}, {\em term indicator} and {\em current module} to
14
\index{predicate indicator}
15
\index{term indicator}
17
\item By {\em predicate indicator} \index{predicate indicator} we mean a
18
{\em compound term} of the form {\tt M:F/A} or simply {\tt F/A}.
19
When the predicate indicator is fully instantiated, {\tt M} and {\tt F}
20
are atoms representing the {\em module name} and the {\em functor}
21
of the predicate respectively and {\tt A} is a non negative integer
22
representing its {\em arity}.
24
Example: {\tt usermod:append/3}
25
\item By {\em term indicator} \index{term indicator} we mean a predicate or
26
function symbol of arity N followed by a sequence of N variables
27
(enclosed in parentheses if N is greater than zero). A term indicator
28
may optionally be prefixed by the module name, thus it can be of the
31
Example: {\tt usermod:append(\_,\_,\_)}
32
\item A module {\tt M} becomes a {\em current (i.e. ``known'') module} as
33
soon as it is loaded in the system or when another module that is
34
loaded in the system imports some predicates from module {\tt M}.
36
Note that due to the dynamic loading of \ourprolog, a module can be
37
current even if it has not been loaded, and that some predicates of
38
that module may not be defined. In fact, a module can be current even
39
if it does not exist. This situation occurs when a predicate is
40
improperly imported from a non-existent module. Despite this,
41
a module can never lose the property of being {\em current}.
46
\ournewitem{current\_input(?Stream)}{ISO}\index{\texttt{current\_input/1}}
47
Succeeds iff stream {\tt Stream} is the current input stream, or
48
procedurally unifies {\tt Stream} with the current input stream.
52
\item {\tt Stream} is neither a variable nor a stream identifier
54
\item {\tt domain\_error(stream\_or\_variable,Stream))}
58
\ournewitem{current\_output(?Stream)}{ISO}\index{\texttt{current\_output/1}}
59
Succeeds iff stream {\tt Stream} is the current output stream, or
60
procedurally unifies {\tt Stream} with the current output stream.
64
\item {\tt Stream} is neither a variable nor a stream identifier
66
\item {\tt domain\_error(stream\_or\_variable,Stream))}
70
\ournewitem{current\_prolog\_flag(?Flag\_Name, ?Value)}{ISO}
71
\index{\texttt{current\_prolog\_flag/2}}
73
{\tt current\_prolog\_flag/2} allows the user to examine both dynamic
74
aspects of XSB along with certain non-changable ISO
75
flags~\footnote{The ISO flags {\tt
76
char\_conversion} and {\tt double\_quotes} are not yet
77
implemented.}. This predicate is based upon the predicate {\tt
82
\item {\tt Flag\_Name} is neither a variable nor an atom.
84
\item {\tt domain\_error(atom\_or\_variable,Flag\_Name)}
88
\ournewitem{set\_prolog\_flag(?Flag\_Name, ?Value)}{ISO}
89
\index{\texttt{set\_prolog\_flag/2}}
91
{\tt set\_prolog\_flag/2} allows the user to change settable prolog
92
flags. Currently the only settable flag is the {\tt unknown} flag.
93
Setting the flag {\tt unknown} to {\tt fail} results in calls to
94
undefined predicates to quietly fail. Setting it to {\tt warning}
95
causes calls to undefined predicates to generate a warning and then
96
fail. Setting it to {\tt error} (the default) causes calls to
97
undefined predicates to throw an error.
101
\item {\tt Flag\_Name} is neither a variable nor an atom.
103
\item {\tt domain\_error(settable\_flag,Flag\_Name)}
107
\ournewitem{current\_predicate(?Predicate\_Indicator)}{ISO}
108
\index{\texttt{current\_predicate/1}}
110
{\tt current\_predicate/1} can be used to backtrack through indicators
111
for loaded user or system predicates. If {\tt Predicate\_Indicator}
112
unifies with {\tt Module:F/A} all loaded predicates unifying with this
113
indicator is returned. If {\tt Predicate\_indicator} is {\tt F/A},
114
{\tt current\_predicate/1} behaves as if it were called with the form
115
{\tt usermod:F/A}. Unlike {\tt current\_functor/1} {\tt
116
current\_predicate/1}does not return indicators for predicates that
117
have been imported but not actually loaded into code space. For more
118
detailed analysis of predicate properties, the predicate {\tt
119
predicate\_property/2} can be used.
121
As an example to backtrack through all of the predicates defined and loaded in
122
module {\tt blah}, regardless of whether {\tt blah} is a system or a
123
user defined module, use:
126
\> \> | ?- current\_predicate(blah:Predicate).
129
In this case {\tt Predicate} will have the form: {\tt Functor/Arity}.
131
To backtrack through all predicates defined and loaded in any current
135
\> \> | ?- current\_predicate(Module:Functor/Arity).
138
This succeeds once for every predicate that is loaded in \ourprolog's
141
To find the predicates having arity 3 that are loaded in {\tt
145
\> \> | ?- current\_predicate(usermod:Functor/3).
148
while to find all predicates loaded in the global modules of the system
149
regardless of their arity, use:
152
\> \> | ?- current\_predicate(usermod:Predicate). \\
158
\item {\tt Predicate\_indicator} is neither a variable nor a predicate indicator
160
\item {\tt type\_error(predicate\_indicator,Predicate\_indicator))}
164
%-----------------------------------------------------------------------------------------------
166
%TLS: I don't see that this gives us anything useful over
167
%current_predicate/1, so why confuse the user?
168
%\ouritem{current\_predicate(?Name, ?Term\_Indicator)}
169
%\index{\texttt{current\_predicate/2}}
170
% Succeeds iff {\tt Term\_Indicator} is the most general term
171
% corresponding to one of the predicates having functor {\tt Name} that are
172
% defined and loaded in a particular module in the database.
173
% (The module can be either system or user defined).
174
% Or procedurally, {\tt current\_predicate/2}
175
% unifies {\tt Name} with the name of a loaded predicate, and
176
% {\tt Term\_Indicator} with the most general term corresponding to that
177
% predicate. The flavours of this predicate are analogous to those of
178
% {\tt current\_predicate/1} and behave according to whether
179
% {\tt Term\_Indicator} has one of the following two forms:
181
% \item{\tt Module:Term.}
182
% \item{\tt Term} (module is assumed to be usermod).
184
% If {\tt Term\_Indicator} is uninstantiated, then this predicate succeeds
185
% only for {\tt usermod}. Like {\tt current\_predicate/1} only
186
% predicates that have a property in the following set:
188
% {\tt $\{$ loaded, dynamic, foreign $\}$ }
190
% (see {\tt predicate\_property/2} below) are reported.
192
% For example, if predicates {\tt foo/1} and {\tt foo/3} are defined and
193
% loaded into module {\tt blah}, the following query will return:
196
% \> \> | ?- current\_predicate(foo, blah:Term).\\
198
% \> \> Term = foo(\_638788,\_638792,\_638796); \\
200
% \> \> Term = foo(\_638788); \\
205
% If a module is specified, {\tt current\_predicate/2} succeeds only for
206
% those predicates which are defined and loaded in that module. Unless
207
% the module is one of the global modules, {\tt current\_predicate/2} fails
208
% for those predicates which are imported into that module.
210
% On the other hand, the goal:
213
% \> \> | ?- current\_predicate(Name, Term).
216
% can be used to backtrack through every predicate that is loaded in the
217
% global modules of \ourprolog's database.
219
% Note that the order of term generation is undetermined. Once again,
220
% there are no error conditions associated with this predicate; if its
221
% argument is not what it should be, the predicate simply fails.
223
%\ouritem{current\_functor(?Name, ?Term\_Indicator)}
224
%\index{\texttt{current\_functor/2}}
225
% Succeeds iff {\tt Term\_Indicator} is the most general term
226
% corresponding to one of the currently known terms having {\tt Name}
227
% as their functor appearing in a current module. (Both system and user
228
% defined modules are checked). Or procedurally,
229
% {\tt current\_functor/2} unifies {\tt Name} with the name of a functor
230
% known to the database, and {\tt Term\_Indicator} with the most
231
% general term corresponding to that functor. The flavours of this predicate
232
% are analogous to the ones of {\tt current\_functor/1} according to
233
% whether {\tt Term\_Indicator} has one of the following two forms:
235
% \item{\tt Module:Term.}
236
% \item{\tt Term} (for global modules).
238
% If {\tt Term\_Indicator} is uninstantiated, then this predicate succeeds
239
% only for global modules.
240
% As in {\tt current\_functor/1} even unloaded predicates are reported
241
% (if they have been imported and are are known to the database).
243
% For example, if a predicate {\tt foo/2} and and a function symbol
244
% {\tt foo/1} are defined into module {\tt blah}, the following query
248
% \> \> | ?- current\_functor(foo, blah:Term). \\
250
% \> \> Term = foo(\_638788,\_638792); \\
252
% \> \> Term = foo(\_638788); \\
257
% If a module is specified, {\tt current\_functor/2} succeeds only for
258
% those functors (function and predicate symbols) which are defined in
259
% that module. Unless the module is one of the global modules,
260
% {\tt current\_functor/2} fails for the predicates which are imported
263
% On the other hand, the goal:
266
% \> \> | ?- current\_functor(Name, Term).
269
% can be used to backtrack through every known term {\tt Term} in the global
270
% modules of \ourprolog's database that has {\tt Name} as its functor.
272
% Note that the order of term generation is undetermined. Once again,
273
% there are no error conditions associated with this predicate; if its
274
% arguments are inappropriate, the predicate simply fails.
276
%--------------------------------------------------------------------------------------------------
278
\ouritem{current\_module(?Module)}\index{\texttt{current\_module/1}}
279
The standard predicate {\tt current\_module/1} allows the user to
280
check whether a given module is {\em current} or to generate
281
(through backtracking) all currently known modules. Succeeds iff
282
{\tt Module} is one of the modules in the database. This includes
283
both user modules and system modules. For more detailed analysis
284
of module properties, the predicate {\tt module\_property/2}
287
Note that predicate {\tt current\_module/1} succeeds for a given
288
module even if that module does not export any predicates. There
289
are no error conditions associated with this predicate; if its
290
argument does not unify with one of the current modules, {\tt
291
current\_module/1} simply fails.
293
\ouritem{current\_module(?Module, ?ObjectFile)}\index{\texttt{current\_module/2}}
294
Predicate {\tt current\_module/2} gives the relationship between
295
the modules and their associated object file names. The file name
296
{\tt ObjectFile} must be absolute and end with the object file
297
extension for the system (by default, {\tt .xwam}).
299
It is possible for a current module to have no associated file
300
name (as is the case for {\tt "usermod"}), or for the system to be
301
unable to determine the file name of a current module. In both
302
cases, predicate {\tt current\_module/1} will succeed for this
303
module, while {\tt current\_module/2} will fail. The system is
304
unable to determine the file name of a given module if that module
305
is not in one of the directories of the search path (see
306
Section~\ref{LibPath}). Once again, there are no error conditions
307
associated with this predicate; if the arguments of {\tt
308
current\_module/2} are not correct, or {\tt Module} has no
309
associated {\tt File}, the predicate will simply fail.
311
\ouritem{current\_functor(?Predicate\_Indicator)}
312
\index{\texttt{current\_functor/1}}
313
{\tt current\_predicate/1} can be used to backtrack through indicators
314
for all non-atomic terms occurring in loaded modules. If {\tt
315
Predicate\_Indicator} unifies with {\tt Module:F/A} all term
316
indicators unifying with {\tt F/A} in a module unifying with {\tt
317
Module} are returned. If {\tt Predicate\_indicator} is {\tt F/A},
318
{\tt current\_predicate/1} behaves as if it were called with the form
319
{\tt usermod:F/A}. Unlike {\tt current\_predicate/1} {\tt
320
current\_functor/1} returns not only structures occurring in
321
predicates but predicates that are imported into loaded modules but
322
are not yet themselves loaded.
324
As an example, to backtrack through all of the functors of positive
325
arity (function and predicate symbols) that appear in the global
326
modules of the system regardless of whether they are system or a user
330
\> \> | ?- current\_functor(Functor/Arity), Arity > 0.
333
There are no error conditions associated with this predicate; if its
334
argument is not a predicate indicator the predicate simply fails.
336
\ouritem{current\_index(Functor/Arity,IndexSpec)}
337
\index{\texttt{current\_index/2}}
339
XSB has a variety of ways to index dynamic predicate including
340
alternate argument indexing, multiple argument indexing,
341
star-indexing, and tries, as discussed in Section~\ref{sec:assert}.
342
In addition XSB allows a choice of which argument to index for
343
compiled predicates as well. {\tt current\_index/2} returns the index
344
specification for each functor/arity pair unifying with {\tt
345
Functor/Arity} and visible from the calling context of {\tt current\_index/2}.
347
\ouritem{current\_atom(?Atom\_Indicator)}\index{\texttt{current\_atom/1}}
348
Generates (through backtracking) all currently known atoms, and unifies
349
each in turn with {\tt Atom\_Indicator}.
351
%??? need to define visible.
353
\ouritem{predicate\_property(?Term\_Indicator, ?Property)}
354
\index{\texttt{predicate\_property/2}}
355
The standard predicate {\tt predicate\_property/2} can be used to find
356
the properties of any predicate that is visible to a particular module.
357
Succeeds iff {\tt Term\_Indicator} is a term indicator for a current
358
predicate whose principal functor is a predicate having {\tt Property}
359
as one of its properties. Or procedurally, {\tt Property} is unified
360
with the currently known properties of the predicate having
361
{\tt Term\_Indicator} as its skeletal specification.
363
A brief description of {\tt predicate\_property/2} is as follows:
365
\item If {\tt Term\_Indicator} is not a variable, and is a structure
366
or atom, then {\tt Property} is successively unified with the
367
various properties associated with {\tt Term\_Indicator}. If
368
{\tt Term\_Indicator} is not a known to the system, the call
369
succeeds with {\tt Property} successively unified to {\tt
370
exported} and {\tt unclassified}. These properties can be
371
considered as a default for any structure or atom.
372
\item If {\tt Property} is bound to a valid predicate property, then {\tt
373
predicate\_property/2} successively unifies {\tt
374
Term\_Indicator} with the skeletal specifications of all
375
predicates known to the system having the specified {\tt
377
\item If {\tt Term\_Indicator} is a variable, then
378
it is unified (successively through backtracking) with the
379
most general term for a predicate whose known properties are
380
unified with {\tt Property}.
381
\item If {\tt Term\_Indicator}
382
is not a term indicator, or if {\tt Property} is not a valid
383
predicate property, the call fails.
386
For example, all the loaded predicate skeletal specifications in
387
module {\tt "usermod"} may be enumerated using:
390
\> \> | ?- predicate\_property(Pred, loaded).
393
Also the following query finds all predicate skeletal specifications that
394
are exported by module {\tt blah}:
397
\> \> | ?- predicate\_property(blah:Pred, exported).
400
Currently, the following properties are associated with predicates
401
either implicitly or by declaration. Double lines show property
402
categories, and a predicate can have at most one property of each
406
\begin{tabular}{||l|l||} \hline
407
{\em Property} & {\em Explanation} \\ \hline \hline
409
The predicate symbol is not yet classified according \\
410
& to this category. This property has various meanings. \\
411
& Usually for exported predicate symbols in system or \\
412
& user defined modules it means that the predicate is \\
413
& yet unloaded (because it has not been used). \\
414
& In {\tt usermod} it usually means that the predicate \\
415
& is either a function symbol, or an unloaded predicate \\
416
& symbol (including constants). \\ \hline
418
The predicate is dynamic. \\ \hline
420
The predicate (including internal predicates) is a \\
421
& Prolog predicate loaded into the module in question; \\
422
& this is always the case for predicates in {\tt usermod}.\\
425
The predicate is yet unloaded into the module \\
426
& in question.\\ \hline
428
The predicate is a foreign predicate. This implies that \\
429
& the predicate is already loaded in the system, because \\
430
& currently there is no way for XSB to know that a \\
431
& predicate is a foreign predicate until it is loaded in \\
432
& the system.\\ \hline
434
% The predicate symbol is declared as a function. \\ \hline
437
The predicate symbol is exported by the module in \\
438
& question; in other words the predicate symbol is \\
439
& visible to any other module in the system. \\ \hline
441
The predicate symbol is local to the module \\
442
& in question. \\ \hline
443
{\tt imported\_from(Mod)} &
444
The predicate symbol is imported into the module in \\
445
& question from module {\tt Mod}. \\ \hline
448
The predicate symbol has been declared spied \\
449
& (either conditionally or unconditionally). \\ \hline
452
The predicate has been declared tabled. \\ \hline
455
The predicate has been declared shared in the \\
456
& multi-threaded engine. This means that any dynamic \\
457
& code or tables for this predicate will be shared among \\
458
& threads, but it does not affect static, non-tabled code. \\ \hline
460
{\tt xsb\_standard\_pred} &
461
The predicate symbol has the same Functor and Arity as \\
462
& one of XSB's standard predicates, and is available to \\
463
& the user without needing to load a file or import the \\
464
& predicate from a module. \\ \hline
468
Finally, since {\tt dynamic} is usually declared as an operator with
469
precedence greater than 999, writing the following:
472
\> \> | ?- predicate\_property(X, dynamic).
475
will cause a syntax error. The way to achieve the desired result is to
476
parenthesize the operator like in:
479
\> \> | ?- predicate\_property(X, (dynamic)).
483
\ouritem{module\_property(?Module, ?Property)}\index{\texttt{module\_property/2}}
484
The standard predicate {\tt module\_property/2} can be used to find the
485
properties of any current module.
486
Succeeds iff {\tt Module} is the name of a current module having
487
{\tt Property} as one of its properties. Or procedurally, {\tt Property}
488
is unified with the currently known properties of the module having
489
{\tt Module} as its name.
491
Currently, the following properties are associated with modules
495
\begin{tabular}{||l|l||} \hline
496
{\em Property} & {\em Explanation} \\ \hline \hline
498
The module (including system modules) though it is \\
499
& current, is yet unloaded in the system. \\ \hline
501
The module (including system modules) is loaded in the \\
502
& system; this is always the case for {\tt usermod}.\\ \hline
506
\ouritem{listing}\index{\texttt{listing/0}}
507
Lists in the current output stream the clauses for all dynamic
508
predicates found in module {\tt usermod}. Note that {\tt listing/0}
509
does not list any compiled predicates unless they have the
510
{\tt dynamic} property (see {\tt predicate\_property/2}). A
511
predicate gets the {\tt dynamic} property when it is explicitly
512
declared as {\tt dynamic}, or automatically acquires it when some
513
clauses for that predicate are asserted in the database. In
514
cases where a predicate was compiled but converted to {\tt dynamic}
515
by asserting additional clauses for that predicate, {\tt listing/0}
516
will just display an indication that there exist compiled clauses
517
for that predicate and only the dynamically created clauses of the
518
predicate will be listed. For example:
521
\> \> | ?- [user]. \\
522
\> \> [Compiling user] \\
523
\> \> a(X) :- b(X). \\
525
\> \> [user compiled, cpu time used: 0.3 seconds] \\
526
\> \> [user loaded] \\
529
\> \> | ?- assert(a(3)). \\
532
\> \> | ?- listing. \\
535
\> \> \> \$compiled. \\
541
Predicate {\tt listing/0} always succeeds. The query:
548
is just a notational shorthand for the query:
551
\> \> | ?- listing(X).
554
\ouritem{listing(+Predicate\_Indicator)}\index{\texttt{listing/1}}
555
If {\tt Predicate\_Indicator} is a variable then {\tt listing/1} is
556
equivalent to {\tt listing/0}.
557
If {\tt Predicate\_Indicator} is an atom, then {\tt listing/1}
558
lists the dynamic clauses for all predicates of that name found in
559
module {\tt usermod} of the database.
560
The argument {\tt Predicate\_Indicator} can also be a predicate
561
indicator of the form {\tt Name/Arity} in which case only the
562
clauses for the specified predicate are listed.
563
Finally, it is possible for {\tt Predicate\_Indicator}
564
to be a list of predicate indicators and/or atoms; e.g.
567
\> \> | ?- listing([foo/2, bar, blah/4]).
570
If {\tt Predicate\_Indicator} is not a variable, an atom or a predicate
571
indicator (or list of predicate indicators) of the form {\tt Name/Arity},
572
predicate {\tt listing/1} will simply fail.
574
In future releases of \ourprolog, we intend to allow the user to
575
specify a predicate indicator of the form {\tt Module:Name/Arity}
576
as argument of {\tt listing/1}.
578
\ouritem{xsb\_configuration(Feature\_Name, ?Value)}
579
\index{\texttt{xsb\_configuration/2}}
580
Succeeds iff the current value of the XSB feature {\tt
581
Feature\_Name} is {\tt Value}.
583
This predicate provides information on a wide variety of features
584
related to how XSB was built, including the compiler used, the compiler
585
and loader flags, the machine and OS on which XSB was built, the
586
release number, the various directories that XSB uses to find its
589
To find all features and their values, ask the following query:
592
\> \> | ?- xsb\_configuration(FeatureName, Value), fail.
595
Here is how {\tt xsb\_configuration} might look like:
598
xsb_configuration(architecture, 'i686-pc-linux-gnu').
599
%% configuration is usualy the same as architecture, but it can also
600
%% contain special tags, {\it e.g.}, i686-pc-linux-gnu-dbg, for a verion
601
%% built with debugging enabled.
602
xsb_configuration(configuration, 'i686-pc-linux-gnu-dbg').
603
xsb_configuration(host_os, 'linux-gnu').
604
xsb_configuration(os_version, '2.34').
605
xsb_configuration(os_type, 'linux-gnu').
606
xsb_configuration(host_vendor, 'pc').
607
xsb_configuration(host_cpu, 'i686').
608
xsb_configuration(compiler, 'gcc').
609
xsb_configuration(compiler_flags, ' -ansi -pedantic -Wall -g').
610
xsb_configuration(loader_flags, ' -lm -ldl -Wl,-export-dynamic').
611
xsb_configuration(compile_mode, 'debug').
612
%% The following is XSB release information
613
xsb_configuration(major_version, '1').
614
xsb_configuration(minor_version, '9').
615
xsb_configuration(beta_version, '3').
616
xsb_configuration(version, '1.9-b3').
617
xsb_configuration(codename, 'Code Breaker').
618
xsb_configuration(release_date, date(1998, 10, 17)).
619
%% XSB query evaluation directive
620
xsb_configuration(scheduling_strategy, '(batched)').
621
%% Support for other languages
622
xsb_configuration(perl_support, 'yes').
623
xsb_configuration(perl_archlib, '/usr/lib/perl5/i386-linux/5.00404').
624
xsb_configuration(perl_cc_compiler, 'cc').
625
xsb_configuration(perl_ccflags, '-Dbool=char -DHAS_BOOL -I/usr/local/include').
626
xsb_configuration(perl_libs, '-lnsl -lndbm -lgdbm -ldb -ldl -lm -lc -lposix -lcrypt').
627
xsb_configuration(javac, '/usr/bin/javac').
628
/* Tells where XSB is currently residing; can be moved */
629
xsb_configuration(install_dir, InstallDir) :- ...
630
/* User home directory. Usually HOME. If that is null, then it would
631
be the directory where XSB is currently residing.
632
This is where we expect to find the .xsb directory */
633
xsb_configuration(user_home, Home) :- ...
634
/* Where XSB invocation script is residing */
635
xsb_configuration(scriptdir, ScriptDir) :- ...
636
/* where are cmplib, syslib, lib, packages, etc live */
637
xsb_configuration(cmplibdir, CmplibDir) :- ...
638
xsb_configuration(libdir, LibDir) :- ...
639
xsb_configuration(syslibdir, SyslibDir) :- ...
640
xsb_configuration(packagesdir, PackDir) :- ...
641
xsb_configuration(etcdir, EtcDir) :- ...
642
/* architecture and configuration specific directories */
643
xsb_configuration(config_dir, ConfigDir) :- ...
644
xsb_configuration(config_libdir, ConfigLibdir) :- ...
645
/* site-specific directories */
646
xsb_configuration(site_dir, '/usr/local/XSB/site').
647
xsb_configuration(site_libdir, SiteLibdir) :- ...
648
/* site and configuration-specific directories */
649
xsb_configuration(site_config_dir, SiteConfigDir) :- ...
650
xsb_configuration(site_config_libdir, SiteConfigLibdir) :- ...
651
/* Where user's arch-specific libraries are found by default. */
652
xsb_configuration(user_config_libdir, UserConfigLibdir) :- ...
655
\ouritem{xsb\_flag(?Flag\_Name, ?Value)}\index{\texttt{xsb\_flag/2}}
656
Succeeds iff the current value of the XSB flag {\tt Flag\_Name} is
657
{\tt Value}. So, one can enumerate all the flag names which the system
658
currently understands, together with their current values by using the
662
\> \> | ?- xsb\_flag(FlagName, Value), fail.
665
The flag names currently supported are:
668
\begin{tabular}{||l|p{11cm}||} \hline
669
{\em Flag Name} & {\em Purpose} \\ \hline \hline
671
{\tt backtrace\_on\_error} & {\tt on} iff system-handled errors
672
automatically print out the trace of the execution stack where the
673
error arose, {\tt off} otherwise. Default is {\tt on}. In the
674
multi-threaded engine, this flag is thread-specific and controls
675
whether the backtrace for a current execution will be printed to {\tt
678
{\tt dcg\_style} & the DCG style currently used; {\tt xsb} or {\tt
679
standard} (standard is used in Quintus, SICSTUS, etc.). See
680
Section~\ref{sec-dcg-differences} for more details. Default is {\tt
681
xsb}. This flag affects all threads in the process. \\ \hline
683
{\tt debugging} & {\tt on} iff debug mode is on; {\tt off} otherwise.
684
This flag affects all threads in the process. \\ \hline
686
{\tt heap\_garbage\_collection} & {\tt indirection}, {\tt none}, {\tt
687
sliding}, or {\tt copying} depending on the heap garbage collection
688
strategy that is currently being employed (see also
689
Section~\ref{sec:EmuOptions}). Default is {\tt indirection}. This
690
flag is private to each thread. \\ \hline
692
{\tt clause\_garbage\_collection} & {\tt on} if garbage collection for
693
retracted clauses is allowed, and off otherwise. Default is {\tt
694
on}. This flag is private to each thread. \\ \hline
696
{\tt goal} & the goal passed to XSB on command line with the
697
`-e' switch; `{\tt true.}' if nothing is passed. \\ \hline
699
{\tt tracing} & {\tt on} iff trace mode is on; {\tt off}
700
otherwise. This flag affects all threads in the process. \\ \hline
702
{\tt write\_depth} & The depth to which a term is written by {\tt
703
write}-like predicates. Default is 64. This flag affects all
704
threads in the process. \\ \hline
708
Note that {\tt xsb\_flag} is used only for dynamic XSB settings, {\it
709
i.e.}, settings that might change between sessions or within the same
710
session. For static configuration information, the predicate {\tt
711
xsb\_configuration/2} is used. \index{\texttt{xsb\_configuration/2}}
713
\ouritem{set\_xsb\_flag(+Flag\_Name, +Value)}
714
\index{\texttt{set\_xsb\_flag/2}}
716
Changes one of the dynamic XSB settings described for {\tt
721
\item {\tt Flag\_Name} or {\tt Value} is a variable.
723
\item {\tt instantiation\_error}
726
\item {\tt Flag\_Name} is not the name of a recognized XSB flag.
728
\item {\tt domain\_error(xsb\_flag,Flag\_Name)}
734
\ouritem{hilog\_symbol(?Symbol)}\index{\texttt{hilog\_symbol/1}}
735
Succeeds iff {\tt Symbol} has been declared as a HiLog symbol, or
736
procedurally unifies {\tt Symbol} with one of the currently known
737
(because of a prior declaration) HiLog symbols. The HiLog symbols
738
are always atoms, but if the argument of {\tt hilog\_symbol},
739
though instantiated, is not an atom the predicate simply fails.
740
So, one can enumerate all the HiLog symbols by using the following
744
\> \> | ?- hilog\_symbol(X).
747
\ournewitem{current\_op(?Precedence, ?Specifier, ?Name)}{ISO}
748
\index{\texttt{current\_op/3}}
749
This predicate is used to examine the set of operators currently
750
in force. It succeeds when the atom {\tt Name} is currently an
751
operator of type {\tt Specifier} and precedence {\tt Precedence}. None
752
of the arguments of {\tt current\_op/3} need to be instantiated at
753
the time of the call, but if they are, they must be of the
756
\item[{\tt Precedence}] must be an integer in the range from 1 to 1200.
757
\item[{\tt Specifier}] must be one of the atoms:
759
xfx xfy yfx fx fy hx hy xf yf
761
\item[{\tt Name}] it must be an atom.
766
\item {\tt Precedence} is neither a variable nor an integer in the
767
range from 1 to 1200.
769
\item {\tt domain\_error(operator\_priority,Precedence)}
771
\item {\tt Specifier} is neither a variable nor an operator
772
specifier of the types above.
774
\item {\tt domain\_error(operator\_specifier,Specifier)}
776
\item {\tt Name} is neither a variable nor an atom.
778
\item {\tt domain\_error(atom\_or\_variable,Name)}
784
\ouritem{hilog\_op(?Precedence, ?Type, ?Name)}\index{\texttt{hilog\_op/3}}
785
This predicate has exactly the same behaviour as {\tt current\_op/3}
786
with the only difference that {\tt Type} can only have the values
787
{\tt hx} and {\tt hy}.
793
%%% TeX-master: "manual1"
796
%======================================================
798
\section{Execution State}\label{environmental}
802
\ouritem{break}\index{\texttt{break/0}}
803
Causes the current execution to be suspended at the beginning of the next
804
call. The interpreter then enters break level 1 and is ready to accept
805
input as if it were at top level. If another call to {\tt break/0} is
806
encountered, it moves up to break level 2, and so on. While execution
807
is done at break level $n>0$ the prompt changes to {\tt $n$: ?-}.
809
To close a break level and resume the suspended execution, the user can
810
type the the atom {\tt end\_of\_file} or the end-of-file character
811
applicable on the system (usually {\tt CTRL-d} on UNIX systems).
812
Predicate {\tt break/0}
813
then succeeds (note in the following example that the calls to {\tt break/0}
814
do not succeed), and the execution of the interrupted program is resumed.
815
Alternatively, the suspended execution can be abandoned by calling the
816
standard predicate {\tt abort/0}, which causes a return to the top level.
818
An example of {\tt break/0} 's use is the following:
822
\> \> [ Break (level 1) ] \\
823
\> \> 1: ?- break. \\
824
\> \> [ Break (level 2) ] \\
825
\> \> 2: ?- end\_of\_file. \\
826
\> \> [ End break (level 2) ] \\
832
Entering a break closes all incomplete tables (those which may not have a
833
complete set of answers). Closed tables are unaffected, even if
834
the tables were created during the computation for which the break was
837
\ournewitem{halt}{ISO}\index{\texttt{halt/0}}
838
Exits the XSB session regardless of the break level. On exiting
839
the system cpu and elapsed time information is displayed.
841
\ournewitem{halt(Code)}{ISO}\index{\texttt{halt/1}}
843
Exits the XSB session regardless of the break level, sending the
844
integer {\tt Code} to the parent process. Normally {\tt 0} is
845
considered to indicate normal termination, while other exit codes are
846
used to report various degrees of abnormality.
850
\item {\tt Code} is not an integer
852
\item {\tt type\_error(Integer,Code)}
856
\ouritem{prompt(+NewPrompt, ?OldPrompt)}\index{\texttt{prompt/2}}
857
Sets the prompt of the top level interpreter to {\tt NewPrompt} and
858
returns the old prompt in {\tt OldPrompt}.
860
An example of {\tt prompt/2} 's use is the following:
863
\> \> | ?- prompt('Yes master > ', P). \\
868
\> \> Yes master > fail. \\
874
\ouritem{garbage\_collection(+Option)}\index{texttt{garbage\_collection/1}}
875
Sets the system so that subsequent heap garbage collecting will be
876
done according to the specified {\tt Option}. {\tt Option} may be
877
the atom \verb|none| indicating that heap garbage collection is
878
turned off; it may be the atom \verb|sliding| indicating that
879
sliding garbage collection will be done; the atom \verb|copying|
880
indicating that the copying garbage collector will be used; or it
882
\verb|indirection| indicating that the indirect-sliding garbage
883
collector will be used.
885
\ouritem{cputime(-CPU\_Time)}\index{\texttt{cputime/1}}
887
Returns the (process-level) {\tt CPU\_Time} at the time of the call in
888
seconds. The difference between results of successive calls to this
889
predicate can measure the time spent in specific predicates. Note
890
that in the multi-threaded engine, {cputime/1} measures the time for
893
\ouritem{walltime(-Time)}\index{\texttt{cputime/1}}
895
Returns the \texttt{Time}, in seconds, since execution started, or
896
since the last call to \texttt{statistics(0)} by any thread.
898
\ouritem{statistics}\index{\texttt{statistics/0}}
900
Displays usage information on the current output stream, including:
902
\item Process-level information about allocated memory excluding
903
execution stacks but including:
905
\item {\tt atom} Space used to maintain global information about
906
predicates and structures.
908
\item {\tt string} Space used to maintain information about atomic
911
\item {\tt asserted} Space allocated for dynamic code.
913
\item {\tt asserted} Space allocated for static code.
915
\item {\tt foreign} Space allocated for foreign predicates.
917
\item {\tt table} Space allocated for XSB's tables.
919
\item {\tt findall} Space allocated for buffers to support {\tt
920
findall/3} and similar predicates.
922
\item {\tt mt-private} Private space used by threads.
924
\item {\tt profiling} Space used to maintain profiling information, if
925
XSB is called with profiling on.
927
\item {\tt gc temp} Temporary space for used for heap garbage
930
\item {\tt interprolog} space allocated for the Interprolog XSB/Java
933
\item {\tt thread} space allocated for the thread table
935
\item the space occupied by subgoal and answer tables (in the form of
936
tries) \cite{RRSSW98}. In the multi-threaded configuration this
937
includes all private and shared tables.
940
\item Thread-specific information about allocation of memory
943
\item Global stack (heap) and local (environment) stack (see e.g.
944
\cite{AitK90}) for the calling thread. Memory for these two WAM
945
stacks is allocated as a single unit so that each stack grows
946
together; information is provided on the current allocation for the
947
stacks as well as on the stack sizes themselves. (See
948
Section~\ref{sec:EmuOptions} for the memory re-allocation
951
\item Trail and choice point stack (see e.g. \cite{AitK90}) for the
952
calling thread. Memory for these two WAM stacks is allocated as a
953
single unit so that each stack grows together; information is
954
provided on the current allocation for the stacks as well as on the
955
stack sizes themselves. The (re-)allocation follows the algorithm
956
sketched in Section~\ref{sec:EmuOptions}). (See
957
Section~\ref{sec:EmuOptions} for the memory re-allocation
960
\item SLG unification stack for the calling thread This stack is used
961
as a space to copy terms from the execution stacks into table space,
962
or back out. This stack will not be reallocated unless extremely
963
large terms are tabled.
965
\item SLG completion stack for the calling thread. The completion
966
stack is used to perform incremental completion for sets of mutually
967
dependant tabled subgoals. One completion stack frame is allocated
968
per tabled subgoal \cite{SaSw98} but the size of these frames is
972
In XSB's single-threaded configuration, maximum space used by each of
973
will be output if the {\tt '-s'} command-line option is used
975
\item Information about the number of tabling operations performed in
976
the session by any thread. Note that the statistics are divided up
977
between calls to predicates that use variant tabling and those that
978
use (call) subsumptive tabling (see
979
Section~\ref{sec:SimilarityMeasures} and \cite{TST99}).
981
\item Call Subsumption Subgoal Operations. For predicates that use
982
subsumptive tabling, the total number of subsumptive subgoal calls is
983
given, as is the number of new calls ({\tt producers}) and the number
984
of repeated calls to non-completed tables ({\tt variants}).
985
Furthermore, the number of properly subsumed calls to incomplete
986
tables is given, along with the number of subsumed calls to completed
987
tables. Finally, the total number of subsumptive table entries
988
overall is given, including all producer and consumer calls.
990
\item Call Subsumption Answer Operations. In call subsumptive
991
tabling, answer lists are copied from producer subgoals to subsumed
992
consumer subgoals (this opration is not required in variant tabling).
993
The number of {\tt answer ident} operations represents the number of
994
times this copy is done. In addition, the number of consumptions
995
performed by all consuming subsumptive table entries is also given.
997
\item Call Variance Subgoal Operations. For call variance the number
998
of subgoal check/insert operations is given along with the unique
999
number of subgoals encountered ({\tt generator}) and the number of
1000
redundant consumer encountered ({\tt consumer}).
1002
\item Total Answer Operations. For both variant and subsumptive
1003
tables, the number of answer check insert operations is given along
1004
with the number of answers actually inserted into the table and the
1005
number of redundant answers derived.
1008
\item Garbage Collection Information. Time spent garbage collecting
1009
by the calling thread and number of heap cells collected.
1011
\item Information about process CPU and clock time, as well as the
1012
number of active threads.
1015
As mentioned above, if XSB is configured with the single-threaded
1016
engine and is invoked with the {\tt '-s'} option (see
1017
Section~\ref{sec:EmuOptions}), additional information is printed out
1018
about maximum use of each execution stack and table space. However,
1019
the {\tt '-s'} option can substantially slow down the emulator so
1020
benchmarks of time should be performed separately from benchmarks of
1023
{\bf Example}: The following printout shows how the {\tt statistics/0}
1024
output looks if it is invoked with the {\tt '-s'} option (without it
1025
the {\tt Maximum stack used}, and {\tt Maximum table space used} lines
1026
are not shown). Information about the allocation size is provided
1027
since the sizes can be changed through emulator options (see
1028
Section~\ref{sec:EmuOptions}).
1034
Memory (total) 1941216 bytes: 238120 in use, 1703096 free
1035
permanent space 237280 bytes: 237280 in use, 0 free
1036
glob/loc space 786432 bytes: 524 in use, 785908 free
1039
trail/cp space 786432 bytes: 316 in use, 786116 free
1041
choice point 292 bytes
1042
SLG unific. space 65536 bytes: 0 in use, 65536 free
1043
SLG completion 65536 bytes: 0 in use, 65536 free
1044
SLG table space 0 bytes: 0 in use, 0 free
1046
Maximum stack used: global 224, local 1384, trail 240, cp 492,
1047
SLG completion 0 (0 subgoals)
1048
Maximum table space used: 0 bytes
1051
Call Subsumption Subgoal Operations:
1052
0 call check/insert ops: 0 producers, 0 variants,
1053
0 properly subsumed. 0 used completed table,
1054
0 table entries overall.
1055
Call Subsumption Answer Operations:
1056
0 relevant answer ident ops. 0 consumptions via answer list.
1057
Call Variance Subgoal Operations:
1058
0 call check/insert ops: 0 generators, 0 consumers.
1059
Total Answer Operations:
1060
0 answer check/insert ops: 0 unique inserts, 0 redundant.
1062
{GC} 0 heap garbage collections by copying: collected 0 cells in 0.000000 millisecs
1064
0.570 sec. cputime, 5.088 sec. elapsetime
1067
%===================
1069
\ouritem{statistics(+Type)}\index{\texttt{statistics/1}}
1071
{\tt statistics/1} allows the user to output detailed statistical
1072
information about the atom and symbol tables, as well as about table
1073
space. The following calls to {\tt statistics/1} are supported:
1076
\item {\tt statistics(reset)} Resets the CPU time as well as counts
1077
for various tabling operations.
1079
\item {\tt statistics(atom)} Outputs statistics about both the atom
1080
and symbol tables. An example is:
1085
Symbol table statistics:
1086
------------------------
1089
used buckets: 1088 (range: [0, 8174])
1090
unused buckets: 7103
1091
maximum bucket size: 3 (#: 18)
1093
String table statistics:
1094
------------------------
1097
used buckets: 1598 (range: [0, 16373])
1098
unused buckets: 14783
1099
maximum bucket size: 3 (#: 2318)
1102
\item {\tt statistics(table)} Outputs {\em very} detailed statistics
1103
about table space, including breakdowns into variant and subsumptive
1104
call- and answer- trie nodes and hash tables; as well as answer return
1105
list nodes (cf. \cite{SaSw98, RRSSW98, TST99}). This option is not
1106
available in the multi-threaded configuration.
1111
%need op (just so we dont forget ???
1114
%=====================================================================
added
removed
docs/userman/state.tex
