Runtime system control

Author(s): Manuel Carro, Daniel Cabeza, José F. Morales, Mats Carlsson (original author).

This module implements some predicates which provide internal control and access to the Ciao runtime, like some internal statistics, loaded modules, special properties of the predicates, garbage collection, system flags, etc.

Flags define some global parameters of the system and control the behavior of system or library predicates. Each flag has a name and an associated predefined value, and except some system flags which are fixed, in general their associated value is changeable. Predefined flags in the system are:

version
The Ciao version, as a term ciao(Version,Patch,CommitInfo). Version and Patch are atoms. CommitInfo is a structure describing the commit information (branch, id, date, description). Unchangeable.

dialect
Value set to ciao. Used for compatibility with other systems when in Prolog mode. Unchangeable.

argv
Its value is a list of atoms representing the program arguments supplied when the current executable was invoked. This is the value to which the argument of the main/1 predicate is instantiated at executable startup. Unchangeable.

bounded
It is false, to denote that the range of integers can be considered infinite (but see int/1). Unchangeable. ISO
fileerrors
If on, predicates handling files produce errors (throw exceptions) when a file is non-existent or an operation is not allowed. If off, a failure will occur instead for those conditions. Initially on.

gc
Controls whether garbage collection is performed. May be on (default) or off.

gc_margin
An integer Margin. If less than Margin kilobytes are reclaimed in a garbage collection then the size of the garbage-collected area should be increased. Also, no garbage collection is attempted unless the garbage-collected area has at least Margin kilobytes. Initially 500.

gc_trace
Governs garbage collection trace messages. An element off [on,off,terse,verbose]. Initially off.

integer_rounding_function
It is toward_zero, so that -1 =:= -3//2 succeeds. Unchangeable. ISO
max_arity
It is 255, so that no compound term (or predicate) can have more than this number of arguments. Unchangeable. ISO
quiet
Controls which messages issued using messages_basic are actually written. As the system uses that library to emit its messages, this flag controls the verbosity of the system. Possible states of the flag are:

on
No messages are reported.

error
Only error messages are reported.

warning
Only error and warning messages are reported.

off
All messages are reported, except debug messages. This is the default state.

debug
All messages, including debug messages, are reported. This is only intended for the system implementators.

unknown
Controls action on calls to undefined predicates. The possible states of the flag are:

error
An error is thrown with the error term existence_error(procedure, F/A).

fail
The call simply fails.

warning
A warning is written and the call fails.

The state is initially error. ISO


Documentation on exports

PREDICATEstatistics/0

Usage:

