1timer(3)                   Erlang Module Definition                   timer(3)
2
3
4

NAME

6       timer - Timer functions.
7

DESCRIPTION

9       This module provides useful functions related to time. Unless otherwise
10       stated, time is always measured in milliseconds.  All  timer  functions
11       return immediately, regardless of work done by another process.
12
13       Successful  evaluations  of the timer functions give return values con‐
14       taining a  timer  reference,  denoted  TRef.  By  using  cancel/1,  the
15       returned  reference  can be used to cancel any requested action. A TRef
16       is an Erlang term, which contents must not be changed.
17
18       The time-outs are not exact, but are at least as long as requested.
19

DATA TYPES

21       time() = integer() >= 0
22
23              Time in milliseconds.
24
25       tref()
26
27              A timer reference.
28

EXPORTS

30       apply_after(Time, Module, Function, Arguments) ->
31                      {ok, TRef} | {error, Reason}
32
33              Types:
34
35                 Time = time()
36                 Module = module()
37                 Function = atom()
38                 Arguments = [term()]
39                 TRef = tref()
40                 Reason = term()
41
42              Evaluates apply(Module, Function,  Arguments)  after  Time  mil‐
43              liseconds.
44
45              Returns {ok, TRef} or {error, Reason}.
46
47       apply_interval(Time, Module, Function, Arguments) ->
48                         {ok, TRef} | {error, Reason}
49
50              Types:
51
52                 Time = time()
53                 Module = module()
54                 Function = atom()
55                 Arguments = [term()]
56                 TRef = tref()
57                 Reason = term()
58
59              Evaluates   apply(Module,  Function,  Arguments)  repeatedly  at
60              intervals of Time.
61
62              Returns {ok, TRef} or {error, Reason}.
63
64       cancel(TRef) -> {ok, cancel} | {error, Reason}
65
66              Types:
67
68                 TRef = tref()
69                 Reason = term()
70
71              Cancels a previously requested time-out. TRef is a unique  timer
72              reference returned by the related timer function.
73
74              Returns  {ok,  cancel},  or  {error,  Reason} when TRef is not a
75              timer reference.
76
77       exit_after(Time, Reason1) -> {ok, TRef} | {error, Reason2}
78
79       exit_after(Time, Pid, Reason1) -> {ok, TRef} | {error, Reason2}
80
81              Types:
82
83                 Time = time()
84                 Pid = pid() | (RegName :: atom())
85                 TRef = tref()
86                 Reason1 = Reason2 = term()
87
88              exit_after/2 is the same as exit_after(Time, self(), Reason1).
89
90              exit_after/3 sends an exit signal with  reason  Reason1  to  pid
91              Pid. Returns {ok, TRef} or {error, Reason2}.
92
93       hms(Hours, Minutes, Seconds) -> MilliSeconds
94
95              Types:
96
97                 Hours = Minutes = Seconds = MilliSeconds = integer() >= 0
98
99              Returns the number of milliseconds in Hours + Minutes + Seconds.
100
101       hours(Hours) -> MilliSeconds
102
103              Types:
104
105                 Hours = MilliSeconds = integer() >= 0
106
107              Returns the number of milliseconds in Hours.
108
109       kill_after(Time) -> {ok, TRef} | {error, Reason2}
110
111       kill_after(Time, Pid) -> {ok, TRef} | {error, Reason2}
112
113              Types:
114
115                 Time = time()
116                 Pid = pid() | (RegName :: atom())
117                 TRef = tref()
118                 Reason2 = term()
119
120              kill_after/1 is the same as exit_after(Time, self(), kill).
121
122              kill_after/2 is the same as exit_after(Time, Pid, kill).
123
124       minutes(Minutes) -> MilliSeconds
125
126              Types:
127
128                 Minutes = MilliSeconds = integer() >= 0
129
130              Returns the number of milliseconds in Minutes.
131
132       now_diff(T2, T1) -> Tdiff
133
134              Types:
135
136                 T1 = T2 = erlang:timestamp()
137                 Tdiff = integer()
138                   In microseconds
139
140              Calculates  the time difference Tdiff = T2 - T1 in microseconds,
141              where T1 and T2 are time-stamp tuples  on  the  same  format  as
142              returned from erlang:timestamp/0 or os:timestamp/0.
143
144       seconds(Seconds) -> MilliSeconds
145
146              Types:
147
148                 Seconds = MilliSeconds = integer() >= 0
149
150              Returns the number of milliseconds in Seconds.
151
152       send_after(Time, Message) -> {ok, TRef} | {error, Reason}
153
154       send_after(Time, Pid, Message) -> {ok, TRef} | {error, Reason}
155
156              Types:
157
158                 Time = time()
159                 Pid = pid() | (RegName :: atom())
160                 Message = term()
161                 TRef = tref()
162                 Reason = term()
163
164                send_after/3:
165                  Evaluates  Pid  !  Message after Time milliseconds. (Pid can
166                  also be an atom of a registered name.)
167
168                  Returns {ok, TRef} or {error, Reason}.
169
170                send_after/2:
171                  Same as send_after(Time, self(), Message).
172
173       send_interval(Time, Message) -> {ok, TRef} | {error, Reason}
174
175       send_interval(Time, Pid, Message) -> {ok, TRef} | {error, Reason}
176
177              Types:
178
179                 Time = time()
180                 Pid = pid() | (RegName :: atom())
181                 Message = term()
182                 TRef = tref()
183                 Reason = term()
184
185                send_interval/3:
186                  Evaluates Pid ! Message repeatedly after Time  milliseconds.
187                  (Pid can also be an atom of a registered name.)
188
189                  Returns {ok, TRef} or {error, Reason}.
190
191                send_interval/2:
192                  Same as send_interval(Time, self(), Message).
193
194       sleep(Time) -> ok
195
196              Types:
197
198                 Time = timeout()
199
200              Suspends the process calling this function for Time milliseconds
201              and then returns ok, or suspends the process forever if Time  is
202              the  atom  infinity.  Naturally,  this  function does not return
203              immediately.
204
205       start() -> ok
206
207              Starts the timer server. Normally, the server does not  need  to
208              be  started  explicitly.  It  is  started  dynamically  if it is
209              needed. This is useful during development, but in a target  sys‐
210              tem  the  server  is to be started explicitly. Use configuration
211              parameters for Kernel for this.
212
213       tc(Fun) -> {Time, Value}
214
215       tc(Fun, Arguments) -> {Time, Value}
216
217       tc(Module, Function, Arguments) -> {Time, Value}
218
219              Types:
220
221                 Module = module()
222                 Function = atom()
223                 Arguments = [term()]
224                 Time = integer()
225                   In microseconds
226                 Value = term()
227
228                tc/3:
229                  Evaluates apply(Module, Function,  Arguments)  and  measures
230                  the   elapsed   real   time   as  reported  by  erlang:mono‐
231                  tonic_time/0.
232
233                  Returns {Time, Value}, where Time is the elapsed  real  time
234                  in  microseconds,  and  Value  is  what is returned from the
235                  apply.
236
237                tc/2:
238                  Evaluates apply(Fun, Arguments). Otherwise the same as tc/3.
239
240                tc/1:
241                  Evaluates Fun(). Otherwise the same as tc/2.
242

