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  re‐
15       turned  reference can be used to cancel any requested action. A TRef is
16       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
20       Creating timers using erlang:send_after/3 and  erlang:start_timer/3  is
21       much  more efficient than using the timers provided by this module. See
22       the Timer Module section in the Efficiency Guide.
23

DATA TYPES

25       time() = integer() >= 0
26
27              Time in milliseconds.
28
29       tref()
30
31              A timer reference.
32

EXPORTS

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

EXAMPLES

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

NOTES

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