19962009 Ericsson AB. All Rights Reserved. The contents of this file are subject to the Erlang Public License, Version 1.1, (the "License"); you may not use this file except in compliance with the License. You should have received a copy of the Erlang Public License along with this software. If not, it can be retrieved online at http://www.erlang.org/. Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License. timer Sebastian Strollo Bjarne Däcker 1 Bjarne Däcker 1998-09-09 D timer.sgml
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.

start() -> ok Start a global timer server (named timer_server).

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} Apply Module:Function(Arguments)after a specified Time. 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} Send Messageto Pidafter a specified Time. Time = integer() in Milliseconds Pid = pid() | atom() Message = term() Result = {ok, TRef} | {error, Reason}

send_after/3

Evaluates Pid ! Message after Time 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} Send an exit signal with Reasonafter a specified Time. Time = integer() in milliseconds Pid = pid() | atom() Reason1 = Reason2 = term()

exit_after/3

Send an exit signal with reason Reason1 to Pid Pid. 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} Evaluate Module:Function(Arguments)repeatedly at intervals of Time. 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} Send Messagerepeatedly at intervals of Time. Time = integer() in milliseconds Pid = pid() | atom() Message = term() Reason = term()

send_interval/3

Evaluates Pid ! Message repeatedly after Time 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} Cancel a previously requested timeout identified by TRef.

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 Suspend the calling process for Timeamount of milliseconds. 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} Measure the real time it takes to evaluate apply(Module, Function, Arguments) Module = Function = atom() Arguments = [term()] Time = integer() in microseconds Value = term()

Evaluates apply(Module, Function, Arguments) and measures the elapsed real time as reported by now/0. 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 Calculate time difference between now/0timestamps 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 Convert Secondsto Milliseconds.

Returns the number of milliseconds in Seconds.

 minutes(Minutes) -> Milliseconds Converts Minutesto Milliseconds.

Return the number of milliseconds in Minutes.

 hours(Hours) -> Milliseconds Convert Hoursto Milliseconds.

Returns the number of milliseconds in Hours.

 hms(Hours, Minutes, Seconds) -> Milliseconds Convert Hours+Minutes+Secondsto 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.