timer

MODULE

timer

MODULE SUMMARY

Timer Functions

DESCRIPTION

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. By using cancel/1, the returned reference can be used to cancel any requested action .

The timeouts are not exact, but should be at least as long as requested.

EXPORTS

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)

Types:
Time = integer() in Milliseconds
Module = Function = atom()
Arguments = [term()]

Evaluates apply(M, F, A) after Time amount of time has elapsed. Returns {ok, #Ref}, or {error, Reason}.

send_after(Time, Pid, Message) -> -> {ok, #Ref} | {error,Reason}
send_after(Time, Message) -> -> {ok, #Ref} | {error,Reason}

Types:
Time = integer() in Milliseconds
Pid = pid() | atom()
Message = term()
Result = {ok, #Ref} | {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, #Ref}, or {error, Reason}.


send_after/2

Same as send_after(Time, self(), Message).

exit_after(Time, Pid, Reason1) -> {ok, #Ref} | {error,Reason2}
exit_after(Time, Reason1) -> {ok, #Ref} | {error,Reason2}
kill_after(Time, Pid)-> {ok, #Ref} | {error,Reason2}
kill_after(Time) -> {ok, #Ref} | {error,Reason2}

Types:
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, #Ref}, 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, #Ref} | {error, Reason}

Types:
Time = integer() in milliseconds
Module = Function = atom()
Arguments = [term()]

Evaluates apply(Module, Function, Arguments) repeatedly at intervals of Time. Returns {ok, #Ref}, or {error, Reason}.

send_interval(Time, Pid, Message) -> {ok, #Ref} | {error, Reason}
send_interval(Time, Message) -> {ok, #Ref} | {error, Reason}

Types:
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, #Ref} or {error, Reason}.


send_interval/2

Same as send_interval(Time, self(), Message).

cancel(Ref) -> {ok, cancel} | {error, Reason}

Cancels a previously requested timeout. Ref is a reference returned by the timer function in question. Returns {ok, cancel}, or {error, Reason} when Ref is not a timer reference.

sleep(Time) -> ok

Types:
Time = integer() in milliseconds

Suspends the process calling this function for Time amount of milliseconds and then returns ok. Naturally, this function does not return immediately.

tc(Module, Function, Arguments) -> {Time, Value}

Types:
Module = Function = atom()
Arguments = [term()]
Time = integer() in MICRO-seconds
Value = term()

Evaluates apply(Module, Function, Arguments) and measures the elapsed real time. Returns {Time, Value}, where Time is the elapsed real time in micro seconds, and Value is what is returned from the apply.

seconds(Seconds) -> Milliseconds

Returns the number of milliseconds in Seconds.

minutes(Minutes) -> Milliseconds

Returns 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,#Ref}
Hello World!
2> 
    

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 isn't finished in 10 seconds, kill him
{ok, R} = timer:kill_after(timer:seconds(10), Pid),
...
%% We change our mind...
timer:cancel(R),
...
    

WARNING

Timers are not linked to the requesting processes. A timer requested with apply_after/4 will execute even if the requesting process dies before the timer times out. A timer requested with apply_interval/4 will execute until it is removed with cancel/1 regardless if the requesting process dies. A timer requested with send_interval/3 will stop when it is cancelled by cancel/1 or when the receiving process dies.

AUTHORS

Sebastian Strollo - seb@erix.ericsson.se