<HTML> <HEAD> <!-- Created by texi2html 1.56k + clip patches and <A href="http://www.clip.dia.fi.upm.es/Software">lpdoc</A> from ciao.texi on 28 January 2007 --> <LINK rel="stylesheet" href="ciao.css" type="text/css"> <TITLE>The Ciao Prolog System - Prolog system internal predicates</TITLE> </HEAD> <BODY> Go to the <A HREF="ciao_1.html">first</A>, <A HREF="ciao_52.html">previous</A>, <A HREF="ciao_54.html">next</A>, <A HREF="ciao_241.html">last</A> section, <A HREF="ciao_toc.html">table of contents</A>. <P><HR><P> <H1><A NAME="SEC249" HREF="ciao_toc.html#TOC249">Prolog system internal predicates</A></H1> <P> <A NAME="IDX3504"></A> <P> <STRONG>Author(s):</STRONG> Manuel Carro, Daniel Cabeza, Mats Carlsson. <P> <STRONG>Version:</STRONG> 1.10#7 (2006/4/26, 19:22:13 CEST) <P> <STRONG>Version of last change:</STRONG> 1.9#92 (2003/7/24, 8:4:39 CEST) <P> This module implements some miscellaneous predicates which provide access to some internal statistics, special properties of the predicates, etc. <UL> <LI><A HREF="ciao_53.html#SEC250">Usage and interface (prolog_sys)</A> <LI><A HREF="ciao_53.html#SEC251">Documentation on exports (prolog_sys)</A> <LI><A HREF="ciao_53.html#SEC252">Documentation on internals (prolog_sys)</A> <LI><A HREF="ciao_53.html#SEC253">Known bugs and planned improvements (prolog_sys)</A> </UL> <H2><A NAME="SEC250" HREF="ciao_toc.html#TOC250">Usage and interface (<CODE>prolog_sys</CODE>)</A></H2> <div class="cartouche"> <UL> <LI><STRONG>Library usage:</STRONG> <CODE>:- use_module(library(prolog_sys)).</CODE> <LI><STRONG>Exports:</STRONG> <UL> <LI><EM>Predicates:</EM> <A NAME="IDX3505"></A> <CODE>statistics/0</CODE>, <A NAME="IDX3506"></A> <CODE>statistics/2</CODE>, <A NAME="IDX3507"></A> <CODE>predicate_property/2</CODE>, <A NAME="IDX3508"></A> <CODE>current_atom/1</CODE>, <A NAME="IDX3509"></A> <CODE>garbage_collect/0</CODE>, <A NAME="IDX3510"></A> <CODE>new_atom/1</CODE>. </UL> </UL> </div class="cartouche"> <H2><A NAME="SEC251" HREF="ciao_toc.html#TOC251">Documentation on exports (<CODE>prolog_sys</CODE>)</A></H2> <P> <A NAME="IDX3511"></A> <A NAME="IDX3512"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>statistics/0:</B> <DD><A NAME="IDX3513"></A> <P> <STRONG>Usage:</STRONG> <UL> <LI><EM>Description:</EM> Prints statistics about the system. </UL> </DL> <P> <A NAME="IDX3514"></A> <A NAME="IDX3515"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>statistics/2:</B> <DD><A NAME="IDX3516"></A> <P> <STRONG>Usage 1:</STRONG> <CODE>statistics(Time_option, Time_result)</CODE> <UL> <LI><EM>Description:</EM> Gather information about time (either process time or wall time) since last consult or since start of program. Results are returned in milliseconds. <LI><EM>The following properties should hold at call time:</EM> Options to get information about execution time. <CODE>Time_option</CODE> must be one of <CODE>runtime</CODE>, <CODE>walltime</CODE>. (<CODE>prolog_sys:time_option/1</CODE>) <CODE>Time_result</CODE> is any term. (<CODE>basic_props:term/1</CODE>) <LI><EM>The following properties hold upon exit:</EM> Options to get information about execution time. <CODE>Time_option</CODE> must be one of <CODE>runtime</CODE>, <CODE>walltime</CODE>. (<CODE>prolog_sys:time_option/1</CODE>) <CODE>Time_result</CODE> is a two-element list of integers. The first integer is the time since the start of the execution; the second integer is the time since the previous consult to time. (<CODE>prolog_sys:time_result/1</CODE>) </UL> <P> <STRONG>Usage 2:</STRONG> <CODE>statistics(Memory_option, Memory_result)</CODE> <UL> <LI><EM>Description:</EM> Gather information about memory consumption. <LI><EM>The following properties should hold at call time:</EM> Options to get information about memory usage. (<CODE>prolog_sys:memory_option/1</CODE>) <CODE>Memory_result</CODE> is any term. (<CODE>basic_props:term/1</CODE>) <LI><EM>The following properties hold upon exit:</EM> Options to get information about memory usage. (<CODE>prolog_sys:memory_option/1</CODE>) 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. (<CODE>prolog_sys:memory_result/1</CODE>) </UL> <P> <STRONG>Usage 3:</STRONG> <CODE>statistics(Garbage_collection_option, Gc_result)</CODE> <UL> <LI><EM>Description:</EM> Gather information about garbage collection. <LI><EM>The following properties should hold at call time:</EM> Options to get information about garbage collection. (<CODE>prolog_sys:garbage_collection_option/1</CODE>) <CODE>Gc_result</CODE> is any term. (<CODE>basic_props:term/1</CODE>) <LI><EM>The following properties hold upon exit:</EM> Options to get information about garbage collection. (<CODE>prolog_sys:garbage_collection_option/1</CODE>) <CODE>Gc_result</CODE> is a tree-element list of integers, related to <A NAME="IDX3517"></A> garbage collection and <A NAME="IDX3518"></A> memory management. When <CODE>stack_shifts</CODE> 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 <CODE>garbage_collection</CODE> is selected, the numbers are, respectively, the number of garbage collections performed, the number of bytes freed, and the time spent in garbage collection. (<CODE>prolog_sys:gc_result/1</CODE>) </UL> <P> <STRONG>Usage 4:</STRONG> <CODE>statistics(Symbol_option, Symbol_result)</CODE> <UL> <LI><EM>Description:</EM> Gather information about number of symbols and predicates. <LI><EM>The following properties should hold at call time:</EM> Option to get information about the number of symbols in the program. (<CODE>prolog_sys:symbol_option/1</CODE>) <CODE>Symbol_result</CODE> is any term. (<CODE>basic_props:term/1</CODE>) <LI><EM>The following properties hold upon exit:</EM> Option to get information about the number of symbols in the program. (<CODE>prolog_sys:symbol_option/1</CODE>) <CODE>Symbol_result</CODE> 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). (<CODE>prolog_sys:symbol_result/1</CODE>) </UL> <P> <STRONG>Usage 5:</STRONG> <CODE>statistics(Option, ?term)</CODE> <UL> <LI><EM>Description:</EM> If <CODE>Option</CODE> is unbound, it is bound to the values on the other cases. </UL> </DL> <P> <A NAME="IDX3519"></A> <A NAME="IDX3520"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>predicate_property/2:</B> <DD><A NAME="IDX3521"></A> <P> <STRONG>Usage:</STRONG> <CODE>predicate_property(Head, Property)</CODE> <UL> <LI><EM>Description:</EM> The predicate with clause <CODE>Head</CODE> is <CODE>Property</CODE>. <LI><EM>The following properties should hold at call time:</EM> <CODE>Head</CODE> is any term. (<CODE>basic_props:term/1</CODE>) <CODE>Property</CODE> is any term. (<CODE>basic_props:term/1</CODE>) <LI><EM>The following properties hold upon exit:</EM> <CODE>Head</CODE> is a term which represents a goal, i.e., an atom or a structure. (<CODE>basic_props:callable/1</CODE>) <CODE>Property</CODE> is an atom. (<CODE>basic_props:atm/1</CODE>) </UL> </DL> <P> <A NAME="IDX3522"></A> <A NAME="IDX3523"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>current_atom/1:</B> <DD><A NAME="IDX3524"></A> <P> <STRONG>Usage:</STRONG> <CODE>current_atom(Atom)</CODE> <UL> <LI><EM>Description:</EM> Enumerates on backtracking all the existing atoms in the system. <LI><EM>The following properties should hold at call time:</EM> <CODE>Atom</CODE> is a free variable. (<CODE>term_typing:var/1</CODE>) <LI><EM>The following properties hold upon exit:</EM> <CODE>Atom</CODE> is an atom. (<CODE>basic_props:atm/1</CODE>) </UL> </DL> <P> <A NAME="IDX3525"></A> <A NAME="IDX3526"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>garbage_collect/0:</B> <DD><A NAME="IDX3527"></A> <P> <STRONG>Usage:</STRONG> <UL> <LI><EM>Description:</EM> Forces garbage collection when called. </UL> </DL> <P> <A NAME="IDX3528"></A> <A NAME="IDX3529"></A> <DL> <DT><span class="define">PREDICATE:</span> <B>new_atom/1:</B> <DD><A NAME="IDX3530"></A> <P> <STRONG>Usage:</STRONG> <CODE>new_atom(Atom)</CODE> <UL> <LI><EM>Description:</EM> 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. <LI><EM>The following properties should hold at call time:</EM> <CODE>Atom</CODE> is a free variable. (<CODE>term_typing:var/1</CODE>) <LI><EM>The following properties hold upon exit:</EM> <CODE>Atom</CODE> is an atom. (<CODE>basic_props:atm/1</CODE>) </UL> </DL> <H2><A NAME="SEC252" HREF="ciao_toc.html#TOC252">Documentation on internals (<CODE>prolog_sys</CODE>)</A></H2> <P> <A NAME="IDX3531"></A> <A NAME="IDX3532"></A> <DL> <DT><span class="define">REGTYPE:</span> <B>time_option/1:</B> <DD><A NAME="IDX3533"></A> <P> <STRONG>Usage:</STRONG> <CODE>time_option(M)</CODE> <UL> <LI><EM>Description:</EM> Options to get information about execution time. <CODE>M</CODE> must be one of <CODE>runtime</CODE>, <CODE>walltime</CODE>. </UL> </DL> <P> <A NAME="IDX3534"></A> <A NAME="IDX3535"></A> <DL> <DT><span class="define">REGTYPE:</span> <B>memory_option/1:</B> <DD><A NAME="IDX3536"></A> <P> <STRONG>Usage:</STRONG> <CODE>memory_option(M)</CODE> <UL> <LI><EM>Description:</EM> Options to get information about memory usage. </UL> </DL> <P> <A NAME="IDX3537"></A> <A NAME="IDX3538"></A> <DL> <DT><span class="define">REGTYPE:</span> <B>garbage_collection_option/1:</B> <DD><A NAME="IDX3539"></A> <P> <STRONG>Usage:</STRONG> <CODE>garbage_collection_option(M)</CODE> <UL> <LI><EM>Description:</EM> Options to get information about garbage collection. </UL> </DL> <P> <A NAME="IDX3540"></A> <A NAME="IDX3541"></A> <DL> <DT><span class="define">REGTYPE:</span> <B>symbol_option/1:</B> <DD><A NAME="IDX3542"></A> <P> <STRONG>Usage:</STRONG> <CODE>symbol_option(M)</CODE> <UL> <LI><EM>Description:</EM> Option to get information about the number of symbols in the program. </UL> </DL> <P> <A NAME="IDX3543"></A> <A NAME="IDX3544"></A> <DL> <DT><span class="define">REGTYPE:</span> <B>time_result/1:</B> <DD><A NAME="IDX3545"></A> <P> <STRONG>Usage:</STRONG> <CODE>time_result(Result)</CODE> <UL> <LI><EM>Description:</EM> <CODE>Result</CODE> is a two-element list of integers. The first integer is the time since the start of the execution; the second integer is the time since the previous consult to time. </UL> </DL> <P> <A NAME="IDX3546"></A> <A NAME="IDX3547"></A> <DL> <DT><span class="define">REGTYPE:</span> <B>memory_result/1:</B> <DD><A NAME="IDX3548"></A> <P> <STRONG>Usage:</STRONG> <CODE>memory_result(Result)</CODE> <UL> <LI><EM>Description:</EM> 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. </UL> </DL> <P> <A NAME="IDX3549"></A> <A NAME="IDX3550"></A> <DL> <DT><span class="define">REGTYPE:</span> <B>gc_result/1:</B> <DD><A NAME="IDX3551"></A> <P> <STRONG>Usage:</STRONG> <CODE>gc_result(Result)</CODE> <UL> <LI><EM>Description:</EM> <CODE>Result</CODE> is a tree-element list of integers, related to <A NAME="IDX3552"></A> garbage collection and <A NAME="IDX3553"></A> memory management. When <CODE>stack_shifts</CODE> 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 <CODE>garbage_collection</CODE> is selected, the numbers are, respectively, the number of garbage collections performed, the number of bytes freed, and the time spent in garbage collection. </UL> </DL> <P> <A NAME="IDX3554"></A> <A NAME="IDX3555"></A> <DL> <DT><span class="define">REGTYPE:</span> <B>symbol_result/1:</B> <DD><A NAME="IDX3556"></A> <P> <STRONG>Usage:</STRONG> <CODE>symbol_result(Result)</CODE> <UL> <LI><EM>Description:</EM> <CODE>Result</CODE> 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). </UL> </DL> <H2><A NAME="SEC253" HREF="ciao_toc.html#TOC253">Known bugs and planned improvements (<CODE>prolog_sys</CODE>)</A></H2> <UL> <LI> 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). </UL> <P><HR><P> Go to the <A HREF="ciao_1.html">first</A>, <A HREF="ciao_52.html">previous</A>, <A HREF="ciao_54.html">next</A>, <A HREF="ciao_241.html">last</A> section, <A HREF="ciao_toc.html">table of contents</A>. </BODY> </HTML>
