- break
-
Causes the current execution to be suspended at the beginning of the next
call. The interpreter then enters break level 1 and is ready to accept
input as if it were at top level. If another call to break/0 is
encountered, it moves up to break level 2, and so on. While execution
is done at break level n > 0 the prompt changes to n: ?-.
To close a break level and resume the suspended execution, the user can
type the the atom end_of_file or the end-of-file character
applicable on the system (usually CTRL-d on UNIX systems).
Predicate break/0
then succeeds (note in the following example that the calls to break/0
do not succeed), and the execution of the interrupted program is resumed.
Alternatively, the suspended execution can be abandoned by calling the
standard predicate abort/0, which causes a return to the top level.
An example of break/0 's use is the following:
| ?- break.
1: ?- break.
2: ?- end_of_file.
yes
1: ?-
|
Entering a break closes all incomplete tables (those which may not have a
complete set of answers). Closed tables are unaffected, even if
the tables were created during the computation for which the break was
entered.
- halt
-
Exits the XSB session regardless of the break level. On exiting
the system cpu and elapsed time information is displayed.
- prompt(+NewPrompt, ?OldPrompt)
-
Sets the prompt of the top level interpreter to NewPrompt and
returns the old prompt in OldPrompt.
An example of prompt/2 's use is the following:
| ?- prompt('Yes master > ', P).
P = | ?- ;
no
Yes master > fail.
no
Yes master >
|
- garbage_collection(+Option)
-
Sets the system so that subsequent heap
garbage collecting will be done according to the specified Option. Option may be the atom none indicating that
heap garbage collection is turned off; it may be the atom
sliding indicating that sliding garbage collection will be
done; the atom copying indicating that the copying garbage
collector will be used; or it may be the atom indirection
indicating that the indirect-sliding garbage collector will be
used.
- cputime(-CPU_Time)
-
Returns the CPU_Time at the time of the call in seconds.
The difference between results of successive calls to this
predicate can measure the time spent in specific predicates.
- walltime(-Time)
-
Returns the Time, in seconds, since execution started, or
since the last call to statistics(0).
- statistics
-
Prints on the current
output stream:
- Information about allocation of memory containing the
- Global stack (heap) and local (environment) stack (see e.g.
[1]). Memory for these two WAM stacks is allocated as a
single unit so that each stack grows together; information is provided
on the current allocation for the stacks as well as on the stack sizes
themselves. (See Section 3.5 for the memory
re-allocation algorithm). For maximum space used by each of these
stacks, use the '-s' command-line option.
- Trail and choice point stack (see e.g. [1]). Memory
for these two WAM stacks is allocated as a single unit so that each
stack grows together; information is provided on the current
allocation for the stacks as well as on the stack sizes themselves.
The (re-)allocation follows the algorithm sketched in
Section 3.5). (See Section 3.5 for
the memory re-allocation algorithm). For maximum space used by each
of these stacks, use the '-s' command-line option.
- SLG unification stack. This stack is used as a space to copy
terms from the execution stacks into table space, or back out. This
stack will not be reallocated unless extremely large terms are tabled.
- SLG completion stack. The completion stack is used to perform
incremental completion for sets of mutually dependant tabled
subgoals. One completion stack frame is allocated per tabled subgoal
[40] but the size of these frames is version-dependent.
- the space occupied by subgoal and answer tables (in the form of
tries) [39].
- Information about the number of tabling operations performed in
the session. Note that the statistics are divided up between calls to
predicates that use variant tabling and those that use (call)
subsumptive tabling (see Section 5.2.1 and
[26]).
- Call Subsumption Subgoal Operations. For predicates that use
subsumptive tabling, the total number of subsumptive subgoal calls is
given, as is the number of new calls (producers) and the number
of repeated calls to non-completed tables (variants).
Furthermore, the number of properly subsumed calls to incomplete
tables is given, along with the number of subsumed calls to completed
tables. Finally, the total number of subsumptive table entries
overall is given, including all producer and consumer calls.
- Call Subsumption Answer Operations. In call subsumptive
tabling, answer lists are copied from producer subgoals to subsumed
consumer subgoals (this opration is not required in variant tabling).
The number of answer ident operations represents the number of
times this copy is done. In addition, the number of consumptions
performed by all consuming subsumptive table entries is also given.
- Call Variance Subgoal Operations. For call variance the number
of subgoal check/insert operations is given along with the unique
number of subgoals encountered (generator) and the number of
redundant consumer encountered (consumer).
- Total Answer Operations. For both variant and subsumptive
tables, the number of answer check insert operations is given along
with the number of answers actually inserted into the table and the
number of redundant answers derived.
- Garbage Collection Information. Time spent garbage collecting
and number of heap cells collected.
- Information about process CPU and clock time.
As mentioned above, if the emulator is invoked with the '-s'
option (see Section 3.5), additional information
is printed out about maximum use of each execution stack and table
space. However, the '-s' option can substantially slow down
the emulator so benchmarks of time should be performed separately
from benchmarks of space.
Example: The following printout shows how the statistics/0
output looks if it is invoked with the '-s' option (without it
the Maximum stack used, and Maximum table space used lines
are not shown). Information about the allocation size is provided
since the sizes can be changed through emulator options (see
Section 3.5).
| ?- statistics.
Memory (total) 1941216 bytes: 238120 in use, 1703096 free
permanent space 237280 bytes: 237280 in use, 0 free
glob/loc space 786432 bytes: 524 in use, 785908 free
global 284 bytes
local 240 bytes
trail/cp space 786432 bytes: 316 in use, 786116 free
trail 24 bytes
choice point 292 bytes
SLG unific. space 65536 bytes: 0 in use, 65536 free
SLG completion 65536 bytes: 0 in use, 65536 free
SLG table space 0 bytes: 0 in use, 0 free
Maximum stack used: global 224, local 1384, trail 240, cp 492,
SLG completion 0 (0 subgoals)
Maximum table space used: 0 bytes
Tabling Operations
Call Subsumption Subgoal Operations:
0 call check/insert ops: 0 producers, 0 variants,
0 properly subsumed. 0 used completed table,
0 table entries overall.
Call Subsumption Answer Operations:
0 relevant answer ident ops. 0 consumptions via answer list.
Call Variance Subgoal Operations:
0 call check/insert ops: 0 generators, 0 consumers.
Total Answer Operations:
0 answer check/insert ops: 0 unique inserts, 0 redundant.
{GC} 0 heap garbage collections by copying: collected 0 cells in 0.000000 millisecs
0.570 sec. cputime, 5.088 sec. elapsetime
For expert users of XSB, further information about resources
required by the system can be obtained through the non-supported
predicate statistics/1 in $XSB_DIR/emu/trace.c.
- shell(+SystemCall)
-
Calls the operating system with the atom SystemCall as argument.
It succeeds if SystemCall is executed successfully, otherwise it
fails. As a notational convenience, the user can supply SystemCall
in the form of a list (something currently not possible for shell/2).
For example, the call:
| ?- shell('echo $HOME').
will output in the current output stream of XSB the name of
the user's home directory; while the call:
| ?- File = 'test.c', shell(['cc -c ', File]).
will call the C compiler to compile the file test.c.
Note that in UNIX systems, since shell/1 is executed by
forking off a shell process, it cannot be used, for example, to
change the working directory of the interpreter. For that reason
the standard predicate cd/1 described below should be used.
- shell(+SystemCall, -Result)
-
Calls the operating system with the atom SystemCall as argument
and returns the result of the call in Result. In comparison with
shell/1 this predicate always succeeds, even if the SystemCall
cannot be successfully executed.
- ls
-
Under UNIX, this command lists in the current output stream the files
in the system's current directory if it can do so. If so, it succeeds.
It is the same as shell('ls -F', 0).
- cd(+Dir)
-
Under UNIX and Windows, this predicate changes the interpreter's
working directory to Dir. If the directory specified does
not exist or is not a directory, or the user does not have execute
permission for that directory, predicate cd/1 simply fails
raising no permission error.
Exceptions:
- instantiation_error
- Dir is not instantiated at the time of call.
- type_error
- Dir is not an atom.
- edit(+Module)
-
Provided that the environment variable EDITOR has been set,
and the system is executing under UNIX,
a call to edit(foo) will call the default editor on the file
named foo.P. The argument to edit/1, should be instantiated,
it can be an absolute or a relative file name, but it should not
contain the suffix .P. Users can also set their preferred options
of calling the default editor by setting an environment variable named
EDITOR_OPTIONS.
Examples of possible uses of predicate edit/1 are:
- If the environment variables have been set as follows:
setenv EDITOR /usr/ucb/vi
setenv EDITOR_OPTIONS -l
a call like:
| ?- edit(foo).
will call the vi editor in the mode where left and right parentheses
and curly brackets are checked for balance for the file foo.P
in the current working directory.
- If, on the other hand, they have been set as follows:
setenv EDITOR /usr/local/bin/emacs
setenv EDITOR_OPTIONS -r
a call like:
| ?- edit('~/foo').
will call the emacs editor in reverse video for the file foo.P
in user's home directory.
