% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\section{library(statistics): Get information about resource usage}

\label{sec:statistics}

This library provides predicates to obtain information about resource
usage by your program. The predicates of this library are for human use
at the toplevel: information is \textit{printed}. All predicates obtain their
information using public low-level primitives. These primitives can be
use to obtain selective statistics during execution.\vspace{0.7cm}

\begin{description}
    \predicate[det]{statistics}{0}{}
Print information about resource usage using \predref{print_message}{2}.

\begin{tags}
    \tag{See also}
All statistics printed are obtained through \predref{statistics}{2}.
\end{tags}

    \predicate[det]{statistics}{1}{-Stats:dict}
\arg{Stats} is a dict representing the same information as
\predref{statistics}{0}. This convience function is primarily intended to
pass statistical information to e.g., a web client. Time
critical code that wishes to collect statistics typically only
need a small subset and should use \predref{statistics}{2} to obtain
exactly the data they need.

    \predicate[nondet]{thread_statistics}{2}{?Thread, -Stats:dict}
Obtain statistical information about a single thread. Fails
silently of the \arg{Thread} is no longer alive.

\begin{arguments}
\arg{Stats} & is a dict containing status, time and stack-size
information about \arg{Thread}. \\
\end{arguments}

    \predicate[nondet]{time}{1}{:Goal}
Execute \arg{Goal}, reporting statistics to the user. If \arg{Goal} succeeds
non-deterministically, retrying reports the statistics for
providing the next answer.

Statistics are retrieved using \predref{thread_statistics}{3} on the
calling thread. Note that not all systems support
thread-specific CPU time. Notable, this is lacking on MacOS X.

\begin{tags}
\mtag{See also}- \predref{statistics}{2} for obtaining statistics in your program and
understanding the reported values. \\- \predref{call_time}{2}, \predref{call_time}{3} to obtain the timing in a dict.
    \tag{bug}
Inference statistics are often a few off.
\end{tags}

    \predicate{call_time}{2}{:Goal, -Time:dict}
\nodescription
    \predicate{call_time}{3}{:Goal, -Time:dict, -Result}
Call \arg{Goal} as \predref{call}{1}, unifying \arg{Time} with a dict that provides
information on the resource usage. If \arg{Goal} succeeds with a choice
point, backtracking reports the time used to find the \textit{next answer},
failure or exception. If \arg{Goal} succeeds deterministically no choice
point is left open. Currently \arg{Time} contains the keys below. Future
versions may provide additional keys.

\begin{shortlist}
    \item wall:Seconds
    \item cpu:Seconds
    \item inferences:Count
\end{shortlist}

\predref{call_time}{2} is defined as below. Note that for \predref{call_time}{2} the time
is only available if \arg{Goal} succeeds.

\begin{code}
call_time(Goal, Time) :-
    call_time(Goal, Time, Result),
    call(Result).
\end{code}

\begin{arguments}
\arg{Result} & is one of \const{true}, \const{false} or \verb$throw(E)$, depending on
whether or not the goal succeeded or raised an exception. Note that
\arg{Result} may be called using \predref{call}{1} to propagate the failure or
exception. \\
\end{arguments}
\end{description}