4.10.1.2 Displaying Statistics

Statistics relating to memory usage, run time, and garbage collection, including information about which areas of memory have overflowed and how much time has been spent expanding them, can be displayed by calling statistics/0.

The output from statistics/0 looks like this:

     memory (total)       3334072 bytes
        global stack      1507184 bytes:       2516 in use,   1504668 free
        local stack         49296 bytes:        276 in use,     49020 free
        trail stack         34758 bytes:        248 in use,     34510 free
        control stack       34874 bytes:        364 in use,     34510 free
        program space     1707960 bytes:    1263872 in use,    444088 free
        program space breakdown:
                 compiled code               575096 bytes
                 atom                        166528 bytes
                 predicate                   157248 bytes
                 try_node                    144288 bytes
                 sw_on_key                   105216 bytes
                 incore_info                  51096 bytes
                 atom table                   36864 bytes
                 interpreted code             13336 bytes
                 atom buffer                   2560 bytes
                 SP_malloc                     2288 bytes
                 FLI stack                     2048 bytes
                 miscellaneous                 1640 bytes
                 BDD hash table                1560 bytes
                 source info (B-tree)          1024 bytes
                 numstack                      1024 bytes
                 int_info                       880 bytes
                 file table                     400 bytes
                 source info (itable)           328 bytes
                 module                         320 bytes
                 source info (lheap)             80 bytes
                 foreign resource                32 bytes
                 all solutions                   16 bytes
         4323 atoms (151927 bytes) in use, 1044252 free
         No memory resource errors
     
            0.020 sec. for 7 global, 20 local, and 0 choice stack overflows
            0.060 sec. for 15 garbage collections which collected 5461007 bytes
            0.000 sec. for 0 atom garbage collections which collected 0 atoms (0 bytes)
            0.000 sec. for 4 defragmentations
            0.000 sec. for 7 dead clause reclamations
            0.000 sec. for 0 dead predicate reclamations
           39.410 sec. runtime
         ========
           39.490 sec. total runtime
          109.200 sec. elapsed time

Note the use of indentation to indicate sub-areas. That is, memory contains the program space and the four stacks: global, local, choice, and trail.

The memory (total) figure shown as “in use” is the sum of the spaces for the program space and stacks. The “free” figures for the stacks are for free space within those areas. However, this free space is considered used as far as the memory (total) area is concerned, because it has been allocated to the stacks. The program space is not considered to have its own free space. It always allocates new space from the general memory (total) free area.

If a memory resource error has occurred previously in the execution, the memory area for which memory could not be allocated is displayed.

Individual statistics can be obtained by statistics/2, which accepts a keyword and returns a list of statistics related to that keyword.

The keys and values for statistics(Keyword, Value) are summarized below. The keywords core and heap are included to retain compatibility with other Prologs. Times are given in milliseconds and sizes are given in bytes.

Keyword

Value

runtime

[since start of Prolog,since previous statistics]
These refer to CPU time used while executing, excluding time spent in memory management tasks or or in system calls. The second element is the time since the latest call to statistics/2 with this key or to statistics/0.

total_runtime

[since start of Prolog,since previous statistics]
These refer to total CPU time used while executing, including memory management tasks such as garbage collection but excluding system calls. The second element is the time since the latest call to statistics/2 with this key or to statistics/0.

walltime

[since start of Prolog,since previous statistics]
These refer to absolute time elapsed. The second element is the time since the latest call to statistics/2 with this key or to statistics/0.

global_stack

[size used,free]
This refers to the global stack, where compound terms are stored. The values are gathered before the list holding the answers is allocated. Formed from basic values below.

local_stack

[size used,free]
This refers to the local stack, where recursive predicate environments are stored. Formed from basic values below.

trail

[size used,free]
This refers to the trail stack, where conditional variable bindings are recorded. Formed from basic values below.

choice

[size used,free]
This refers to the choice stack, where partial states are stored for backtracking purposes. Formed from basic values below.

memory

core

[size used,0]
These refer to the amount of memory actually allocated by the Prolog engine. The zero is there for compatibility with other Prolog implementations. Formed from basic values below.

program

heap

[size used,size free]
These refer to the amount of memory allocated for the database, symbol tables, and the like. Formed from basic values below.

garbage_collection

[no. of GCs,bytes freed,time spent]
Formed from basic values below.

stack_shifts

[no. of global shifts,no. of local/choice shifts,time spent]
Formed from basic values below.

atoms

[no. of atoms,bytes used,atoms free]
The number of atoms free is the number of atoms allocated (the first element in the list) subtracted from the maximum number of atoms, i.e. 262143 (33554431) on 32-bit (64-bit) architectures. Note that atom garbage collection may be able to reclaim some of the allocated atoms. Formed from basic values below.

atom_garbage_collection

[no. of AGCs,bytes freed,time spent]
Formed from basic values below.

defragmentation

[no. of defragmentations,time spent]
Formed from basic values below.

memory_used

bytes used

memory_free

bytes free

global_stack_used

bytes used

global_stack_free

bytes free

local_stack_used

bytes used

local_stack_free

bytes free

trail_used

bytes used

trail_free

bytes free

choice_used

bytes used

choice_free

bytes free

atoms_used

bytes used

atoms_nbused

atoms used

atoms_nbfree

atoms free

ss_global

number of global stack shifts

ss_local

number of local stack shifts

ss_choice

number of choice stack shifts

ss_time

time spent stack shifting

gc_count

number of garbage collections

gc_freed

number of bytes freed

gc_time

time spent collecting garbage

agc_count

number of atom garbage collections

agc_nbfreed

number of garbage collected atoms

agc_freed

number of bytes freed by atom garbage collected

agc_time

time spent garbage collected atoms

defrag_count

number of memory defragmentations

defrag_time

time spent defragmenting memory

dpgc_count

number of dead predicate reclamations

dpgc_time

time spent reclaiming dead predicates

dcgc_count

number of dead clause reclamations

dcgc_time

time spent reclaiming dead clauses

memory_culprit

memory bucket in which latest memory resource error occurred

memory_buckets

list of bucket-size pair
where size is the amount of memory in use for memory bucket bucket.

To see an example of the use of each of these keywords, type

     | ?- statistics(K, L).

and then repeatedly type `;' to backtrack through all the possible keywords. As an additional example, to report information on the runtime of a predicate p/0, add the following to your program:

     :- statistics(runtime, [T0| _]),
        p,
        statistics(runtime, [T1|_]),
        T is T1 - T0,
        format('p/0 took ~3d sec.~n', [T]).