16 Time and alarm library

This library is not available if SWI-Prolog is compiled without support for multiple threads.

The 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 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 call_with_time_limit/2.

alarm(+Time, :Callable, -Id, +Options)

Schedule Callable to be called Time seconds from now. Time is a number (integer or float). Callable is called on the next pass through a call- or redo-port of the Prolog engine, or a call to the PL_handle_signals() routine from SWI-Prolog. Id is unified with a reference to the timer.

The resolution of the alarm depends on the underlying implementation, which is based on pthread_cond_timedwait() (on Windows on the pthread emulation thereof). Long-running foreign predicates that do not call PL_handle_signals() may further delay the alarm. The relation to blocking system calls (sleep, reading from slow devices, etc.) is undefined and varies between implementations.

Options is a list of Name(Value) terms. Defined options are:

remove(Bool)

If true (default false), the timer is removed automatically after fireing. Otherwise it must be destroyed explicitly using remove_alarm/1.

install(Bool)

If false (default true), the timer is allocated but not scheduled for execution. It must be started later using install_alarm/1.

alarm(+Time, :Callable, -Id)

Same as alarm(Time, Callable, Id,[]).

alarm_at(+Time, :Callable, -Id, +Options)

as alarm/3, but Time is the specification of an absolute point in time. Absolute times are specified in seconds after the Jan 1, 1970 epoch. See also date_time_stamp/2.

install_alarm(+Id)

Activate an alarm allocated using alarm/4 with the option install(false) or stopped using uninstall_alarm/1.

install_alarm(+Id, +Time)

As install_alarm/1, but specifies a new (relative) timeout value.

uninstall_alarm(+Id)

Deactivate a running alarm, but do not invalidate the alarm identifier. Later, the alarm can be reactivated using either install_alarm/1 or install_alarm/2. Reinstalled using install_alarm/1, it will fire at the originally scheduled time. Reinstalled using install_alarm/2 causes the alarm to fire at the specified time from now.

remove_alarm(+Id)

Remove an alarm. If it is not yet fired, it will not be fired any more.

current_alarm(?At, ?:Callable, ?Id, ?Status)

Enumerate the not-yet-removed alarms. Status is one of done if the alarm has been called, next if it is the next to be fired and scheduled otherwise.

call_with_time_limit(+Time, :Goal)

True if Goal completes within Time seconds. Goal is executed as in once/1. If Goal doesn't complete within Time seconds (wall time), exit using the exception time_limit_exceeded. See catch/3.

Please note that this predicate uses alarm/4 and therefore its effect on long-running foreign code and system calls is undefined. Blocking I/O can be handled using the timeout option of set_stream/2 or waiting for input using wait_for_input/3.