
statistics(?Keyword, -Value)

   Succeeds if the statistics item Keyword has value Value.



Arguments
   Keyword             Atom or Variable.
   Value               Prolog term.

Type
   Development Environment and Global Settings

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 --- 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