EXAMPLES

244       Example 1
245
246       The following example shows how to print "Hello World!" in 5 seconds:
247
248       1> timer:apply_after(5000, io, format, ["~nHello World!~n", []]).
249       {ok,TRef}
250       Hello World!
251
252       Example 2
253
254       The following example shows a process performing a certain action,  and
255       if  this action is not completed within a certain limit, the process is
256       killed:
257
258       Pid = spawn(mod, fun, [foo, bar]),
259       %% If pid is not finished in 10 seconds, kill him
260       {ok, R} = timer:kill_after(timer:seconds(10), Pid),
261       %% We change our mind...
262       timer:cancel(R),
263

NOTES

265       A timer can always be removed by calling cancel/1.
266
267       An interval timer, that is, a timer created by evaluating  any  of  the
268       functions  apply_interval/4,  send_interval/3,  and  send_interval/2 is
269       linked to the process to which the timer performs its task.
270
271       A one-shot timer, that is, a timer created by  evaluating  any  of  the
272       functions   apply_after/4,  send_after/3,  send_after/2,  exit_after/3,
273       exit_after/2, kill_after/2, and  kill_after/1  is  not  linked  to  any
274       process.  Hence, such a timer is removed only when it reaches its time-
275       out, or if it is explicitly removed by a call to cancel/1.
276
277
278
279Ericsson AB                       stdlib 3.10                         timer(3)