1timer(3) Erlang Module Definition timer(3)
2
6 timer - Timer functions.
7
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 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 The time-outs are not exact, but are at least as long as requested.
19 Creating timers using erlang:send_after/3 and erlang:start_timer/3 is
21 more efficient than using the timers provided by this module. However,
22 the timer module has been improved in OTP 25, making it more efficient
23 and less susceptible to being overloaded. See the Timer Module section
24 in the Efficiency Guide.
25
27 time() = integer() >= 0
28 Time in milliseconds.
30 tref()
32 A timer reference.
34
36 apply_after(Time, Module, Function, Arguments) ->
37 {ok, TRef} | {error, Reason}
38 Types:
40 Time = time()
42 Module = module()
43 Function = atom()
44 Arguments = [term()]
45 TRef = tref()
46 Reason = term()
47 Evaluates apply(Module, Function, Arguments) after Time mil‐
49 liseconds.
50 Returns {ok, TRef} or {error, Reason}.
52 apply_interval(Time, Module, Function, Arguments) ->
54 {ok, TRef} | {error, Reason}
55 Types:
57 Time = time()
59 Module = module()
60 Function = atom()
61 Arguments = [term()]
62 TRef = tref()
63 Reason = term()
64 Evaluates apply(Module, Function, Arguments) repeatedly at in‐
66 tervals of Time.
67 Returns {ok, TRef} or {error, Reason}.
69 cancel(TRef) -> {ok, cancel} | {error, Reason}
71 Types:
73 TRef = tref()
75 Reason = term()
76 Cancels a previously requested time-out. TRef is a unique timer
78 reference returned by the related timer function.
79 Returns {ok, cancel}, or {error, Reason} when TRef is not a
81 timer reference.
82 exit_after(Time, Reason1) -> {ok, TRef} | {error, Reason2}
84 exit_after(Time, Target, Reason1) -> {ok, TRef} | {error, Reason2}
86 Types:
88 Time = time()
90 Target = pid() | (RegName :: atom())
91 TRef = tref()
92 Reason1 = Reason2 = term()
93 exit_after/2 is the same as exit_after(Time, self(), Reason1).
95 exit_after/3 sends an exit signal with reason Reason1 to Target,
97 which can be a local process identifier or an atom of a regis‐
98 tered name. Returns {ok, TRef} or {error, Reason2}.
99 hms(Hours, Minutes, Seconds) -> MilliSeconds
101 Types:
103 Hours = Minutes = Seconds = MilliSeconds = integer() >= 0
105 Returns the number of milliseconds in Hours + Minutes + Seconds.
107 hours(Hours) -> MilliSeconds
109 Types:
111 Hours = MilliSeconds = integer() >= 0
113 Returns the number of milliseconds in Hours.
115 kill_after(Time) -> {ok, TRef} | {error, Reason2}
117 kill_after(Time, Target) -> {ok, TRef} | {error, Reason2}
119 Types:
121 Time = time()
123 Target = pid() | (RegName :: atom())
124 TRef = tref()
125 Reason2 = term()
126 kill_after/1 is the same as exit_after(Time, self(), kill).
128 kill_after/2 is the same as exit_after(Time, Target, kill).
130 minutes(Minutes) -> MilliSeconds
132 Types:
134 Minutes = MilliSeconds = integer() >= 0
136 Returns the number of milliseconds in Minutes.
138 now_diff(T2, T1) -> Tdiff
140 Types:
142 T1 = T2 = erlang:timestamp()
144 Tdiff = integer()
145 In microseconds
146 Calculates the time difference Tdiff = T2 - T1 in microseconds,
148 where T1 and T2 are time-stamp tuples on the same format as re‐
149 turned from erlang:timestamp/0 or os:timestamp/0.
150 seconds(Seconds) -> MilliSeconds
152 Types:
154 Seconds = MilliSeconds = integer() >= 0
156 Returns the number of milliseconds in Seconds.
158 send_after(Time, Message) -> {ok, TRef} | {error, Reason}
160 send_after(Time, Destination, Message) ->
162 {ok, TRef} | {error, Reason}
163 Types:
165 Time = time()
167 Destination =
168 pid() |
169 (RegName :: atom()) |
170 {RegName :: atom(), Node :: node()}
171 Message = term()
172 TRef = tref()
173 Reason = term()
174 send_after/3:
176 Evaluates Destination ! Message after Time milliseconds.
177 (Destination can be a remote or local process identifier, an
178 atom of a registered name or a tuple {RegName, Node} for a
179 registered name at another node.)
180 Returns {ok, TRef} or {error, Reason}.
182 See also the Timer Module section in the Efficiency Guide.
184 send_after/2:
186 Same as send_after(Time, self(), Message).
187 send_interval(Time, Message) -> {ok, TRef} | {error, Reason}
189 send_interval(Time, Destination, Message) ->
191 {ok, TRef} | {error, Reason}
192 Types:
194 Time = time()
196 Destination =
197 pid() |
198 (RegName :: atom()) |
199 {RegName :: atom(), Node :: node()}
200 Message = term()
201 TRef = tref()
202 Reason = term()
203 send_interval/3:
205 Evaluates Destination ! Message repeatedly after Time mil‐
206 liseconds. (Destination can be a remote or local process
207 identifier, an atom of a registered name or a tuple {Reg‐
208 Name, Node} for a registered name at another node.)
209 Returns {ok, TRef} or {error, Reason}.
211 send_interval/2:
213 Same as send_interval(Time, self(), Message).
214 sleep(Time) -> ok
216 Types:
218 Time = timeout()
220 Suspends the process calling this function for Time milliseconds
222 and then returns ok, or suspends the process forever if Time is
223 the atom infinity. Naturally, this function does not return im‐
224 mediately.
225 Note:
227 Before OTP 25, timer:sleep/1 did not accept integer timeout val‐
228 ues greater than 16#ffffffff, that is, 2^32-1. Since OTP 25, ar‐
229 bitrarily high integer values are accepted.
230 start() -> ok
233 Starts the timer server. Normally, the server does not need to
235 be started explicitly. It is started dynamically if it is
236 needed. This is useful during development, but in a target sys‐
237 tem the server is to be started explicitly. Use configuration
238 parameters for Kernel for this.
239 tc(Fun) -> {Time, Value}
241 tc(Fun, Arguments) -> {Time, Value}
243 tc(Module, Function, Arguments) -> {Time, Value}
245 Types:
247 Module = module()
249 Function = atom()
250 Arguments = [term()]
251 Time = integer()
252 In microseconds
253 Value = term()
254 tc/3:
256 Evaluates apply(Module, Function, Arguments) and measures
257 the elapsed real time as reported by erlang:mono‐
258 tonic_time/0.
259 Returns {Time, Value}, where Time is the elapsed real time
261 in microseconds, and Value is what is returned from the ap‐
262 ply.
263 tc/2:
265 Evaluates apply(Fun, Arguments). Otherwise the same as tc/3.
266 tc/1:
268 Evaluates Fun(). Otherwise the same as tc/2.
269
271 Example 1
272 The following example shows how to print "Hello World!" in 5 seconds:
274 1> timer:apply_after(5000, io, format, ["~nHello World!~n", []]).
276 {ok,TRef}
277 Hello World!
278 Example 2
280 The following example shows a process performing a certain action, and
282 if this action is not completed within a certain limit, the process is
283 killed:
284 Pid = spawn(mod, fun, [foo, bar]),
286 %% If pid is not finished in 10 seconds, kill him
287 {ok, R} = timer:kill_after(timer:seconds(10), Pid),
288 %% We change our mind...
289 timer:cancel(R),
290
292 A timer can always be removed by calling cancel/1.
293 An interval timer, that is, a timer created by evaluating any of the
295 functions apply_interval/4, send_interval/3, and send_interval/2 is
296 linked to the process to which the timer performs its task.
297 A one-shot timer, that is, a timer created by evaluating any of the
299 functions apply_after/4, send_after/3, send_after/2, exit_after/3,
300 exit_after/2, kill_after/2, and kill_after/1 is not linked to any
301 process. Hence, such a timer is removed only when it reaches its time-
302 out, or if it is explicitly removed by a call to cancel/1.
303Ericsson AB stdlib 4.2 timer(3)