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



\section{library(time): Time and alarm library}

\label{sec:time}

The \file{library(time)} provides timing and alarm functions. Alarms are
thread-specific, i.e., creating an alarm causes the alarm goal to be
called in the thread that created it. The predicate \predref{current_alarm}{4} only
reports alarms that are related to the calling thread. If a thread
terminates, all remaining alarms are silently removed. Most applications
use \predref{call_with_time_limit}{2}.\vspace{0.7cm}

\begin{description}
    \predicate[det]{alarm}{3}{+Time, :Callable, -Id}
\nodescription
    \predicate[det]{alarm}{4}{+Time, :Callable, -Id, +Options}
Set up an alarm to be signaled \arg{Time} seconds from now. If the
alarm expires, \arg{Callable} is called asynchronously. \arg{Callable} can
be used to raise an exception using \predref{throw}{1} to abort some
execution.

\arg{Options} is a list of Name(Value) options. Currently defined
options are:

\begin{description}
    \termitem{remove}{Bool}
If \const{true} (default \const{false}), remove the alarm-event (as
\predref{remove_alarm}{1}) after it has been fired.
    \termitem{install}{Bool}
If \const{false} (default \const{true}) do not install the alarm.
It must be installed separately using \predref{install_alarm}{1}.
\end{description}

    \predicate[det]{alarm_at}{3}{+Time, :Callable, -Id}
\nodescription
    \predicate[det]{alarm_at}{4}{+Time, :Callable, -Id, +Options}
As \predref{alarm}{3} and \predref{alarm}{4}, but schedule the alarm at an absolute
point in time.

\begin{tags}
    \tag{See also}
\predref{date_time_stamp}{2}.
\end{tags}

    \predicate[det]{install_alarm}{1}{+Id}
\nodescription
    \predicate[det]{install_alarm}{2}{+Id, +RelTime}
Install an alarm allocated using \predref{alarm}{4} with the \verb$install(false)$
option or de-activated using \predref{uninstall_alarm}{1}. With a given
\arg{RelTime}, the alarm is scheduled at the \arg{RelTime} from now.
Otherwise it is scheduled on the same (absolute) time on which
is was created.

    \predicate[det]{uninstall_alarm}{1}{+Id}
De-activate an alarm. This does \textit{not} invalidate \arg{Id}, but ensures
that the alarm will not fire. The alarm can be rescheduled to
the original time using \predref{install_alarm}{1} or to a new time using
\predref{install_alarm}{2}.

    \predicate[det]{remove_alarm}{1}{+Id}
Remove an alarm. If it has not yet been fired, it never will.

    \predicate[nondet]{current_alarm}{4}{?Time, :Goal, ?Id, ?Status}
Enumerate the alarms in the schedule. \arg{Time} is the absolute time
the event is scheduled for (see also \predref{get_time}{1}). \arg{Goal} is the
goal to execute, \arg{Id} is the identifier and \arg{Status} is the
scheduling status. It takes the value \const{done} if the alarm has
been fired, \const{next} if the event is the next to be executed and
\const{scheduled} otherwise.

    \predicate[det]{call_with_time_limit}{2}{+Time, :Goal}
\nodescription
    \predicate[det]{call_with_time_limit}{3}{+Time, :Goal, +Context}
Call \arg{Goal}, while watching out for a (wall-time) limit. If this limit
is exceeded, the exception \verb$time_limit_exceeded$ is raised.
\predref{call_with_time_limit}{3} throws \verb$time_limit_exceeded(Context)$. \arg{Goal} is
called as in \predref{once}{1}.

\begin{tags}
    \tag{throws}
\verb$time_limit_exceeded$ (\predref{call_with_time_limit}{2}) or
\verb$time_limit_exceeded(Context)$ (\predref{call_with_time_limit}{3}).
\end{tags}
\end{description}