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   since release 4.1

bytes used

memory_free   since release 4.1

bytes free

global_stack_used   since release 4.1

bytes used

global_stack_free   since release 4.1

bytes free

local_stack_used   since release 4.1

bytes used

local_stack_free   since release 4.1

bytes free

trail_used   since release 4.1

bytes used

trail_free   since release 4.1

bytes free

choice_used   since release 4.1

bytes used

choice_free   since release 4.1

bytes free

atoms_used   since release 4.1

bytes used

atoms_nbused   since release 4.1

atoms used

atoms_nbfree   since release 4.1

atoms free

ss_global   since release 4.1

number of global stack shifts

ss_local   since release 4.1

number of local stack shifts

ss_choice   since release 4.1

number of choice stack shifts

ss_time   since release 4.1

time spent stack shifting

gc_count   since release 4.1

number of garbage collections

gc_freed   since release 4.1

number of bytes freed

gc_time   since release 4.1

time spent collecting garbage

agc_count   since release 4.1

number of atom garbage collections

agc_nbfreed   since release 4.1

number of garbage collected atoms

agc_freed   since release 4.1

number of bytes freed by atom garbage collected

agc_time   since release 4.1

time spent garbage collected atoms

defrag_count   since release 4.1

number of memory defragmentations

defrag_time   since release 4.1

time spent defragmenting memory

dpgc_count   since release 4.1

number of dead predicate reclamations

dpgc_time   since release 4.1

time spent reclaiming dead predicates

dcgc_count   since release 4.1

number of dead clause reclamations

dcgc_time   since release 4.1

time spent reclaiming dead clauses

memory_culprit   since release 4.1

memory bucket in which latest memory resource error occurred

memory_buckets   since release 4.1

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

jit_count   since release 4.3

number of JIT-compiled predicates
This is zero when JIT compilation is not available.

jit_time   since release 4.3

time spent JIT-compiling predicates
This is zero when JIT compilation is not available.

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]).

See mpg-ref-statistics.