Prolog system internal predicates

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

This module implements some miscellaneous predicates which provide access to some internal statistics, special properties of the predicates, etc.

Documentation on exports

PREDICATE

Usage:

  • Description: Prints statistics about the system.

PREDICATE

Usage 1: statistics(Tick_option,Tick_result)

  • Description: 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:
    (prolog_sys: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:
    (prolog_sys:tick_option/1)Options to get information about execution ticks.
    (prolog_sys: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)

  • Description: 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.
  • The following properties should hold at call time:
    (prolog_sys:clockfreq_option/1)Options to get information about the frequency of clocks used to get the ticks.
    (basic_props:term/1)Clockfreq_result is any term.
  • The following properties should hold upon exit:
    (prolog_sys:clockfreq_option/1)Options to get information about the frequency of clocks used to get the ticks.
    (prolog_sys:clockfreq_result/1)Clockfreq_result is a number. It gives the frequency in hertz used by the clock get the ticks.

Usage 3: statistics(Time_option,Time_result)

  • Description: 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:
    (prolog_sys: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:
    (prolog_sys:time_option/1)Options to get information about execution time. Time_option must be one of runtime, usertime, systemtime or walltime.
    (prolog_sys: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)

  • Description: Gather information about memory consumption.
  • The following properties should hold at call time:
    (prolog_sys: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:
    (prolog_sys:memory_option/1)Options to get information about memory usage.
    (prolog_sys: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)

  • Description: Gather information about garbage collection.
  • The following properties should hold at call time:
    (prolog_sys: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:
    (prolog_sys:garbage_collection_option/1)Options to get information about garbage collection.
    (prolog_sys: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)

  • Description: Gather information about number of symbols and predicates.
  • The following properties should hold at call time:
    (prolog_sys: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:
    (prolog_sys:symbol_option/1)Option to get information about the number of symbols in the program.
    (prolog_sys: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)

  • Description: If Option is unbound, it is bound to the values on the other cases.
  • Call and exit should be compatible with:
    (basic_props:term/1)Arg2 is any term.
  • The following properties should hold upon exit:
    (basic_props:term/1)Arg2 is any term.

REGTYPE

Usage: clockfreq_result(Result)

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

REGTYPE

Usage: tick_result(Result)

  • Description: 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.

PREDICATE

Usage: new_atom(Atom)

  • Description: 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.

REGTYPE

Usage: symbol_result(Result)

  • Description: 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).

REGTYPE

Usage: gc_result(Result)

  • Description: 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.

REGTYPE

Usage: memory_result(Result)

  • Description: 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.

REGTYPE

Usage: time_result(Result)

  • Description: 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.

REGTYPE

Usage: symbol_option(M)

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

REGTYPE

Usage: garbage_collection_option(M)

  • Description: Options to get information about garbage collection.

REGTYPE

Usage: memory_option(M)

  • Description: Options to get information about memory usage.

REGTYPE

Usage: clockfreq_option(M)

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

REGTYPE

Usage: tick_option(M)

  • Description: Options to get information about execution ticks.

REGTYPE

Usage: time_option(M)

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

PREDICATE

General properties: predicate_property(Head,Prop)
  • Description: Predicate property of true/0 is compiled
  • If the following properties should hold at call time:
    (term_basic:= /2)term_basic:Head=true then the following properties should hold upon exit:
    (term_basic:= /2)term_basic:Prop=compiled

Usage: predicate_property(Head,Property)

  • Description: The predicate Head, visible from the current module, (a goal) has the property Property.
  • The following properties should hold upon exit:
    (basic_props:callable/1)Head is a term which represents a goal, i.e., an atom or a structure.
    (basic_props:atm/1)Property is an atom.

PREDICATE
No further documentation available for this predicate.

PREDICATE

Usage: current_atom(Atom)

  • Description: Enumerates on backtracking all the existing atoms in the system.
  • The following properties hold upon exit:
    (basic_props:atm/1)Atom is an atom.

PREDICATE

Usage:

  • Description: Forces garbage collection when called.

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