timer(3)

MODULE
timer - 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.

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.

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) -> {ok, Tref} | {error, Reason}

    Types
        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}

    Types
        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}

    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, 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}

    Types
        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}

    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, 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

    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 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) -> {Time, Value}

    Types
        T1 = T2 = {MegaSecs, Secs, MicroSecs}
        MegaSecs = Secs = MicroSecs = integer()

    Calculates the time difference 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!
      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 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.

AUTHORS
 Sebastian Strollo - support@erlang.ericsson.se
 Dan Gudmundsson - support@erlang.ericsson.se
 Peter Hogfeldt - support@erlang.ericsson.se