[ Development Environment and Global Settings | The ECLiPSe Built-In Predicates | Reference Manual | Alphabetic Index ]

# statistics(?Keyword, -Value)

Succeeds if the statistics item Keyword has value Value.

Keyword
  Atom or Variable.
Value
  Prolog term.

## Description

Used to retrieve various statistical information about the running ECLiPSe . To print a list of all the current values, statistics/0 can be used.

The following list details the statistic items:

shared_heap_allocated

  Unit : bytes

  Description : The amount of memory assigned to the code heap, i.e. the area used for storing compiled Prolog code, atoms, records, non-logical variables, descriptors, buffers etc. This area will never shrink.

shared_heap_used

  Unit : bytes

  Description : The amount of memory currently used for compiled Prolog code, atoms, records, non-logical variables, descriptors, buffers etc.

control_stack_allocated

  Unit : bytes

  Description : The amount of control stack currently allocated. The control stack is allocated in chunks, up to a maximum controlled by the -l command line option. The local and control stacks share the same memory area specified by the -l option, which thus gives the maximum combined allocated size of these two stacks.

control_stack_peak

  Unit : bytes

  Description : The peak allocated size of the control stack during this session. Chunks of memory can be allocated to, and deallocated from, the control stack as it grows and shrinks.

control_stack_used

  Unit : bytes

  Description : The amount of control stack currently in use. This stack holds information needed for backtracking.

dictionary_entries

  Unit : count

  Description : The number of atoms and functors that are currently known to the system. This is equal to the number of solutions that current_functor/1 would return.

dict_hash_usage

  Unit : List of counts

  Description : Returns a list of two numbers: the number of slots in hash table of the dictionary that are actually used, and the number of slots in the dictionary hash table.

dict_hash_collisions

  Unit : list of counts

  Description : Returns a list of two numbers: the length of the longest list in a hash table slot (i.e. the maximum number of dictionary entries that are hashed to the same slot), and the number of slots in the dictionary hash table.

dict_gc_number

  Unit : count

  Description : The number of dictionary garbage collections performed during this session.

dict_gc_time

  Unit : seconds

  Description : The total cputime spent by all dictionary garbage collections performed during this session.

event_time

  Unit : Seconds

  Description : Returns the elapsed real time (session_time) or the elapsed user time (cputime) since the start of a (parallel) ECLiPSe session depending on the value of the after_event_timer flag.

gc_area

  Unit : bytes

  Description : The average area processed by a garbage collection. This number should be close to the value of gc_interval. If it is much higher, gc_interval should be increased.

gc_collected

  Unit : bytes

  Description : The total number of bytes collected in the global stack during all the garbage collections in this session.

gc_number

  Unit : count

  Description : The number of global/trail stack garbage collections performed during this session.

gc_ratio

  Unit : percent

  Description : The average percentage of garbage found and collected in the garbage collections performed so far. If this number is low, gc_interval should be increased.

gc_time

  Unit : seconds

  Description : The total time spent for all garbage collections in this session.

private_heap_allocated

  Unit : bytes

  Description : The amount of memory assigned to the private heap. This area will never shrink.

private_heap_used

  Unit : bytes

  Description : The amount of memory currently used for private data.

global_stack_allocated

  Unit : bytes

  Description : The amount of global stack currently allocated. The global stack is allocated in chunks, up to a maximum controlled by the -g command line option. The global stack and trail share the same memory area specified by the -g option, which thus gives the maximum possible combined allocated size of these two stacks.

global_stack_peak

  Unit : bytes

  Description : The peak allocated size of the global stack during this session. Chunks of memory can be allocated to, and deallocated from, the global stack as it grows and shrinks.

global_stack_used

  Unit : bytes

  Description : The amount of global stack currently in use. The global stack holds lists and structures and is subject to garbage collection.

local_stack_allocated

  Unit : bytes

  Description : The amount of local stack currently allocated. The local stack is allocated in chunks, up to a maximum controlled by the -l command line option. The local and control stacks share the same memory area specified by the -l option, which thus gives the maximum combined allocated size of these two stacks.

local_stack_peak

  Unit : bytes

  Description : The peak allocated size of the local stack during this session. Chunks of memory can be allocated to, and deallocated from, the local stack as it grows and shrinks.

local_stack_used

  Unit : bytes

  Description : The amount of local stack currently in use. This stack holds Prolog variables and return addresses.

memory, core

  Unit : List of bytes

  Description : The second number is always zero. The first number is the total amount of memory currently allocated in the various stacks. This is provided mainly for compatibility.

program, heap

  Unit : List of bytes

  Description : Returns a list of two numbers for the allocated shared heap, where, along with other items, program code is stored: the number of bytes currently used, and the number of bytes currently free. It is provided mainly for compatibility.

global_stack

  Unit : List of bytes

  Description : Returns a list of two numbers for the allocated global stack: the number of bytes currently used, and the number of bytes currently free. It is provided mainly for compatibility.

local_stack

  Unit : List of bytes

  Description : Returns a list of two numbers on the current usage of the allocated local and control stacks. In the original WAM, these two stacks are combined into a single stack. This is provided for compatibility purposes only.

trail

  Unit : List of bytes

  Description : Returns a list of two numbers for the allocated trail: the number of bytes currently used, and the number of bytes currently free. It is provided mainly for compatibility.

garbage_collection

  Unit : List of numbers

  Descriptions : Returns a list that summaries garbage collections during this session: the number of times it has occurred, the number of bytes freed, and the total time spent (in seconds). This is provided mainly for compatibility purposes.

runtime

  Unit : List of milliseconds

  Description : Returns a list of two times: user cpu time since the start of the ECLiPSe session, user cpu time since the last call to statistics(runtime, _). As from ECLiPSe 4.2, these times exclude the time spent in garbage collection. This item is provided primarily for compatibility reasons.

session_time

  Unit : Seconds

  Description : Returns the real time elapsed since the start of a (parallel) ECLiPSe session. This is the only timer that can be reliably used in a parallel execution, since it accesses a central clock. All other timers are local to the worker where they are accessed.

times

  Unit : List of seconds

  Description : Returns a list of three times: user cpu time, system cpu time and real time elapsed since the start of the ECLiPSe session.

trail_stack_allocated

  Unit : bytes

  Description : The amount of trail stack currently allocated. The trail is allocated in chunks, up to a maximum controlled by the -g command line option. The global stack and trail share the same memory area specified by the -g option, which thus gives the maximum possible combined allocated size of these two stacks.

trail_stack_peak

  Unit : bytes

  Description : The peak allocated size of the trail stack during this session. Chunks of memory can be allocated to, and deallocated from, the trail stack as it grows and shrinks.

trail_stack_used

  Unit : bytes

  Description : The amount of trail stack currently in use. The trail stack records information needed for backtracking and is subject to garbage collection.

### Modes and Determinism

- statistics(-, -) is multi
- statistics(+, -) is det

### Exceptions

(5) type error
  Keyword is neither an atom nor variable.

## Examples

    Success:
       [eclipse]: statistics(times, [_,_,T]).
       T = 2848.64
       yes.
       [eclipse]: statistics(global_stack_used, G).
       G = 136
       yes.
    Fail:
       statistics(times, [T]).
    Error:
       statistics("time", T).    (Error 5)

## See Also

set_flag / 2, env / 0, statistics / 0