6.12 Execution State

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

ISO
Exits the XSB session regardless of the break level. On exiting the system cpu and elapsed time information is displayed.

halt(Code)

ISO
Exits the XSB session regardless of the break level, sending the integer Code to the parent process. Normally 0 is considered to indicate normal termination, while other exit codes are used to report various degrees of abnormality.

Error Cases

• Code is not an integer
  • type_error(Integer,Code)

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 >     

trimcore

machine
A call to trimcore/0 reallocates an XSB thread's execution stacks (and some tabling stacks) to their initial allocation size, the action affecting only the memory areas for the calling thread. When XSB is called in standalone or server mode, trimcore/0 is automatically called when the top interpreter level is reached. When XSB is embedded in a process, trimcore/0 is called at the top interpreter level for any thread created through xsb_ccall_thread_create() (see Volume 2, Chapter 3 Embedding XSB in a Process).

gc_heap

Explicitly invokes the garbage collector for a thread's heap. By default, heap garbage collection is called automatically for each thread upon stack expansion, unless the xsb_flag heap_garbage_collection is set to none. Automatic heap garbage collection should rarely need to be turned off, and should rarely need to be invoked manually.

cputime(-CPU_Time)

Returns the (process-level) 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. Note that in the multi-threaded engine, cputime/1 measures the time for all threads.

walltime(-Time)

Returns the Time, in seconds, since execution started, or since the last call to statistics(0) by any thread.

statistics

Displays usage information on the current output stream, including:

• Process-level information about allocated memory excluding execution stacks but including:
  • atom Space used to maintain global information about predicates and structures.
  • string Space used to maintain information about atomic constants in XSB.
  • asserted Space allocated for dynamic code.
  • asserted Space allocated for static code.
  • foreign Space allocated for foreign predicates.
  • table Space allocated for XSB's tables.
  • findall Space allocated for buffers to support findall/3 and similar predicates.
  • mt-private Private space used by threads.
  • profiling Space used to maintain profiling information, if XSB is called with profiling on.
  • gc temp Temporary space for used for heap garbage collector.
  • interprolog space allocated for the Interprolog XSB/Java interface.
  • thread space allocated for the thread table
  • the space occupied by subgoal and answer tables (in the form of tries) [46,18,32]. In the multi-threaded configuration process level table space includes shared tables but not private tables.

• Thread-specific information about allocation of memory for the calling thread including the
  • Global stack (heap) and local (environment) stack (see e.g. [1]) for the calling thread. 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.7 for the memory re-allocation algorithm).
  • Trail and choice point stack (see e.g. [1]) for the calling thread. 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.7). (See Section 3.7 for the memory re-allocation algorithm).
  • SLG unification stack for the calling thread 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 for the calling thread. The completion stack is used to perform incremental completion for sets of mutually dependent tabled subgoals. One completion stack frame is allocated per tabled subgoal [47] but the size of these frames is version-dependent.
  • the space occupied by private subgoal and answer tables for the calling thread.

  In XSB's single-threaded configuration, maximum space used by each of will be output if the '-s' command-line option is used

• Information about the number of tabling operations performed in the session by any thread. 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 [32]).
  • 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 operation 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 by the calling thread and number of heap cells collected.

• Information about process CPU and clock time, as well as the number of active threads.

As mentioned above, if XSB is configured with the single-threaded engine and is invoked with the '-s' option (see Section 3.7), 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.7).

| ?- statistics.
Memory (total)         2429504 bytes:       726696 in use,      1702808 free
  permanent space       645520 bytes:       645520 in use,            0 free
    atom                                    120328
    string                                  156872
    asserted                                  3184
    compiled                                358216
    other                                     6920
  glob/loc space        786432 bytes:          652 in use,       785780 free
    global                                     456 bytes
    local                                      196 bytes
  trail/cp space        786432 bytes:          476 in use,       785956 free
    trail                                       88 bytes
    choice point                               388 bytes
  SLG unific. space      65536 bytes:            0 in use,        65536 free
  SLG completion         65536 bytes:            0 in use,        65536 free
  SLG table space        80048 bytes:        80048 in use,            0 free

  Maximum stack used: global 436724, local 14780, trail 27304, cp 20292,
                      SLG completion 0 (0 subgoals)
  Maximum table space used:  0 bytes

Tabling Operations
  0 subsumptive call check/insert ops: 0 producers, 0 variants,
  0 properly subsumed (0 table entries), 0 used completed table.
  0 relevant answer ident ops.  0 consumptions via answer list.
  0 variant call check/insert ops: 0 producers, 0 variants.
  0 answer check/insert ops: 0 unique inserts, 0 redundant.


   0 heap (  0 string) garbage collections by copying: collected 0 cells in 0.000000 secs

Time: 0.190 sec. cputime,  13.921 sec. elapsetime

statistics(+Type)

statistics/1 allows the user to output detailed statistical information about the atom and symbol tables, as well as about table space. The following calls to statistics/1 are supported:

• statistics(reset) Resets the CPU time as well as counts for various tabling operations.
• statistics(atom) Outputs statistics about both the atom and symbol tables. An example is:

  | ?- statistics(atom).
  
  Symbol table statistics:
  ------------------------
  Table Size:	8191
  Total Symbols:	1188
              used buckets:              1088  (range: [0, 8174])
              unused buckets:            7103
              maximum bucket size:       3  (#: 18)
  
  String table statistics:
  ------------------------
  Table Size:	16381
  Total Strings:	1702
              used buckets:              1598  (range: [0, 16373])
              unused buckets:            14783
              maximum bucket size:       3  (#: 2318)
  

• statistics(table) Outputs very detailed statistics about table space, including breakdowns into variant and subsumptive call- and answer- trie nodes and hash tables; answer return list nodes, and structures for conditional answers (cf. [47,46,32,17]). In the multi-threaded engine, these data structures are reported both for shared tables and for private tables of the calling thread.

  While this option is intended primarily for developers, it can also provide valuable information for the serious user of tabling.