Prints statistics about the system.

    PREDICATEstatistics/2

    Usage 1:statistics(Tick_option,Tick_result)

    Gather information about clock ticks (either run, user, system or wall tick) since last consult or since start of program. A tick is the smallest amount of time that a clock can measure.

    • The following properties should hold at call time:
      (runtime_control:tick_option/1)Options to get information about execution ticks.
      (basic_props:term/1)Tick_result is any term.
    • The following properties should hold upon exit:
      (runtime_control:tick_option/1)Options to get information about execution ticks.
      (runtime_control:tick_result/1)Tick_result is a two-element list of numbers. The first number is the number of ticks since the start of the execution; the second number is the number of ticks since the previous consult to tick.

    Usage 2:statistics(Clockfreq_option,Clockfreq_result)

    Gather information about frequency of the clocks used to measure the ticks (either run-user, system or wall clock). Results are returned in hertz. This value also can be defined as the amount of ticks that a clock can measure in one second.

    Usage 3:statistics(Time_option,Time_result)

    Gather information about time (either process time or wall time) since last consult or since start of program. Results are returned in milliseconds. Note that internally, time is calculated as:

      Time_result = (Tick_result / Clockfreq_result) * 1000
    

    • The following properties should hold at call time:
      (runtime_control:time_option/1)Options to get information about execution time. Time_option must be one of runtime, usertime, systemtime or walltime.
      (basic_props:term/1)Time_result is any term.
    • The following properties should hold upon exit:
      (runtime_control:time_option/1)Options to get information about execution time. Time_option must be one of runtime, usertime, systemtime or walltime.
      (runtime_control:time_result/1)Time_result is a two-element list of numbers. The first number is the time since the start of the execution; the second number is the time since the previous consult to time.

    Usage 4:statistics(Memory_option,Memory_result)

    Gather information about memory consumption.

    • The following properties should hold at call time:
      (runtime_control:memory_option/1)Options to get information about memory usage.
      (basic_props:term/1)Memory_result is any term.
    • The following properties should hold upon exit:
      (runtime_control:memory_option/1)Options to get information about memory usage.
      (runtime_control:memory_result/1)Result is a two-element list of integers. The first element is the space taken up by the option selected, measured in bytes; the second integer is zero for program space (which grows as necessary), and the amount of free space otherwise.

    Usage 5:statistics(Garbage_collection_option,Gc_result)

    Gather information about garbage collection.

    • The following properties should hold at call time:
      (runtime_control:garbage_collection_option/1)Options to get information about garbage collection.
      (basic_props:term/1)Gc_result is any term.
    • The following properties should hold upon exit:
      (runtime_control:garbage_collection_option/1)Options to get information about garbage collection.
      (runtime_control:gc_result/1)Gc_result is a tree-element list of integers, related to garbage collection and memory management. When stack_shifts is selected, the first one is the number of shifts (reallocations) of the local stack; the second is the number of shifts of the trail, and the third is the time spent in these shifts. When garbage_collection is selected, the numbers are, respectively, the number of garbage collections performed, the number of bytes freed, and the time spent in garbage collection.

    Usage 6:statistics(Symbol_option,Symbol_result)

    Gather information about number of symbols and predicates.

    • The following properties should hold at call time:
      (runtime_control:symbol_option/1)Option to get information about the number of symbols in the program.
      (basic_props:term/1)Symbol_result is any term.
    • The following properties should hold upon exit:
      (runtime_control:symbol_option/1)Option to get information about the number of symbols in the program.
      (runtime_control:symbol_result/1)Symbol_result is a two-element list of integers. The first one is the number of atom, functor, and predicate names in the symbol table. The second is the number of predicates known to be defined (although maybe without clauses).

    Usage 7:statistics(Option,Arg2)

    If Option is unbound, it is bound to the values on the other cases.

    Usage:clockfreq_result(Result)

    Result is a number. It gives the frequency in hertz used by the clock get the ticks.

      Usage:tick_result(Result)

      Result is a two-element list of numbers. The first number is the number of ticks since the start of the execution; the second number is the number of ticks since the previous consult to tick.

        Usage:symbol_result(Result)

        Result is a two-element list of integers. The first one is the number of atom, functor, and predicate names in the symbol table. The second is the number of predicates known to be defined (although maybe without clauses).

          Usage:gc_result(Result)

          Result is a tree-element list of integers, related to garbage collection and memory management. When stack_shifts is selected, the first one is the number of shifts (reallocations) of the local stack; the second is the number of shifts of the trail, and the third is the time spent in these shifts. When garbage_collection is selected, the numbers are, respectively, the number of garbage collections performed, the number of bytes freed, and the time spent in garbage collection.

            Usage:memory_result(Result)

            Result is a two-element list of integers. The first element is the space taken up by the option selected, measured in bytes; the second integer is zero for program space (which grows as necessary), and the amount of free space otherwise.

              Usage:time_result(Result)

              Result is a two-element list of numbers. The first number is the time since the start of the execution; the second number is the time since the previous consult to time.

                Usage:symbol_option(M)

                Option to get information about the number of symbols in the program.

                  Usage:garbage_collection_option(M)

                  Options to get information about garbage collection.

                    Usage:memory_option(M)

                    Options to get information about memory usage.

                      Usage:clockfreq_option(M)

                      Options to get information about the frequency of clocks used to get the ticks.

                        Usage:tick_option(M)

                        Options to get information about execution ticks.

                          Usage:time_option(M)

                          Options to get information about execution time. M must be one of runtime, usertime, systemtime or walltime.

                            Usage:current_atom(Atom)

                            Enumerates on backtracking all the existing atoms in the system.

                            PREDICATEnew_atom/1

                            Usage:new_atom(Atom)

                            Returns, on success, a new atom, not existing before in the system. The entry argument must be a variable. The idea behind this atom generation is to provide a fast source of identifiers for new objects, concurrent predicates, etc. on the fly.

                            • The following properties should hold at call time:
                              (term_typing:var/1)Atom is a free variable.
                            • The following properties hold upon exit:
                              (basic_props:atm/1)Atom is an atom.

                            This predicate will successively unify its argument with all module names currently loaded. Module names will be simple atoms.

                            When called using a free variable as argument, it will retrieve on backtracking all modules currently loaded. This is useful when called from the Ciao toplevel.

                            When called using a module name as argument it will check whether the given module is loaded or not. This is useful when called from user programs.

                            Usage:current_module(Module)

                            Retrieves (on backtracking) all the loaded modules (either statically or dynamically).

                            No further documentation available for this predicate.

                            Usage:predicate_property(Head,Property)

                            The predicate Head, visible from the current module, (a goal) has the property Property.

                            No further documentation available for this predicate.

                            Usage:

                            Forces garbage collection when called.

                              set_prolog_flag(FlagName,Value)

                              Set existing flag FlagName to Value.

                              Usage:ISO

                              current_prolog_flag(FlagName,Value)

                              FlagName is an existing flag and Value is the value currently associated with it.

                              Usage:

                              PREDICATEprolog_flag/3
                              prolog_flag(FlagName,OldValue,NewValue)

                              FlagName is an existing flag, unify OldValue with the value associated with it, and set it to new value NewValue.

                              Usage 1:prolog_flag(A,B,C)

                              Usage 2:prolog_flag(FlagName,OldValue,NewValue)

                              Same as current_prolog_flag(FlagName, OldValue). OldValue and NewValue must be strictly identical variables.

                              push_prolog_flag(Flag,NewValue)

                              Same as set_prolog_flag/2, but storing current value of Flag to restore it with pop_prolog_flag/1.

                              Usage:

                              pop_prolog_flag(Flag)

                              Restore the value of Flag previous to the last non-canceled push_prolog_flag/2 on it.

                              Usage:

                              • The following properties should hold at call time:
                                (basic_props:atm/1)Flag is an atom.
                              • The following properties should hold upon exit:
                                (basic_props:atm/1)Flag is an atom.

                              PREDICATEprompt/2
                              prompt(Old,New)

                              Unify Old with the current prompt for reading, change it to New.

                              Usage 1:prompt(A,B)

                              Usage 2:prompt(Old,New)

                              Unify Old with the current prompt for reading without changing it. On calls, Old and New must be strictly identical variables.

                              PREDICATEgc/0

                              Usage:

                              Enable garbage collection. Equivalent to set_prolog_flag(gc, on)

                              • The following properties should hold globally:
                                (basic_props:equiv/2)gc is equivalent to set_prolog_flag(gc,on).

                              PREDICATEnogc/0

                              Usage:

                              Disable garbage collection. Equivalent to set_prolog_flag(gc, off)

                              • The following properties should hold globally:
                                (basic_props:equiv/2)nogc is equivalent to set_prolog_flag(gc,off).

                              PREDICATEfileerrors/0

                              Usage:

                              Enable reporting of file errors. Equivalent to set_prolog_flag(fileerrors, on)

                              • The following properties should hold globally:
                                (basic_props:equiv/2)fileerrors is equivalent to set_prolog_flag(fileerrors,on).

                              Usage:

                              Disable reporting of file errors. Equivalent to set_prolog_flag(fileerrors, off)

                              • The following properties should hold globally:
                                (basic_props:equiv/2)nofileerrors is equivalent to set_prolog_flag(fileerrors,off).

                              Documentation on multifiles

                              PREDICATEdefine_flag/3
                              define_flag(Flag,Values,Default)

                              New flags can be defined by writing facts of this predicate. Flag is the name of the new flag, Values defines the posible values for the flag (see below) and Default defines the predefined value associated with the flag (which should be compatible with Values).

                              Usage:define_flag(Flag,FlagValues,Default)

                              The predicate is multifile.

                              Documentation on internals

                              No further documentation available for this predicate.

                              Documentation on imports

                              This module has the following direct dependencies:

                              Known bugs and planned improvements

                              • The space used by the process is not measured here: process data, code, and stack also take up memory. The memory reported for atoms is not what is actually used, but the space used up by the hash table (which is enlarged as needed).
                              • The predicate predicate_property/2 needs more work:

                                  Efficiency:
                                  In order to be complete and efficient, this needs to be a built-in predicate of our module system. Consulting predicate properties does not seem a dangerous operation (except that, when it cannot be resolved at compile-time, it prevents removal of module runtime information).

                                  Correctness:
                                  The head is automatically module-expanded on call. If the head is not module-expanded, there are consistency problems. Other systems avoid those problems by disallowing the import of two predicates with the same name from different modules. That is clearly not a solution in Ciao.

                              • Implement a '$predicate_property'/2 where the module can be specified. That will simplify the predicate_property/2 implementation