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 os:timestamp/0.
231
232                  Returns  {Time,  Value}, where Time is the elapsed real time
233                  in microseconds, and Value is  what  is  returned  from  the
234                  apply.
235
236                tc/2:
237                  Evaluates apply(Fun, Arguments). Otherwise the same as tc/3.
238
239                tc/1:
240                  Evaluates Fun(). Otherwise the same as tc/2.
241

EXAMPLES

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

NOTES

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