% BEGIN LICENSE BLOCK
% Version: CMPL 1.1
%
% The contents of this file are subject to the Cisco-style Mozilla Public
% License Version 1.1 (the "License"); you may not use this file except
% in compliance with the License.  You may obtain a copy of the License
% at www.eclipse-clp.org/license.
% 
% Software distributed under the License is distributed on an "AS IS"
% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied.  See
% the License for the specific language governing rights and limitations
% under the License. 
% 
% The Original Code is  The ECLiPSe Constraint Logic Programming System. 
% The Initial Developer of the Original Code is  Cisco Systems, Inc. 
% Portions created by the Initial Developer are
% Copyright (C) 2006 Cisco Systems, Inc.  All Rights Reserved.
% 
% Contributor(s): 
% 
% END LICENSE BLOCK

:- comment(alias, "Development Environment and Global Settings").
:- comment(summary, "Built-ins related to the development environment").

:- tool(env / 0).
:- tool(get_flag / 2).
:- tool(set_flag / 2).
:- tool(pred / 1).

:- comment(statistics / 2, [
	summary:"Succeeds if the statistics item Keyword has value Value.

",
	amode:(statistics(-,-) is multi),
	amode:(statistics(+,-) is det),
	desc:html("   Used to retrieve various statistical information about the running
   ECLiPSe .  To print a list of all the current values, statistics/0 can
   be used.

<P>
   The following list details the statistic items:

<DL>
<DT><STRONG>shared_heap_allocated</STRONG><DD>

<P>
    Unit :   bytes

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

<DT><STRONG>shared_heap_used</STRONG><DD>

<P>
    Unit :   bytes

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

<DT><STRONG>control_stack_allocated</STRONG><DD>

<P>
    Unit :  bytes

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

<DT><STRONG>control_stack_peak</STRONG><DD>

<P>
    Unit : bytes

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

<DT><STRONG>control_stack_used</STRONG><DD>

<P>
    Unit :   bytes

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

<DT><STRONG>dictionary_entries</STRONG><DD>

<P>
    Unit :   count

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

<DT><STRONG>dict_hash_usage</STRONG><DD>

<P>
    Unit :  List of counts 

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

<DT><STRONG>dict_hash_collisions</STRONG><DD>

<P>
    Unit :   list of counts

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

<DT><STRONG>dict_gc_number</STRONG><DD>

<P>
    Unit :   count

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

<DT><STRONG>dict_gc_time</STRONG><DD>

<P>
    Unit :   seconds

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

<DT><STRONG>event_time</STRONG><DD>

<P>
    Unit :   Seconds

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

<DT><STRONG>gc_area</STRONG><DD>

<P>
    Unit :   bytes

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

<DT><STRONG>gc_collected</STRONG><DD>

<P>
    Unit :   bytes

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

<DT><STRONG>gc_number</STRONG><DD>

<P>
    Unit :   count

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

<DT><STRONG>gc_ratio</STRONG><DD>

<P>
    Unit :   percent

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

<DT><STRONG>gc_time</STRONG><DD>

<P>
    Unit :   seconds

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

<DT><STRONG>private_heap_allocated</STRONG><DD>

<P>
    Unit :   bytes

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

<DT><STRONG>private_heap_used</STRONG><DD>

<P>
    Unit :   bytes

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

<DT><STRONG>global_stack_allocated</STRONG><DD>

<P>
    Unit :   bytes

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

<DT><STRONG>global_stack_peak</STRONG><DD>

<P>
    Unit :   bytes

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

<DT><STRONG>global_stack_used</STRONG><DD>

<P>
    Unit :   bytes

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

<DT><STRONG>local_stack_allocated</STRONG><DD>

<P>
    Unit :   bytes

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

<DT><STRONG>local_stack_peak</STRONG><DD>

<P>
    Unit :   bytes

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

<DT><STRONG>local_stack_used</STRONG><DD>

<P>
    Unit :   bytes

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

<DT><STRONG>memory, core</STRONG><DD>

<P>
   Unit :    List of bytes

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

<DT><STRONG>program, heap</STRONG><DD>

<P>
    Unit :   List of bytes

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

<DT><STRONG>global_stack</STRONG><DD>

<P>
    Unit :   List of bytes

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

<DT><STRONG>local_stack</STRONG><DD>

<P>
    Unit :   List of bytes

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

<DT><STRONG>trail</STRONG><DD>

<P>
    Unit :   List of bytes

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

<DT><STRONG>garbage_collection</STRONG><DD>

<P>
    Unit :   List of numbers

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

<DT><STRONG>runtime</STRONG><DD>

<P>
    Unit :   List of milliseconds

<P>
    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
\texclude the time spent in garbage collection. This item is provided
        primarily for compatibility reasons.

<DT><STRONG>session_time</STRONG><DD>

<P>
    Unit :   Seconds

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

<DT><STRONG>times</STRONG><DD>

<P>
    Unit :   List of seconds

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

<DT><STRONG>trail_stack_allocated</STRONG><DD>

<P>
    Unit :   bytes

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

<DT><STRONG>trail_stack_peak</STRONG><DD>

<P>
    Unit :   bytes

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

<DT><STRONG>trail_stack_used</STRONG><DD>

<P>
    Unit :   bytes

<P>
    Description :   The amount of trail stack currently in use.  The
        trail stack records information needed for backtracking and is
        subject to garbage collection.
</DL>
"),
	args:["Keyword" : "Atom or Variable.", "Value" : "Prolog term."],
	exceptions:[5 : "Keyword is neither an atom nor variable."],
	eg:"
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]]).


