17 library(time): Time and alarm library

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.

[det]alarm(+Time, :Callable, -Id)

[det]alarm(+Time, :Callable, -Id, +Options)

Set up an alarm to be signaled Time seconds from now. If the alarm expires, Callable is called asynchronously. Callable can be used to raise an exception using throw/1 to abort some execution.

Options is a list of Name(Value) options. Currently defined options are:

remove(Bool)

If true (default false), remove the alarm-event (as remove_alarm/1) after it has been fired. Id remains valid, i.e., it is safe to call remove_alarm/1 on Id regardless of whether or not the alarm has fired.

install(Bool)

If false (default true) do not install the alarm. It must be installed separately using install_alarm/1.

[det]alarm_at(+Time, :Callable, -Id)

[det]alarm_at(+Time, :Callable, -Id, +Options)

As alarm/3 and alarm/4, but schedule the alarm at an absolute point in time.

See also

date_time_stamp/2.

[det]install_alarm(+Id)

[det]install_alarm(+Id, +RelTime)

Install an alarm allocated using alarm/4 with the install(false) option or de-activated using uninstall_alarm/1. With a given RelTime, the alarm is scheduled at the RelTime from now. Otherwise it is scheduled on the same (absolute) time on which is was created.

Errors

existence_error(alarm, Id) if the alarm has been removed.

[det]uninstall_alarm(+Id)

De-activate an alarm. This does not invalidate Id, but ensures that the alarm will not fire. The alarm can be rescheduled to the original time using install_alarm/1 or to a new time using install_alarm/2.

Errors

existence_error(alarm, Id) if the alarm has been removed.

[det]remove_alarm(+Id)

Remove an alarm. If it has not yet been fired, it never will. Succeeds silently if the alarm was already removed, either by remove_alarm/1 or due to the remove(true) option of alarm/4.

[nondet]current_alarm(?Time, :Goal, ?Id, ?Status)

Enumerate the alarms in the schedule. Time is the absolute time the event is scheduled for (see also get_time/1). Goal is the goal to execute, Id is the identifier and Status is the scheduling status. It takes the value done if the alarm has been fired, next if the event is the next to be executed and scheduled otherwise.

[det]call_with_time_limit(+Time, :Goal)

[det]call_with_time_limit(+Time, :Goal, +Context)

Call Goal, while watching out for a (wall-time) limit. If this limit is exceeded, the exception time_limit_exceeded is raised. call_with_time_limit/3 throws time_limit_exceeded(Context). Goal is called as in once/1.

throws

time_limit_exceeded (call_with_time_limit/2) or time_limit_exceeded(Context) (call_with_time_limit/3).