Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2.2_all bug

NAME

       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.

DATA TYPES

       time() = integer() >= 0

              Time in milliseconds.

       tref()

              A timer reference.

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 = time()
                 Module = module()
                 Function = atom()
                 Arguments = [term()]
                 TRef = tref()
                 Reason = term()

              Evaluates apply(Module, Function, Arguments) after Time amount of time has elapsed.
              Returns {ok, TRef}, or {error, Reason}.

       send_after(Time, Message) -> {ok, TRef} | {error, Reason}

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

              Types:

                 Time = time()
                 Pid = pid() | (RegName :: atom())
                 Message = term()
                 TRef = tref()
                 Reason = term()

                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).

       kill_after(Time) -> {ok, TRef} | {error, Reason2}

       kill_after(Time, Pid) -> {ok, TRef} | {error, Reason2}

       exit_after(Time, Reason1) -> {ok, TRef} | {error, Reason2}

       exit_after(Time, Pid, Reason1) -> {ok, TRef} | {error, Reason2}

              Types:

                 Time = time()
                 Pid = pid() | (RegName :: atom())
                 TRef = tref()
                 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 = time()
                 Module = module()
                 Function = atom()
                 Arguments = [term()]
                 TRef = tref()
                 Reason = term()

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

       send_interval(Time, Message) -> {ok, TRef} | {error, Reason}

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

              Types:

                 Time = time()
                 Pid = pid() | (RegName :: atom())
                 Message = term()
                 TRef = tref()
                 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}

              Types:

                 TRef = tref()
                 Reason = term()

              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 = timeout()

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

       tc(Fun, Arguments) -> {Time, Value}

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

              Types:

                 Module = module()
                 Function = atom()
                 Arguments = [term()]
                 Time = integer()
                   In microseconds
                 Value = term()

                tc/3:
                  Evaluates apply(Module, Function, Arguments) and measures the elapsed real time
                  as reported by os:timestamp/0. Returns {Time, Value}, where Time is the elapsed
                  real time in microseconds, and Value is what is returned from the apply.

                tc/2:
                  Evaluates apply(Fun, Arguments). Otherwise works like tc/3.

                tc/1:
                  Evaluates Fun(). Otherwise works like tc/2.

       now_diff(T2, T1) -> Tdiff

              Types:

                 T1 = T2 = erlang:timestamp()
                 Tdiff = integer()
                   In microseconds

              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

              Types:

                 Seconds = MilliSeconds = integer() >= 0

              Returns the number of milliseconds in Seconds.

       minutes(Minutes) -> MilliSeconds

              Types:

                 Minutes = MilliSeconds = integer() >= 0

              Return the number of milliseconds in Minutes.

       hours(Hours) -> MilliSeconds

              Types:

                 Hours = MilliSeconds = integer() >= 0

              Returns the number of milliseconds in Hours.

       hms(Hours, Minutes, Seconds) -> MilliSeconds

              Types:

                 Hours = Minutes = Seconds = MilliSeconds = integer() >= 0

              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.