From 68d53c01b0b8e9a007a6a30158c19e34b2d2a34e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?=
Date: Wed, 18 May 2016 15:53:35 +0200
Subject: Update STDLIB documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Language cleaned up by the technical writers xsipewe and tmanevik
from Combitech. Proofreading and corrections by Björn Gustavsson
and Hans Bolinder.
---
lib/stdlib/doc/src/timer.xml | 380 ++++++++++++++++++++++++-------------------
1 file changed, 217 insertions(+), 163 deletions(-)
(limited to 'lib/stdlib/doc/src/timer.xml')
diff --git a/lib/stdlib/doc/src/timer.xml b/lib/stdlib/doc/src/timer.xml
index 4f259d57a8..8f2ce36b06 100644
--- a/lib/stdlib/doc/src/timer.xml
+++ b/lib/stdlib/doc/src/timer.xml
@@ -30,26 +30,25 @@
1998-09-09D
- timer.sgml
+ timer.xmltimer
- Timer Functions
+ Timer functions.
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.
-
+ stated, time is always measured in milliseconds. All
+ timer functions return immediately, regardless of work done by another
+ process.
+
Successful evaluations of the timer functions give return values
+ containing a timer reference, denoted TRef. By using
+ cancel/1,
+ the returned reference can be used to cancel any
+ requested action. A TRef is an Erlang term, which contents
+ must not be changed.
+
The time-outs are not exact, but are at least as long
+ as requested.
+
@@ -60,231 +59,286 @@
A timer reference.
+
-
- Start a global timer server (named timer_server).
+
+ Apply Module:Function(Arguments) after a specified
+ Time.
-
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.
+
Evaluates apply(Module, Function,
+ Arguments) after Time
+ milliseconds.
+
Returns {ok, TRef} or
+ {error, Reason}.
+
-
- Apply Module:Function(Arguments)after a specified Time.
+
+ Evaluate Module:Function(Arguments) repeatedly at
+ intervals of Time.
-
Evaluates apply(Module, Function, Arguments) after Time amount of time
- has elapsed. Returns {ok, TRef}, or {error, Reason}.
+
Evaluates apply(Module, Function,
+ Arguments) repeatedly at intervals of
+ Time.
+
Returns {ok, TRef} or
+ {error, Reason}.
+
-
-
- Send Messageto Pidafter a specified Time.
+
+ Cancel a previously requested time-out identified by
+ TRef.
-
- 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).
-
-
+
Cancels a previously requested time-out. TRef is
+ a unique
+ timer reference returned by the related timer function.
+
Returns {ok, cancel}, or {error, Reason}
+ when TRef is not a timer reference.
+
-
-
- Send an exit signal with Reasonafter a specified Time.
+ Send an exit signal with Reason after a specified
+ Time.
+
+
exit_after/2 is the same as
+ exit_after(Time, self(),
+ Reason1).
+
exit_after/3 sends an exit signal with reason
+ Reason1 to
+ pid Pid. Returns {ok, TRef}
+ or {error, Reason2}.
Returns the number of milliseconds in Hours +
+ Minutes + Seconds.
+
+
+
+
+
+ Convert Hours to Milliseconds.
+
+
Returns the number of milliseconds in Hours.
+
+
+
+
+
+
+ Send an exit signal with Reason after a specified
+ Time.
+
+
kill_after/1 is the same as
+ exit_after(Time, self(), kill).
+
kill_after/2 is the same as
+ exit_after(Time, Pid, kill).
+
+
+
+
+
+ Converts Minutes to Milliseconds.
+
+
Returns the number of milliseconds in
+ Minutes.
+
+
+
+
+
+ Calculate time difference between time stamps.
+ In microseconds
+
+
Calculates the time difference Tdiff =
+ T2 - T1 in microseconds,
+ where T1 and T2
+ are time-stamp tuples on the same format as returned from
+
+ erlang:timestamp/0 or
+
+ os:timestamp/0.
+
+
+
+
+
+ Convert Seconds to Milliseconds.
+
+
Returns the number of milliseconds in
+ Seconds.
+
+
+
+
+
+
+ Send Message to Pid after a specified
+ Time.
- 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
+ send_after/3
-
Same as exit_after(Time, Pid, kill).
+
Evaluates Pid ! Message after
+ Time milliseconds. (Pid
+ can also be an atom of a registered name.)
+
Returns {ok, TRef} or
+ {error, Reason}.
- kill_after/1
+ send_after/2
-
Same as exit_after(Time, self(), kill).
+
Same as send_after(Time, self(),
+ Message).
-
-
- Evaluate Module:Function(Arguments)repeatedly at intervals of Time.
-
-
Evaluates apply(Module, Function, Arguments) repeatedly at
- intervals of Time. Returns {ok, TRef}, or
- {error, Reason}.
-
-
+
- Send Messagerepeatedly at intervals of Time.
+ Send Message repeatedly at intervals of Time.
+ 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
+
Evaluates Pid ! Message
+ repeatedly after Time milliseconds.
+ (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).
+
Same as send_interval(Time, self(),
+ Message).
+
-
- Cancel a previously requested timeout identified by TRef.
+
+ Suspend the calling process for Time milliseconds.
+
-
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.
+
Suspends the process calling this function for
+ Time milliseconds and then returns ok,
+ or suspends the process forever if Time is the
+ atom infinity. Naturally, this
+ function does not return immediately.
+
-
- Suspend the calling process for Timeamount of milliseconds.
+
+ Start a global timer server (named timer_server).
+
-
Suspends the process calling this function for Time amount
- of milliseconds and then returns ok, or suspend the process
- forever if Time is the atom infinity. Naturally, this
- function does not return immediately.
+
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 is to be started explicitly. Use
+ configuration parameters for
+ Kernel for this.
+
Measure the real time it takes to evaluate apply(Module,
- Function, Arguments) or apply(Fun, Arguments)
+ Function, Arguments) or apply(Fun, Arguments).
In microsecondstc/3
-
Evaluates apply(Module, Function, Arguments) and measures
- the elapsed real time as reported by os:timestamp/0.
- Returns {Time, Value}, where
- Time is the elapsed real time in microseconds,
- and Value is what is returned from the apply.
+
Evaluates apply(Module, Function,
+ Arguments) and measures the elapsed real time as
+ reported by
+ os:timestamp/0.
+
Returns {Time, Value}, where
+ Time is the elapsed real time in
+ microseconds, and Value is what is
+ returned from the apply.
tc/2
-
Evaluates apply(Fun, Arguments). Otherwise works
- like tc/3.
+
Evaluates apply(Fun, Arguments).
+ Otherwise the same as tc/3.
tc/1
-
Evaluates Fun(). Otherwise works like tc/2.
+
Evaluates Fun(). Otherwise the same as
+ tc/2.
-
-
-
- Calculate time difference between timestamps
- In microseconds
-
-
Calculates the time difference Tdiff = T2 - T1 in
- microseconds, where T1 and T2
- are timestamp tuples on the same format as returned from
- erlang:timestamp/0,
- or os:timestamp/0.
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.
The following example shows a process performing a
+ certain action, and if this action is not completed within a certain
+ limit, 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),
- ...
+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.
+ Notes
+
A timer can always be removed by calling
+ cancel/1.
+
+
An interval timer, that is, a timer created by evaluating any of the
+ functions
+ apply_interval/4,
+ send_interval/3, and
+ send_interval/2
+ is linked to the process to which the timer performs its task.
+
+
A one-shot timer, that is, 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 time-out, or if it is explicitly removed by a call to
+ cancel/1.