timer
Timer Functions
This module provides useful functions related to time. Unless otherwise
stated, time is always measured in milliseconds
. All
timer functions return immediately, regardless of work carried
out by another process.
Successful evaluations of the timer functions yield return values
containing a timer reference, denoted TRef
below. By using
cancel/1
, the returned reference can be used to cancel any
requested action. A TRef
is an Erlang term, the contents
of which must not be altered.
The timeouts are not exact, but should be at least
as long
as requested.
Functions
start() -> ok
Starts the timer server. Normally, the server does not need
to be started explicitly. It is started dynamically if it
is needed. This is useful during development, but in a
target system the server should be started explicitly. Use
configuration parameters for kernel
for this.
apply_after(Time, Module, Function, Arguments) -> {ok, Tref} | {error, Reason}
Time = integer() in Milliseconds
Module = Function = atom()
Arguments = [term()]
Evaluates apply(M, F, A)
after Time
amount of time
has elapsed. Returns {ok, TRef}
, or {error, Reason}
.
send_after(Time, Pid, Message) -> {ok, TRef} | {error,Reason}
send_after(Time, Message) -> {ok, TRef} | {error,Reason}
Time = integer() in Milliseconds
Pid = pid() | atom()
Message = term()
Result = {ok, TRef} | {error, Reason}
send_after/3
-
Evaluates
Pid ! Message
afterTime
amount of time has elapsed. (Pid
can also be an atom of a registered name.) Returns{ok, TRef}
, or{error, Reason}
. send_after/2
-
Same as
send_after(Time, self(), Message)
.
exit_after(Time, Pid, Reason1) -> {ok, TRef} | {error,Reason2}
exit_after(Time, Reason1) -> {ok, TRef} | {error,Reason2}
kill_after(Time, Pid)-> {ok, TRef} | {error,Reason2}
kill_after(Time) -> {ok, TRef} | {error,Reason2}
Time = integer() in milliseconds
Pid = pid() | atom()
Reason1 = Reason2 = term()
exit_after/3
-
Send an exit signal with reason
Reason1
to PidPid
. Returns{ok, TRef}
, or{error, Reason2}
. exit_after/2
-
Same as
exit_after(Time, self(), Reason1)
. kill_after/2
-
Same as
exit_after(Time, Pid, kill)
. kill_after/1
-
Same as
exit_after(Time, self(), kill)
.
apply_interval(Time, Module, Function, Arguments) -> {ok, TRef} | {error, Reason}
Time = integer() in milliseconds
Module = Function = atom()
Arguments = [term()]
Evaluates apply(Module, Function, Arguments)
repeatedly at
intervals of Time
. Returns {ok, TRef}
, or
{error, Reason}
.
send_interval(Time, Pid, Message) -> {ok, TRef} | {error, Reason}
send_interval(Time, Message) -> {ok, TRef} | {error, Reason}
Time = integer() in milliseconds
Pid = pid() | atom()
Message = term()
Reason = term()
send_interval/3
-
Evaluates
Pid ! Message
repeatedly afterTime
amount of time has elapsed. (Pid
can also be an atom of a registered name.) Returns{ok, TRef}
or{error, Reason}
. send_interval/2
-
Same as
send_interval(Time, self(), Message)
.
cancel(TRef) -> {ok, cancel} | {error, Reason}
Cancels a previously requested timeout. TRef
is a unique
timer reference returned by the timer function in question. Returns
{ok, cancel}
, or {error, Reason}
when TRef
is not a timer reference.
sleep(Time) -> ok
Time = integer() in milliseconds or the atom infinity
Suspends the process calling this function for Time
amount
of milliseconds and then returns ok
, or suspend the process
forever if Time
is the atom infinity
. Naturally, this
function does not return immediately.
tc(Module, Function, Arguments) -> {Time, Value}
Module = Function = atom()
Arguments = [term()]
Time = integer() in microseconds
Value = term()
Evaluates apply(Module, Function, Arguments)
and measures
the elapsed real time. Returns {Time, Value}
, where
Time
is the elapsed real time in microseconds,
and Value
is what is returned from the apply.
now_diff(T2, T1) -> Tdiff
T1 = T2 = {MegaSecs, Secs, MicroSecs}
Tdiff = MegaSecs = Secs = MicroSecs = integer()
Calculates the time difference Tdiff = T2 - T1
in
microseconds, where T1
and T2
probably
are timestamp tuples returned from erlang:now/0
.
seconds(Seconds) -> Milliseconds
Returns the number of milliseconds in Seconds
.
minutes(Minutes) -> Milliseconds
Return the number of milliseconds in Minutes
.
hours(Hours) -> Milliseconds
Returns the number of milliseconds in Hours
.
hms(Hours, Minutes, Seconds) -> Milliseconds
Returns the number of milliseconds in Hours + Minutes + Seconds
.
Examples
This example illustrates how to print out "Hello World!" in 5 seconds:
1> timer:apply_after(5000, io, format, ["~nHello World!~n", []]).
{ok,TRef}
Hello World!
The following coding example illustrates a process which performs a certain action and if this action is not completed within a certain limit, then the process is killed.
Pid = spawn(mod, fun, [foo, bar]), %% If pid is not finished in 10 seconds, kill him {ok, R} = timer:kill_after(timer:seconds(10), Pid), ... %% We change our mind... timer:cancel(R), ...
WARNING
A timer can always be removed by calling cancel/1
.
An interval timer, i.e. a timer created by evaluating any of the
functions apply_interval/4
, send_interval/3
, and
send_interval/2
, is linked to the process towards which
the timer performs its task.
A one-shot timer, i.e. a timer created by evaluating any of the
functions apply_after/4
, send_after/3
,
send_after/2
, exit_after/3
, exit_after/2
,
kill_after/2
, and kill_after/1
is not linked to any
process. Hence, such a timer is removed only when it reaches its
timeout, or if it is explicitly removed by a call to cancel/1
.