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

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) -> Tdiff`

Types:

`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!
          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 Högfeldt - support@erlang.ericsson.se

stdlib 1.14.1
Copyright © 1991-2006 Ericsson AB