:- comment(make / 0, [
	summary:"Recompile all files that have been modified since their last compilation.

",
	amode:(make is det),
	desc:html("   This is a simple utility which uses file modification times to determine
   if a file needs recompilation.  All compiled files in the system are
   examined and recompiled if they have been modified since the previous
   compilation.  make/0 can be defined as follows:

<P>
<PRE>
make :- current_compiled_file(File, Time, Module),
        get_file_info(File, mtime) =\\= Time,
        compile(File, Module),
        fail.
make.
</PRE>
"),
	args:[],
	eg:"
[eclipse 1]: [file1,file2].
file1.pl   compiled traceable 40 bytes in 0.00 seconds
file2.pl   compiled traceable 40 bytes in 0.00 seconds

yes.
[eclipse 2]: sh(\"touch file1.pl\").

yes.
[eclipse 3]: make.
file1.pl   compiled traceable 40 bytes in 0.00 seconds

yes.



",
	see_also:['.' / 2, compile / 1, compile / 2, current_compiled_file / 3, ensure_loaded / 1]]).

:- comment(profile / 1, [
	summary:"Profile the goal and print the times spent in each predicate.

",
	amode:(profile(+) is det),
	desc:html("<P>\
   This predicate invokes the profiler with default options.  Equivalent to:
   <PRE>
       profile(Goal, []).
   </PRE>
   See profile/2 for details.
</P>
"),
	args:["Goal" : "Atom or a compound term."],
	exceptions:[6 : "Flags contains an illegal flag."],
	eg:"
[eclipse 6]: profile(boyer).
rewriting...
proving...
goal succeeded

                PROFILING STATISTICS
                --------------------

Goal:             boyer
Total user time:  10.65s

Predicate             Module         %Time  Time
-------------------------------------------------
rewrite           /2  eclipse        52.3%  5.57s
garbage_collect   /0  sepia_kernel   23.1%  2.46s
rewrite_args      /2  eclipse        16.6%  1.77s
equal             /2  eclipse         4.7%  0.50s
...
plus              /3  eclipse         0.1%  0.01s



",
	see_also:[get_flag / 2, profile / 2]]).

:- comment(profile / 2, [
	summary:"Profile the goal and print the times spent in each predicate.

",
	amode:(profile(+,++) is det),
	desc:html("<P>\
   This predicate invokes the profiler.  The profiler first executes Goal
   in profiling mode, which means that during its execution interrupts are
   generated at regular intervals and the profiler remembers the currently
   executing predicate.  When the goal succeeds or fails, the profiler
   prints so, and then it prints the statistics about the time spent in
   every encountered predicate.  Goal can be any Prolog goal, it does not
   have to be compiled in a special profiling mode and no Prolog flags have
   to be set.  The time spent in simple predicates (i.e. those with call_type
   external, written in C) is counted towards their parent predicate.
</P><P>
   In cases where the predicate name is not available, e.g. local goals in
   a locked module, the information is grouped under a blank predicate
   name entry for the module.
</P><P>
   Flags is a list of option flags:
   <DL>
   <DT>simple</DT>
       <DD>obsolete</DD>
   <DT>keep_file</DT>
       <DD>do not remove temporary data file when finished</DD>
   </DL>
</P><P>
   A temporary file &lt;tmp_dir&gt;/eclipse.prof.&lt;pid&gt; is used to collect the
   profiling information and is removed upon exit (unless keep_file option
   is given).
</P>
"),
	args:["Goal" : "Atom or a compound term.", "Flags" : "List of atoms."],
	exceptions:[6 : "Flags contains an illegal flag."],
	eg:"
[eclipse 6]: profile(boyer, []).
rewriting...
proving...
goal succeeded

                PROFILING STATISTICS
                --------------------

Goal:             boyer
Total user time:  10.55s

Predicate             Module         %Time  Time
-------------------------------------------------
=..               /2  sepia_kernel   31.1%  3.28s
garbage_collect   /0  sepia_kernel   23.5%  2.48s
rewrite           /2  eclipse        21.6%  2.28s
rewrite_args      /2  eclipse        17.2%  1.82s
equal             /2  eclipse         4.1%  0.43s
remainder         /3  eclipse         0.9%  0.10s
...
plus              /3  eclipse         0.1%  0.01s

yes.




",
	see_also:[get_flag / 2, profile / 1]]).

:- comment(env / 0, [
	summary:"Prints information about the current ECLiPSe environment on the current
output.

",
	amode:(env is det),
	desc:html("   Prints a list of the current global flag values on the toplevel output
   stream.  These are the same values that get_flag/2 provides.

<P>
"),
	args:[],
	eg:"
[eclipse]: env.

after_event_timer:      real            last_errno:             0              
all_dynamic:            off             macro_expansion:        on             
break_level:            0               max_global_trail:       134217728      
coroutine:              off             max_local_control:      134217728      
debug_compile:          on              max_predicate_arity:    255            
debugging:              nodebug         object_suffix:          \"so\"           
dfid_compile:           off             occur_check:            off            
eclipse_info_suffix:    \".eci\"          output_mode:            \"QPm\"          
eclipse_object_suffix:  \".eco\"          pid:                    270            
enable_interrupts:      on              ppid:                   27420          
float_precision:        double          prefer_rationals:       off            
gc:                     on              print_depth:            20             
gc_interval:            4194304         remote_protocol_version:1              
gc_interval_dict:       960             toplevel_module:        eclipse        
gc_policy:              adaptive        unix_time:              1006351709     
goal_expansion:         on              version:                '5.8'          
hostarch:               \"sparc_sunos5\"  version_as_list:        [5, 8, 75]    
hostid:                 \"2152252216\"    wm_window:              off            
ignore_eof:             off             worker:                 0              

cwd:                    \"/homes/john/\" 
default_language:       eclipse_language 
extension:              development occur_check dfid 
hostname:               \"tempest.icparc.ic.ac.uk\" 
installation_directory: \"/usr/local/eclipse\" 
library_path:           [\"/usr/local/eclipse/lib\",
                         \"/usr/local/eclipse/lib_public\"]
loaded_library:         tracer_tty development_support toplevel ...
output_options:         [depth(20), attributes(pretty), quoted(true), ...]
prolog_suffix:          [\"\", \".ecl\", \".pl\"] 
syntax_option:          nl_in_quotes no_blanks
variable_names:         check_singletons 
workerids:              \"tempest.icparc.ic.ac.uk\" : [0] + [] 
workers:                \"tempest.icparc.ic.ac.uk\" : 1 

",
	see_also:[get_flag / 2, set_flag / 2]]).

:- comment(trimcore/0, [
	summary:"Frees currently unused memory.",
	amode:(trimcore is det),
	desc: html("\

   Calling this predicate will free some currently deallocated memory, such
   as memory occupied by retracted and abolished clauses. It also
   returns deallocated stack space back to the operating system.")
]).


:- comment(garbage_collect / 0, [
	summary:"Request an immediate garbage collection.

",
	amode:(garbage_collect is det),
	desc:html("   Causes an immediate garbage collection of the global and trail stack,
   provided that the garbage collector is not switched off (cf.
   set_flag/2).  In any case the predicate succeeds.

<P>
   Note that the garbage collector is usually triggered automatically,
   controlled by the user-definable flag gc_interval.  Therefore, the usage
   of garbage_collect/0 should be restricted to situations where the
   automatic triggering performs badly.  In this case it should be inserted
   in a place where it is known for sure that a lot of structures and lists
   have become useless, eg.  just before a tail-recursive call as shown in
   the example.

<P>
"),
	args:[],
	eg:"
cycle(OldState) :-
    transform(OldState, NewState), /* long computation     */
    !,
    garbage_collect,               /* OldState is obsolete */
    cycle(NewState).



",
	see_also:[env / 0, set_flag / 2, get_flag / 2]]).

:- comment(get_flag / 2, [
	summary:"Succeeds if the flag Flag has the value Value.

",
	amode:(get_flag(-,-) is nondet),
	amode:(get_flag(+,-) is nondet),
	index:[
	    after_event_timer,
	    all_dynamic,
	    break_level,
	    coroutine,
	    cwd,
	    debug_compile,
	    debugging,
	    default_language,
	    eclipse_info_suffix,
	    eclipse_object_suffix,
            tmp_dir,
	    enable_interrupts,
	    extension,
	    float_precision,
	    gc,
	    gc_interval,
	    gc_interval_dict,
	    gc_policy,
	    goal_expansion,
	    hostarch,
	    hostid,
	    hostname,
	    ignore_eof,
	    installation_directory,
	    last_errno,
	    library_path,
	    loaded_library,
	    macro_expansion,
	    max_global_trail,
	    max_local_control,
	    max_predicate_arity,
	    object_suffix,
	    occur_check,
	    output_mode,
	    output_options,
	    pid,
	    ppid,
	    prefer_rationals,
	    print_depth,
	    prolog_suffix,
	    remote_protocol_version,
	    syntax_option,
	    toplevel_module,
	    unix_time,
	    variable_names,
	    version,
	    version_as_list,
	    worker,
	    workers,
	    workerids,
	    wm_window,
	% syntax options
	    atom_subscripts,
	    bar_is_no_atom,
	    based_bignums,
	    blanks_after_sign,
	    blanks_in_nil,
	    curly_args_as_list,
	    doubled_quote_is_quote,
	    general_subscripts,
	    iso_base_prefix,
	    iso_escapes,
	    limit_arg_precedence,
	    nested_comments,
	    nl_in_quotes,
	    no_array_subscripts,
	    no_attributes,
	    no_blanks,
	    no_curly_arguments,
	    read_floats_as_breals,
	    var_functor_is_apply,
	    '$VAR'
	    ],
	desc:html("   Used to return or check the environment flag Flag with value Value.  The
   environment flags which are read/write may be updated using set_flag/2.
   The current values of the environment flags are returned by env/0.
<P>
   The following list details the environment flags:
<DL>
<DT><STRONG>after_event_timer</STRONG><DD>

<P>
    Access mode :   read/write

<P>
    Type :  Atomic constant <EM>real</EM> or <EM>virtual</EM>

<P>
    Description : Specifies the timer used for event_after/2 and
        event_after_every/2.

<P>
<DT><STRONG>all_dynamic</STRONG><DD>

<P>
    Access mode :   read/write

<P>
    Type :   Atomic constant <EM>on</EM> or <EM>off</EM>

<P>
    Default :   off

<P>
    Description :   Specifies whether all clauses compiled are dynamic
        or not. Mainly for test purposes.

<P>
<DT><STRONG>break_level</STRONG><DD>

<P>
    Access mode :   read/write

<P>
    Type :   Integer

<P>
    Description :   Specifies current nesting level of recursive
        top-level loops.

<P>
<DT><STRONG>breal_exceptions</STRONG><DD>

<P>
    Access mode :   read/write

<P>
    Type :   Atomic constant <EM>on</EM> or <EM>off</EM>

<P>
    Default :   off

<P>
    Description :   If <EM>on</EM>,  unifying or testing bounded reals
	for identity raises an 'undecidable comparison of bounded reals'
	exception in case the comparison is undecidable (i.e. the bounds
	overlap).  If <EM>off</EM>, bounded reals compare equal when
	their bounds are equal.  This flag does not affect arithmetic
	comparisons.

<P>
<DT><STRONG>coroutine</STRONG><DD>

<P>
    Access mode :   read/write

<P>
    Type :   Atomic constant <EM>on</EM> or <EM>off</EM>

<P>
    Default :   configuration dependent

<P>
    Description :   Specifies whether built-in predicates delay or
        raise instantiation faults.

<P>
<DT><STRONG>cwd</STRONG><DD>

<P>
    Access mode :   read/write

<P>
    Type :   String

<P>
    Description :   Specifies the name of the current working
        directory.  May also be set using cd/1 or read using getcwd/1.

<P>
<DT><STRONG>debug_compile</STRONG><DD>

<P>
    Access mode :   read/write

<P>
    Type :   Atomic constant <EM>on</EM> or <EM>off</EM>

<P>
    Default :   on

<P>
    Description :   Specifies whether clauses are compiled for
        debugging or not.  May be overwritten on a file by file
	basis using pragma(debug) or pragma(nodebug).

<P>
<DT><STRONG>debugging</STRONG><DD>

<P>
    Access mode : read-only

<P>
    Type : Atomic constant <EM>nodebug</EM>, <EM>creep</EM>, or <EM>leap</EM>

<P>
    Default :   nodebug

<P>
    Description : Specifies whether debugging is disabled (nodebug) or
    \tenabled.  trace/0 sets the creep mode, debug/0 sets the leap mode.

<P>
<DT><STRONG>default_language</STRONG><DD>

<P>
    Access mode : read/write

<P>
    Type : Atom

<P>
    Default :   eclipse_language

<P>
    Description : Specifies the source language dialect for modules which
    	are created without an explicit language specification (module/1
	directive or the create_module/1). Other possible settings are
	for example 'iso' or 'sicstus'.

<P>

<P>
<DT><STRONG>eclipse_info_suffix</STRONG><DD>

<P>
    Access mode : read

<P>
    Type : String

<P>
    Default : \".eci\"

<P>
    Description : Specifies the ECLiPSe information file suffix used when a 
        file is generated by icompile/1. The suffix will be automatically
        appended to the base file name when the information file is 
        generated. 

<P>
<DT><STRONG>eclipse_object_suffix</STRONG><DD>

<P>
    Access mode : read

<P>
    Type : String

<P>
    Default : \".eco\"

<P>
    Description : Specifies the ECLiPSe object file suffix used when a file
        is fcompiled. The suffix will be automatically appended to the 
        file's base name when the object file is generated. When loading a 
        file (e.g. use_module/1, lib/1), the system will try to find an
        object file before a source file by appending the given suffix
        before the source suffix(es).

<P>
<DT><STRONG>enable_interrupts</STRONG><DD>

<P>
    Access mode : read/write

<P>
    Type : Atomic constant <EM>on</EM> or <EM>off</EM>

<P>
    Default :   on

<P>
    Description : If on, interrupts are recognised and processed as
        they occur.  If off, interrupts are entered into a delay queue
        and processed only when the flag is switched back to on.
        Interrupts should be disabled only for short periods of time in
        order to keep the system's interrupt response time short.

<P>
<DT><STRONG>extension</STRONG><DD>

<P>
    Access mode : read-only

<P>
    Type : Atomic constant.

<P>
    Default :   configuration dependent

<P>
    Description : Specifies which extensions are available in the
        system.  This flag may contain multiple values and will return
        them on backtracking.

<P>
<DT><STRONG>float_precision</STRONG><DD>

<P>
    Access mode : read-only

<P>
    Type : Atomic constant

<P>
    Default :   double

<P>
    Description : This flag is obsolete. Its value is always <EM>double</EM>.

<P>
<DT><STRONG>gc</STRONG><DD>

<P>
    Access mode :   read/write

<P>
    Type :   Atomic constant <EM>on</EM>, <EM>verbose</EM> or <EM>off</EM>

<P>
    Default :   on

<P>
    Description :   Specifies whether garbage collection is enabled
        (on), disabled (off) or enabled and reports every collection on
        log_output (verbose).

<P>
<DT><STRONG>gc_policy</STRONG><DD>

<P>
    Access mode :   read/write

<P>
    Type :   Atomic constant <EM>adaptive</EM> or <EM>fixed</EM>.

<P>
    Default :   adaptive

<P>
    Description :   This option affects the triggering heuristics of
	the garbage collector, together with the gc_interval setting.
	The <EM>adaptive</EM> policy minimises garbage collection time,
	while the <EM>fixed</EM> policy minimises space consumption.

<P>
<DT><STRONG>gc_interval</STRONG><DD>

<P>
    Access mode :   read/write

<P>
    Type :   Integer

<P>
    Default :   1/32 of global stack size, at least 64KB

<P>
    Description :   Specify how often the collector is invoked.
	Roughly, the argument specifies the minimum number of bytes a
	program must have newly allocated before a garbage collection
	is triggered.  If the garbage collector runs frequently while
	reclaiming little space it may make sense to increase
	gc_interval, thus reducing the number of garbage collections. 
	This is normally only necessary when the gc_policy is set to
	<EM>fixed</EM>.  With gc_policy set to <EM>adaptive</EM>, the
	collection intervals will be adjusted automatically.  See also
	gc_policy setting.

<P>
<DT><STRONG>gc_interval_dict</STRONG><DD>

<P>
    Access mode :   read/write

<P>
    Type :   Integer

<P>
    Default :   960

<P>
    Description :   Specify after how many new dictionary entries the
        dictionary garbage collector is invoked.

<P>
<DT><STRONG>goal_expansion</STRONG><DD>

<P>
    Access mode :   read/write

<P>
    Type :   Atomic constant <EM>on</EM> or <EM>off</EM>

<P>
    Default :   on

<P>
    Description :   Specifies whether goal expansion is done by the
        compiler. This includes compiler inlining and goal macro
        transformations.  Can be disabled for debugging purposes.

<P>
<DT><STRONG>hostarch</STRONG><DD>

<P>
    Access mode : read-only

<P>
    Type : String

<P>
    Description : String identifying the host processor and operating
        system.  It is also the name of the machine-dependent
        subdirectories in the ECLiPSe installation.

<P>
<DT><STRONG>hostid</STRONG><DD>

<P>
    Access mode : read-only

<P>
    Type : String

<P>
    Description : The unique identification of the host machine that
        the system is running on.

<P>
<DT><STRONG>hostname</STRONG><DD>

<P>
    Access mode : read-only

<P>
    Type : string

<P>
    Description : The name of the current host machine.

<P>
<DT><STRONG>ignore_eof</STRONG><DD>

<P>
    Access mode : read/write

<P>
    Type :   Atomic constant <EM>on</EM> or <EM>off</EM>

<P>
    Description : Controls whether ECLiPSe can be exited by typing an
        end-of-file to the toplevel-prompt or whether this is ignored.
        If ignored, ECLiPSe can be exited by calling halt/0.

<P>
<DT><STRONG>installation_directory</STRONG><DD>

<P>
    Access mode : read-only

<P>
    Type : string

<P>
    Description : The name of the toplevel directory of the running
        ECLiPSe installation.  All ECLiPSe library, documentation and
        other directories are below this one.

<P>
<DT><STRONG>last_errno</STRONG><DD>

<P>
    Access mode : read-only

<P>
    Type : Integer

<P>
    Description : The error code that the most recent failed operating
        system call returned. This should no longer be used because of
        portability problems, use errno_id/1 instead.

<P>
<DT><STRONG>library_path</STRONG><DD>

<P>
    Access mode : read/write

<P>
    Type : List of strings

<P>
    Default :   the contents of the user's ECLIPSELIBRARYPATH
        environment variable, followed by the system library
        directories

<P>
    Description : Specifies the list of pathnames used by the system to
        search for library files.  The library path is used by lib/1
        for autoloading, and to expand library/1 structures in
        pathnames.

<P>
<DT><STRONG>loaded_library</STRONG><DD>

<P>
    Access mode :   read/write

<P>
    Type :   Atom

<P>
    Description :   Returns the names of the currently loaded
        libraries.  This flag may contain multiple values and will
        return them on backtracking.

<P>
<DT><STRONG>macro_expansion</STRONG><DD>

<P>
    Access mode :   read/write

<P>
    Type :   Atomic constant <EM>on</EM> or <EM>off</EM>

<P>
    Default :   on

<P>
    Description :   Specifies whether macro expansion used by the
        source transformation facility is enabled or disabled.  Should
        be disabled only for debugging purposes.

<P>
<DT><STRONG>max_global_trail</STRONG><DD>

<P>
    Access mode : read-only

<P>
    Type : Integer

<P>
    Description : The maximum size in bytes to which the global/trail stack
        can grow. See also statistics/2.

<P>
<DT><STRONG>max_local_control</STRONG><DD>

<P>
    Access mode : read-only

<P>
    Type : Integer

<P>
    Description : The maximum size in bytes to which the global/trail stack
        can grow. See also statistics/2.

<P>
<DT><STRONG>max_predicate_arity</STRONG><DD>

<P>
    Access mode :   read-only

<P>
    Type :   Integer

<P>
    Default :   255

<P>
    Description :   Returns the maximum number of arguments allowed for
        an ECLiPSe predicate.

<P>
<DT><STRONG>object_suffix</STRONG><DD>

<P>
    Access mode :   read-only

<P>
    Type :   String

<P>
    Description :   Returns the suffix of the external object files
        that can be loaded using load/1.  It is usually \"so\" for
        systems that support shared libraries and \"o\" for the others.

<P>
<DT><STRONG>occur_check</STRONG><DD>

<P>
    Access mode : read/write

<P>
    Type :   Atomic constant <EM>on</EM> or <EM>off</EM>

<P>
    Default :   off

<P>
    Description : If the flag is on, occur check is performed on
        uncompiled unifications and the compiler generates code for
        unifications that will perform the occur check when necessary.
        Note that as ECLiPSe built-ins are compiled with this flag off,
        so the occur check is never performed with built-ins.

<P>
<DT><STRONG>output_mode</STRONG><DD>

<P>
    Access mode : read/write

<P>
    Type : String

<P>
    Default :   \"QPm\"

<P>
    Description : The value is a control string that is recognised by
        the %w format of printf/3.  This format is used to output
        results on the toplevel loop and to print debugger trace lines.
	See also the output_options flag.

<P>
<DT><STRONG>output_options</STRONG><DD>

<P>
    Access mode : read/write

<P>
    Type : List of structures

<P>
    Default :   [depth(20), attributes(pretty), ...]

<P>
    Description : The value is an output options list as understood by
    	write_term/2,3.   This format is used to output results on the
	toplevel loop and to print debugger trace lines.  This flag is
	an alternative, more readable representation of the values of the
	print_depth and output_mode flag.  It reflects the values of those
	flags and will change their values whenever it is changed itself.

<P>
<DT><STRONG>pid</STRONG><DD>

<P>
    Access mode :   read-only

<P>
    Type :   Integer

<P>
    Description :   Returns the process identifier of the current
        ECLiPSe .

<P>
<DT><STRONG>ppid</STRONG><DD>

<P>
    Access mode :   read-only

<P>
    Type :   Integer

<P>
    Description :   Returns the process identifier of the current
        ECLiPSe 's parent process.

<P>
<DT><STRONG>prefer_rationals</STRONG><DD>

<P>
    Access mode :   read/write

<P>
    Type :   Atomic constant <EM>on</EM> or <EM>off</EM>

<P>
    Default :   off

<P>
    Description :   Specifies if the result of a /-division of two
        integers gives a rational or a floating point result.  Similar
        for the result of raising an integer to a negative integral
        power.

<P>
<DT><STRONG>print_depth</STRONG><DD>

<P>
    Access mode :   read/write

<P>
    Type :   Integer

<P>
    Default :   20

<P>
    Description :   Specifies the print depth bound for printing
        compound terms.  It is not taken into account by the output
	predicates that produce machine-readable output (write_canonical,
	writeq, etc), but other I/O built-ins obey this flag.
	Identical to the depth(N) component of the output_options flag.

<P>
<DT><STRONG>prolog_suffix</STRONG><DD>

<P>
    Access mode :   read/write

<P>
    Type :   List of strings

<P>
    Default :   [\"\", \".ecl\", \".pl\"]

<P>
    Description :   Specifies the Prolog source file suffix(es) used
        when compiling files or loading libraries.  The system tries to
        find the file by appending the given suffixes in the order
        provided.

<P>
<DT><STRONG>remote_protocol_version</STRONG><DD>

<P>
    Access mode :   read only

<P>
    Type :   Integer

<P>
    Description :   Specifies the version of the protocol which this
    	Eclipse uses to communicate with remotely attached peers.  See
	Embedding and Interfacing Manual: The Remote Interface Protocol.

<P>
<DT><STRONG>syntax_option</STRONG><DD>

<P>
    Access mode :   read/write

<P>
    Type :   Atom

<P>
    Description :   Returns the names of the currently enabled syntax
        options.  This flag may contain multiple values and will return
        them on backtracking.  A syntax option is reset using
        set_flag(syntax_option, not(Flag)).  Most compatibility
        packages affect these flags as well.  The following options are
        available:

    <DL>
    <DT><EM>atom_subscripts</EM><DD>
	  allow atoms to be followed by subscripts, and parse as subscript/2.
	  Useful for parsing other languages, e.g. FlatZinc.

    <DT><EM>bar_is_no_atom</EM><DD>
	disallow the use of an unquoted vertical bar as atom or functor.

    <DT><EM>based_bignums</EM><DD>
	  Allow base notation even for integers longer than the
	  wordsize (i.e.  they are always positive).

    <DT><EM>blanks_after_sign</EM><DD>
	ignore blank space between a sign and a number (by default,
	this space is significant and will lead to the sign being
	taken as prefix operator rather than the number's sign).

    <DT><EM>blanks_in_nil</EM><DD>
          has no effect (obsolete).

    <DT><EM>curly_args_as_list</EM><DD>
	  Parse terms written as {a,b,c} as {}([a,b,c]) instead of
	  the default {}((a,b,c)).

    <DT><EM>doubled_quote_is_quote</EM><DD>
	  parse a pair of quotes within a quoted item as one
	  occurrence of the quote within the item.  If this option is
	  off (the default), consecutive string-quoted and list-quoted
	  items are parsed as a single (concatenated) item, while
	  consecutive quoted atoms are parsed as consecutive atoms.
 
    <DT><EM>general_subscripts</EM><DD>
	  allow atoms, parenthesized subterms and subscripted subterms
	  to be followed by subscripts, and parse as subscript/2.
	  Useful for parsing other languages, e.g. Zinc.

    <DT><EM>iso_base_prefix</EM><DD>
	  allow binary, octal or hexadecimal numbers to be written
	  with 0b, 0o or 0x prefix respectively, and disallow the
	  <CODE>base'number</CODE> notation.

    <DT><EM>iso_escapes</EM><DD>
	  ISO-Prolog compatible escape sequences within strings and atoms.

    <DT><EM>limit_arg_precedence</EM><DD>
	  do not allow terms with a precedence higher than 999 as
	  structure arguments, unless parenthesised.

    <DT><EM>nested_comments</EM><DD>
          allow bracketed comments to be nested.

    <DT><EM>nl_in_quotes</EM><DD>
          allow newlines to occur inside quotes (default).

    <DT><EM>no_array_subscripts</EM><DD>
	  do not allow array subscript syntax for subscript/2.

    <DT><EM>no_attributes</EM><DD>
	disallow the Eclipse specific syntax for variable attributes
	in curly braces.

    <DT><EM>no_blanks</EM><DD>
	  do not allow blanks between functor and opening parenthesis (default).

    <DT><EM>no_curly_arguments</EM><DD>
	disallow the Eclipse specific syntax for structures with
	named arguments in curly braces.

    <DT><EM>read_floats_as_breals</EM><DD>
    	read all floating point numbers as bounded reals rather than as
	floats. The resulting breal is a small interval enclosing the
	true value of the number in decimal notation.

    <DT><EM>var_functor_is_apply</EM><DD>
	allow variables as functors, and parse a term like X(A,B,C)
	as apply(X,[A,B,C]).

    <DT><EM>$VAR</EM><DD>
	  terms of the form '$VAR'(N) are printed in a special way by
	  all the predicates that obey operator declarations (i.e. 
	  write, writeq, print and partly printf).  This is only provided
	  for compatibility packages:  the use of the output options
	  of write_term/2,3 or the format options of printf/2,3 is
	  the preferred way of specifying this behaviour.
     </DL>

<P>
<DT><STRONG>tmp_dir</STRONG><DD>

<P>
    Access mode : read/write

<P>
    Type : String

<P>
    Default : configuration dependent (see Description below)

<P>
    Description : Specifies the temporary directory that ECLiPSe may use
        for storing temporary data files. <TT>Value</TT> should be an
        existing directory (in ECLiPSe's file name syntax) that the user
        can write to (set_flag/2 will fail otherwise). It is also
        recommended that the directory should reside on a local disk where
        the I/O operations are as fast as possible.  <P> By default, this
        directory is taken from the environment variable ECLIPSETMP if it
        exist. Otherwise, it is \"/tmp\" for Unix systems; \"//C/Temp\" for
        Windows. If none of these exist, it is set to the current
        working directory at start up.

<P>
<DT><STRONG>toplevel_module</STRONG><DD>

<P>
    Access mode :   read/write

<P>
    Type :   Atom

<P>
    Default :   eclipse

<P>
    Description :   The name of the current top-level module.  This is
        the caller module for all queries entered in the top-level
        loop.  By default, this is also shown in the top-level prompt.

<P>
<DT><STRONG>unix_time</STRONG><DD>

<P>
    Access mode :   read-only

<P>
    Type :   Integer

<P>
    Description :   Return the time as given by the UNIX time(3)
        function, ie.  seconds since 00:00:00 GMT, Jan 1 1970.

<P>
<DT><STRONG>variable_names</STRONG><DD>

<P>
    Access mode :   read/write

<P>
    Type :   Atomic constant <EM>on</EM>, <EM>off</EM> or <EM>check_singletons</EM>

<P>
    Default :   check_singletons

<P>
    Description :   Controls the ability to retain the source name of
        variables.  This flag affects the reading process only, i.e.
        when a variable is read (or compiled) with the flag set to on,
        it will keep its name even when the flag is switched off later.
        check_singletons is like on but additionally the compiler emits
        warnings about source variables which occur only once in a
        clause and whose name does not start with an underscore.  The
        source variable names are being created during the term input
        if this flag is not off, and then they are kept independently
        of the value of this flag.

<P>
<DT><STRONG>version</STRONG><DD>

<P>
    Access mode :   read-only

<P>
    Type :   Atom

<P>
    Description :   Returns the current version number of ECLiPSe .

<P>
<DT><STRONG>version_as_list</STRONG><DD>

<P>
    Access mode :   read-only

<P>
    Type :   List of integers

<P>
    Description :   Returns a list of integers, starting with your ECLiPSe
    	system's major version number, and ending with its build number.
	Note that this list can be used for lexicographic comparison, e.g.
	[5,3,17] @>= [5,3] or [5,3,17] @>= [5,1,24].

<P>
<DT><STRONG>worker</STRONG><DD>

<P>
    Access mode :   read-only

<P>
    Type :   Integer

<P>
    Description :   In a parallel session it returns a positive number,
        identifying the worker on which the flag inquiry was executed.
        In a sequential session 0 is returned.

<P>
<DT><STRONG>workers</STRONG><DD>

<P>
    Access mode :   read/write

<P>
    Type :   A structure Host:N, where Host is an atom and N integer

<P>
    Description :   In a parallel session it returns a positive number
        for N, which is the number of active workers on a given host
        Host.  If Host is a variable, it is bound to the host name
        where this predicate is executed.

<P>
<DT><STRONG>workerids</STRONG><DD>

<P>
    Access mode :   read-only

<P>
    Type :   A structure Host:ActiveList+AsleepList, where Host is an
        atom and ActiveList and AsleepList are integer lists

<P>
    Description :   In a parallel session it returns the workerid lists
        of of both active and asleep workers on a given host Host.  If
        Host is a variable, it is bound to the host name where this
        predicate is executed.

<P>
<DT><STRONG>wm_window</STRONG><DD>

<P>
    Access mode :   read/write

<P>
    Type :   Atomic constant <EM>on</EM> or <EM>off</EM>

<P>
    Description :   In a parallel session this flag tells if the window
        interface for the worker manager is on or off.
</DL>
<P>
"),
	args:["Flag" : "Atom or Variable.", "Value" : "Prolog term."],
	exceptions:[5 : "Flag is neither an atom nor variable."],
	eg:"
Success:
   [eclipse]: get_flag(gc, X).
   X = on

   yes.
   [eclipse]: get_flag(loaded_library, L).

   L = lists     More? (;)

   L = development_support     More? (;)
   yes.

Error:
   get_flag(1,X).           (Error 5)



",
	see_also:[set_flag / 2, env / 0, errno_id / 1]]).

:- comment((help) / 1, [
	summary:"Prints help information on the specified predicate in PredSpec on the
current output.

",
	amode:(help(+) is semidet),
	desc:html("\
   Prints help information about the specified predicates to the current
   output.  The information displayed is a text version of the reference
   manual.  If only Name is specified, the system looks for all predicates
   that have this atom in their name.  If there are more than one predicate
   matching, a short description for each one is printed, rather than the
   whole page.  For instance, help var prints the short description of
   get_var_info/3, nonvar/1, readvar/3, var/1 and variant/2, whereas help
   dv prints the whole reference manual page for readvar/3.

<P>
   Help information is available for both built-ins (those predicates
   defined in eclipse_language) and library predicates. If a particular
   predicate is available in more than one library, the user can specify
   Module:Name/Arity for PredSpec where Module is the name of the library 
   to select a specific predicate description. If a predicate is available
   both as a built-in and library predicate(s), then the built-in will be
   printed in full, while short descriptions are given for the library
   predicates.
<P>
   In addition, if information on library is available, help
   lib(LibraryName) can be used to obtain this information.

"),
	args:["PredSpec" : "Predicate/Library specification in form Name/Arity or Module:Name/Arity, lib(Name), or an atom Name"],
	fail_if:"Fails if no help is available for PredSpec",
	eg:"
Success:
      help(nl/0).         % Displays reference page on nl/0

      help(write/X).      % Displays short description of
  % write/1 and write/2

      help(fd:(::)/2).    % Displays the reference page for fd's ::/2.

      help((=:=)/2).      % Displays reference page for the built-in =:=/2,
  % and short description of the other instances of =:=/2.

      help(lib(eplex)).   % Displays the reference page for the library eplex.
      help(X).            % Displays short description of
  % all built-ins

Fail:
      help(nobip/1).




",
	see_also:[current_built_in / 1]]).

:- comment(pred / 1, [
	summary:"The flags of the predicate described by PredSpec are printed out on the
current output.

",
	amode:(pred(++) is semidet),
	desc:html("   Used to print on the current output the flags of the visible predicate
   described by PredSpec.  For the description of the flags see get_flag/3.

<P>
"),
	args:["PredSpec" : "Predicate name in the form Atom/Integer"],
	fail_if:"Fails if PredSpec does not exist",
	exceptions:[4 : "PredSpec is not instantiated", 5 : "PredSpec is not in the format Atom/Integer"],
	eg:"
    ?- pred(pred/1).
    mode                pred(?)
    visibility          imported
    definition_module   sepia_kernel
    declared            on
    defined             on
    autoload            off
    auxiliary           off
    call_type           prolog
    demon               off
    deprecated          off
    parallel            off
    priority            2
    stability           static
    tool                on
    type                built_in
    debugged            on
    leash               notrace
    skip                on
    spy                 off
    start_tracing       off
    Yes (0.01s cpu)

    ?- pred(nopred/1).
    No (0.00s cpu)
",
	see_also:[get_flag / 3, set_flag/3, current_built_in / 1]]).

:- comment(set_flag / 2, [
	summary:"Succeeds if the flag Flag is successfully set to the value Value.

",
	amode:(set_flag(+,++) is det),
	desc:html("   Used to set the environment flag Flag to the value Value.  The current
   value of a flag may be returned using get_flag/2.  Refer to the
   specification of get_flag/2 for details about each of the environment
   flags.

<P>
"),
	args:["Flag" : "Atom.", "Value" : "Atomic or compound term."],
	exceptions:[4 : "Flag and/or Value are not instantiated.", 5 : "Flag is neither an atom nor a variable.", 5 : "Value is not of the expected type.", 6 : "Flag and/or Value are out of range.", 30 : "Flag is a read-only flag."],
	eg:"
Success:
   set_flag(gc,verbose).
   set_flag(syntax_option, no_blanks).
   set_flag(syntax_option, not nl_in_quotes).


   % The following example will set a new library path

   [eclipse]: get_flag(library_path,Path),
      set_flag(library_path, [\"/home/myuser/mylibs\" | Path]).

   Path = [\"/usr/local/ECLIPSE/lib\"]
   yes.

Fail:
   set_flag(statistics, some).

Error:
   set_flag(X,a).                (Error  4)
   set_flag(\"a\",x).              (Error  5)
   set_flag(blah, a).            (Error  6)
   set_flag(gc,fred).            (Error  6)
   set_flag(version,1).          (Error 30)



",
	see_also:[get_flag / 2, env / 0, cd / 1, compile / 1, compile / 2, (dynamic) / 1, pragma / 1, lib / 1]]).

:- comment(statistics / 0, [
	summary:"Prints information about resource usage and garbage collection.

",
	amode:(statistics is det),
	desc:html("   Prints information about resource usage and garbage collection on the
   log_output stream.  This information is also provided by
   statistics/2.  Please refer to statistics/2 for a description of the
   statistic items.  Times are displayed in seconds, memory sizes in bytes.

<P>
"),
	args:[],
	eg:"
[eclipse]: statistics.

times:                  [0.1, 0.34, 264.57] seconds
session_time:           264.6 seconds
global_stack_used:      1096 bytes
global_stack_allocated: 102400 bytes
global_stack_peak:      102400 bytes
trail_stack_used:       44 bytes
trail_stack_allocated:  16384 bytes
trail_stack_peak:       16384 bytes
control_stack_used:     440 bytes
control_stack_allocated:4096 bytes
control_stack_peak:     4096 bytes
local_stack_used:       280 bytes
local_stack_allocated:  4096 bytes
local_stack_peak:       4096 bytes
shared_heap_allocated:  737280 bytes
shared_heap_used:       711760 bytes
private_heap_allocated: 20480 bytes
private_heap_used:      17328 bytes
gc_number:              0
gc_collected:           0 bytes
gc_area:                0 bytes
gc_ratio:               100.0 %
gc_time:                0.0 seconds
dictionary_entries:     2893
dict_hash_usage:        1601 / 8191
dict_hash_collisions:   200 / 1601
dict_gc_number:         0
dict_gc_time:           0.0 seconds

yes.


",
	see_also:[statistics / 2]]).

