aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/timer.xml
diff options
context:
space:
mode:
authorBjörn Gustavsson <[email protected]>2016-05-18 15:53:35 +0200
committerBjörn Gustavsson <[email protected]>2016-06-13 12:05:57 +0200
commit68d53c01b0b8e9a007a6a30158c19e34b2d2a34e (patch)
tree4613f513b9465beb7febec6c74c8ef0502f861fe /lib/stdlib/doc/src/timer.xml
parent99b379365981e14e2c8dde7b1a337c8ff856bd4a (diff)
downloadotp-68d53c01b0b8e9a007a6a30158c19e34b2d2a34e.tar.gz
otp-68d53c01b0b8e9a007a6a30158c19e34b2d2a34e.tar.bz2
otp-68d53c01b0b8e9a007a6a30158c19e34b2d2a34e.zip
Update STDLIB documentation
Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Björn Gustavsson and Hans Bolinder.
Diffstat (limited to 'lib/stdlib/doc/src/timer.xml')
-rw-r--r--lib/stdlib/doc/src/timer.xml380
1 files changed, 217 insertions, 163 deletions
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 @@
<checked></checked>
<date>1998-09-09</date>
<rev>D</rev>
- <file>timer.sgml</file>
+ <file>timer.xml</file>
</header>
<module>timer</module>
- <modulesummary>Timer Functions</modulesummary>
+ <modulesummary>Timer functions.</modulesummary>
<description>
<p>This module provides useful functions related to time. Unless otherwise
- stated, time is always measured in <c>milliseconds</c>. All
- timer functions return immediately, regardless of work carried
- out by another process.
- </p>
- <p>Successful evaluations of the timer functions yield return values
- containing a timer reference, denoted <c>TRef</c> below. By using
- <c>cancel/1</c>, the returned reference can be used to cancel any
- requested action. A <c>TRef</c> is an Erlang term, the contents
- of which must not be altered.
- </p>
- <p>The timeouts are not exact, but should be <c>at least</c> as long
- as requested.
- </p>
+ stated, time is always measured in <em>milliseconds</em>. All
+ timer functions return immediately, regardless of work done by another
+ process.</p>
+ <p>Successful evaluations of the timer functions give return values
+ containing a timer reference, denoted <c>TRef</c>. By using
+ <seealso marker="#cancel/1"><c>cancel/1</c></seealso>,
+ the returned reference can be used to cancel any
+ requested action. A <c>TRef</c> is an Erlang term, which contents
+ must not be changed.</p>
+ <p>The time-outs are not exact, but are <em>at least</em> as long
+ as requested.</p>
</description>
+
<datatypes>
<datatype>
<name name="time"/>
@@ -60,231 +59,286 @@
<desc><p>A timer reference.</p></desc>
</datatype>
</datatypes>
+
<funcs>
<func>
- <name name="start" arity="0"/>
- <fsummary>Start a global timer server (named <c>timer_server</c>).</fsummary>
+ <name name="apply_after" arity="4"/>
+ <fsummary>Apply <c>Module:Function(Arguments)</c> after a specified
+ <c>Time</c>.</fsummary>
<desc>
- <p>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 <c>kernel</c> for this.</p>
+ <p>Evaluates <c>apply(<anno>Module</anno>, <anno>Function</anno>,
+ <anno>Arguments</anno>)</c> after <c><anno>Time</anno></c>
+ milliseconds.</p>
+ <p>Returns <c>{ok, <anno>TRef</anno>}</c> or
+ <c>{error, <anno>Reason</anno>}</c>.</p>
</desc>
</func>
+
<func>
- <name name="apply_after" arity="4"/>
- <fsummary>Apply <c>Module:Function(Arguments)</c>after a specified <c>Time</c>.</fsummary>
+ <name name="apply_interval" arity="4"/>
+ <fsummary>Evaluate <c>Module:Function(Arguments)</c> repeatedly at
+ intervals of <c>Time</c>.</fsummary>
<desc>
- <p>Evaluates <c>apply(<anno>Module</anno>, <anno>Function</anno>, <anno>Arguments</anno>)</c> after <c><anno>Time</anno></c> amount of time
- has elapsed. Returns <c>{ok, <anno>TRef</anno>}</c>, or <c>{error, <anno>Reason</anno>}</c>.</p>
+ <p>Evaluates <c>apply(<anno>Module</anno>, <anno>Function</anno>,
+ <anno>Arguments</anno>)</c> repeatedly at intervals of
+ <c><anno>Time</anno></c>.</p>
+ <p>Returns <c>{ok, <anno>TRef</anno>}</c> or
+ <c>{error, <anno>Reason</anno>}</c>.</p>
</desc>
</func>
+
<func>
- <name name="send_after" arity="2"/>
- <name name="send_after" arity="3"/>
- <fsummary>Send <c>Message</c>to <c>Pid</c>after a specified <c>Time</c>.</fsummary>
+ <name name="cancel" arity="1"/>
+ <fsummary>Cancel a previously requested time-out identified by
+ <c>TRef</c>.</fsummary>
<desc>
- <taglist>
- <tag><c>send_after/3</c></tag>
- <item>
- <p>Evaluates <c><anno>Pid</anno> ! <anno>Message</anno></c> after <c><anno>Time</anno></c> amount
- of time has elapsed. (<c><anno>Pid</anno></c> can also be an atom of a
- registered name.) Returns <c>{ok, <anno>TRef</anno>}</c>, or
- <c>{error, <anno>Reason</anno>}</c>.</p>
- </item>
- <tag><c>send_after/2</c></tag>
- <item>
- <p>Same as <c>send_after(<anno>Time</anno>, self(), <anno>Message</anno>)</c>.</p>
- </item>
- </taglist>
+ <p>Cancels a previously requested time-out. <c><anno>TRef</anno></c> is
+ a unique
+ timer reference returned by the related timer function.</p>
+ <p>Returns <c>{ok, cancel}</c>, or <c>{error, <anno>Reason</anno>}</c>
+ when <c><anno>TRef</anno></c> is not a timer reference.</p>
</desc>
</func>
+
<func>
- <name name="kill_after" arity="1"/>
- <name name="kill_after" arity="2"/>
<name name="exit_after" arity="2"/>
<name name="exit_after" arity="3"/>
- <fsummary>Send an exit signal with <c>Reason</c>after a specified <c>Time</c>.</fsummary>
+ <fsummary>Send an exit signal with <c>Reason</c> after a specified
+ <c>Time</c>.</fsummary>
+ <desc>
+ <p><c>exit_after/2</c> is the same as
+ <c>exit_after(<anno>Time</anno>, self(),
+ <anno>Reason1</anno>)</c>.</p>
+ <p><c>exit_after/3</c> sends an exit signal with reason
+ <c><anno>Reason1</anno></c> to
+ pid <c><anno>Pid</anno></c>. Returns <c>{ok, <anno>TRef</anno>}</c>
+ or <c>{error, <anno>Reason2</anno>}</c>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="hms" arity="3"/>
+ <fsummary>Convert <c>Hours</c>+<c>Minutes</c>+<c>Seconds</c> to
+ <c>Milliseconds</c>.</fsummary>
+ <desc>
+ <p>Returns the number of milliseconds in <c><anno>Hours</anno> +
+ <anno>Minutes</anno> + <anno>Seconds</anno></c>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="hours" arity="1"/>
+ <fsummary>Convert <c>Hours</c> to <c>Milliseconds</c>.</fsummary>
+ <desc>
+ <p>Returns the number of milliseconds in <c><anno>Hours</anno></c>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="kill_after" arity="1"/>
+ <name name="kill_after" arity="2"/>
+ <fsummary>Send an exit signal with <c>Reason</c> after a specified
+ <c>Time</c>.</fsummary>
+ <desc>
+ <p><c>kill_after/1</c> is the same as
+ <c>exit_after(<anno>Time</anno>, self(), kill)</c>.</p>
+ <p><c>kill_after/2</c> is the same as
+ <c>exit_after(<anno>Time</anno>, <anno>Pid</anno>, kill)</c>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="minutes" arity="1"/>
+ <fsummary>Converts <c>Minutes</c> to <c>Milliseconds</c>.</fsummary>
+ <desc>
+ <p>Returns the number of milliseconds in
+ <c><anno>Minutes</anno></c>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="now_diff" arity="2"/>
+ <fsummary>Calculate time difference between time stamps.</fsummary>
+ <type_desc variable="Tdiff">In microseconds</type_desc>
+ <desc>
+ <p>Calculates the time difference <c><anno>Tdiff</anno> =
+ <anno>T2</anno> - <anno>T1</anno></c> in <em>microseconds</em>,
+ where <c><anno>T1</anno></c> and <c><anno>T2</anno></c>
+ are time-stamp tuples on the same format as returned from
+ <seealso marker="erts:erlang#timestamp/0">
+ <c>erlang:timestamp/0</c></seealso> or
+ <seealso marker="kernel:os#timestamp/0">
+ <c>os:timestamp/0</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="seconds" arity="1"/>
+ <fsummary>Convert <c>Seconds</c> to <c>Milliseconds</c>.</fsummary>
+ <desc>
+ <p>Returns the number of milliseconds in
+ <c><anno>Seconds</anno></c>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="send_after" arity="2"/>
+ <name name="send_after" arity="3"/>
+ <fsummary>Send <c>Message</c> to <c>Pid</c> after a specified
+ <c>Time</c>.</fsummary>
<desc>
<taglist>
- <tag><c>exit_after/3</c></tag>
- <item>
- <p>Send an exit signal with reason <c><anno>Reason1</anno></c> to Pid
- <c><anno>Pid</anno></c>. Returns <c>{ok, <anno>TRef</anno>}</c>, or
- <c>{error, <anno>Reason2</anno>}</c>.</p>
- </item>
- <tag><c>exit_after/2</c></tag>
- <item>
- <p>Same as <c>exit_after(<anno>Time</anno>, self(), <anno>Reason1</anno>)</c>. </p>
- </item>
- <tag><c>kill_after/2</c></tag>
+ <tag><c>send_after/3</c></tag>
<item>
- <p>Same as <c>exit_after(<anno>Time</anno>, <anno>Pid</anno>, kill)</c>. </p>
+ <p>Evaluates <c><anno>Pid</anno> ! <anno>Message</anno></c> after
+ <c><anno>Time</anno></c> milliseconds. (<c><anno>Pid</anno></c>
+ can also be an atom of a registered name.)</p>
+ <p>Returns <c>{ok, <anno>TRef</anno>}</c> or
+ <c>{error, <anno>Reason</anno>}</c>.</p>
</item>
- <tag><c>kill_after/1</c></tag>
+ <tag><c>send_after/2</c></tag>
<item>
- <p>Same as <c>exit_after(<anno>Time</anno>, self(), kill)</c>. </p>
+ <p>Same as <c>send_after(<anno>Time</anno>, self(),
+ <anno>Message</anno>)</c>.</p>
</item>
</taglist>
</desc>
</func>
- <func>
- <name name="apply_interval" arity="4"/>
- <fsummary>Evaluate <c>Module:Function(Arguments)</c>repeatedly at intervals of <c>Time</c>.</fsummary>
- <desc>
- <p>Evaluates <c>apply(<anno>Module</anno>, <anno>Function</anno>, <anno>Arguments</anno>)</c> repeatedly at
- intervals of <c><anno>Time</anno></c>. Returns <c>{ok, <anno>TRef</anno>}</c>, or
- <c>{error, <anno>Reason</anno>}</c>.</p>
- </desc>
- </func>
+
<func>
<name name="send_interval" arity="2"/>
<name name="send_interval" arity="3"/>
- <fsummary>Send <c>Message</c>repeatedly at intervals of <c>Time</c>.</fsummary>
+ <fsummary>Send <c>Message</c> repeatedly at intervals of <c>Time</c>.
+ </fsummary>
<desc>
<taglist>
<tag><c>send_interval/3</c></tag>
<item>
- <p>Evaluates <c><anno>Pid</anno> ! <anno>Message</anno></c> repeatedly after <c><anno>Time</anno></c>
- amount of time has elapsed. (<c><anno>Pid</anno></c> can also be an atom of
- a registered name.) Returns <c>{ok, <anno>TRef</anno>}</c> or
+ <p>Evaluates <c><anno>Pid</anno> ! <anno>Message</anno></c>
+ repeatedly after <c><anno>Time</anno></c> milliseconds.
+ (<c><anno>Pid</anno></c> can also be
+ an atom of a registered name.)</p>
+ <p>Returns <c>{ok, <anno>TRef</anno>}</c> or
<c>{error, <anno>Reason</anno>}</c>.</p>
</item>
<tag><c>send_interval/2</c></tag>
<item>
- <p>Same as <c>send_interval(<anno>Time</anno>, self(), <anno>Message</anno>)</c>.</p>
+ <p>Same as <c>send_interval(<anno>Time</anno>, self(),
+ <anno>Message</anno>)</c>.</p>
</item>
</taglist>
</desc>
</func>
+
<func>
- <name name="cancel" arity="1"/>
- <fsummary>Cancel a previously requested timeout identified by <c>TRef</c>.</fsummary>
+ <name name="sleep" arity="1"/>
+ <fsummary>Suspend the calling process for <c>Time</c> milliseconds.
+ </fsummary>
<desc>
- <p>Cancels a previously requested timeout. <c><anno>TRef</anno></c> is a unique
- timer reference returned by the timer function in question. Returns
- <c>{ok, cancel}</c>, or <c>{error, <anno>Reason</anno>}</c> when <c><anno>TRef</anno></c>
- is not a timer reference.</p>
+ <p>Suspends the process calling this function for
+ <c><anno>Time</anno></c> milliseconds and then returns <c>ok</c>,
+ or suspends the process forever if <c><anno>Time</anno></c> is the
+ atom <c>infinity</c>. Naturally, this
+ function does <em>not</em> return immediately.</p>
</desc>
</func>
+
<func>
- <name name="sleep" arity="1"/>
- <fsummary>Suspend the calling process for <c>Time</c>amount of milliseconds.</fsummary>
+ <name name="start" arity="0"/>
+ <fsummary>Start a global timer server (named <c>timer_server</c>).
+ </fsummary>
<desc>
- <p>Suspends the process calling this function for <c><anno>Time</anno></c> amount
- of milliseconds and then returns <c>ok</c>, or suspend the process
- forever if <c><anno>Time</anno></c> is the atom <c>infinity</c>. Naturally, this
- function does <em>not</em> return immediately.</p>
+ <p>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
+ <seealso marker="kernel:index"><c>Kernel</c></seealso> for this.</p>
</desc>
</func>
+
<func>
<name name="tc" arity="1"/>
<name name="tc" arity="2"/>
<name name="tc" arity="3"/>
<fsummary>Measure the real time it takes to evaluate <c>apply(Module,
- Function, Arguments)</c> or <c>apply(Fun, Arguments)</c></fsummary>
+ Function, Arguments)</c> or <c>apply(Fun, Arguments)</c>.</fsummary>
<type_desc variable="Time">In microseconds</type_desc>
<desc>
<taglist>
<tag><c>tc/3</c></tag>
<item>
- <p>Evaluates <c>apply(<anno>Module</anno>, <anno>Function</anno>, <anno>Arguments</anno>)</c> and measures
- the elapsed real time as reported by <c>os:timestamp/0</c>.
- Returns <c>{<anno>Time</anno>, <anno>Value</anno>}</c>, where
- <c><anno>Time</anno></c> is the elapsed real time in <em>microseconds</em>,
- and <c><anno>Value</anno></c> is what is returned from the apply.</p>
+ <p>Evaluates <c>apply(<anno>Module</anno>, <anno>Function</anno>,
+ <anno>Arguments</anno>)</c> and measures the elapsed real time as
+ reported by <seealso marker="os:timestamp/0">
+ <c>os:timestamp/0</c></seealso>.</p>
+ <p>Returns <c>{<anno>Time</anno>, <anno>Value</anno>}</c>, where
+ <c><anno>Time</anno></c> is the elapsed real time in
+ <em>microseconds</em>, and <c><anno>Value</anno></c> is what is
+ returned from the apply.</p>
</item>
<tag><c>tc/2</c></tag>
<item>
- <p>Evaluates <c>apply(<anno>Fun</anno>, <anno>Arguments</anno>)</c>. Otherwise works
- like <c>tc/3</c>.</p>
+ <p>Evaluates <c>apply(<anno>Fun</anno>, <anno>Arguments</anno>)</c>.
+ Otherwise the same as <c>tc/3</c>.</p>
</item>
<tag><c>tc/1</c></tag>
<item>
- <p>Evaluates <c><anno>Fun</anno>()</c>. Otherwise works like <c>tc/2</c>.</p>
+ <p>Evaluates <c><anno>Fun</anno>()</c>. Otherwise the same as
+ <c>tc/2</c>.</p>
</item>
-
</taglist>
</desc>
</func>
- <func>
- <name name="now_diff" arity="2"/>
- <fsummary>Calculate time difference between timestamps</fsummary>
- <type_desc variable="Tdiff">In microseconds</type_desc>
- <desc>
- <p>Calculates the time difference <c><anno>Tdiff</anno> = <anno>T2</anno> - <anno>T1</anno></c> in
- <em>microseconds</em>, where <c><anno>T1</anno></c> and <c><anno>T2</anno></c>
- are timestamp tuples on the same format as returned from
- <seealso marker="erts:erlang#timestamp/0"><c>erlang:timestamp/0</c></seealso>,
- or <seealso marker="kernel:os#timestamp/0"><c>os:timestamp/0</c></seealso>.</p>
- </desc>
- </func>
- <func>
- <name name="seconds" arity="1"/>
- <fsummary>Convert <c>Seconds</c>to <c>Milliseconds</c>.</fsummary>
- <desc>
- <p>Returns the number of milliseconds in <c><anno>Seconds</anno></c>.</p>
- </desc>
- </func>
- <func>
- <name name="minutes" arity="1"/>
- <fsummary>Converts <c>Minutes</c> to <c>Milliseconds</c>.</fsummary>
- <desc>
- <p>Return the number of milliseconds in <c><anno>Minutes</anno></c>.</p>
- </desc>
- </func>
- <func>
- <name name="hours" arity="1"/>
- <fsummary>Convert <c>Hours</c>to <c>Milliseconds</c>.</fsummary>
- <desc>
- <p>Returns the number of milliseconds in <c><anno>Hours</anno></c>.</p>
- </desc>
- </func>
- <func>
- <name name="hms" arity="3"/>
- <fsummary>Convert <c>Hours</c>+<c>Minutes</c>+<c>Seconds</c>to <c>Milliseconds</c>.</fsummary>
- <desc>
- <p>Returns the number of milliseconds in <c><anno>Hours</anno> + <anno>Minutes</anno> + <anno>Seconds</anno></c>.</p>
- </desc>
- </func>
</funcs>
<section>
<title>Examples</title>
- <p>This example illustrates how to print out "Hello World!" in 5 seconds:</p>
+ <p><em>Example 1</em></p>
+ <p>The following example shows how to print "Hello World!" in 5 seconds:</p>
<pre>
- 1> <input>timer:apply_after(5000, io, format, ["~nHello World!~n", []]).</input>
- {ok,TRef}
- Hello World!</pre>
- <p>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.</p>
+1> <input>timer:apply_after(5000, io, format, ["~nHello World!~n", []]).</input>
+{ok,TRef}
+Hello World!</pre>
+
+ <p><em>Example 2</em></p>
+ <p>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:</p>
<code type="none">
- 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),
- ...</code>
+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),
+...</code>
</section>
<section>
- <title>WARNING</title>
- <p>A timer can always be removed by calling <c>cancel/1</c>.
- </p>
- <p>An interval timer, i.e. a timer created by evaluating any of the
- functions <c>apply_interval/4</c>, <c>send_interval/3</c>, and
- <c>send_interval/2</c>, is linked to the process towards which
- the timer performs its task.
- </p>
- <p>A one-shot timer, i.e. a timer created by evaluating any of the
- functions <c>apply_after/4</c>, <c>send_after/3</c>,
- <c>send_after/2</c>, <c>exit_after/3</c>, <c>exit_after/2</c>,
- <c>kill_after/2</c>, and <c>kill_after/1</c> 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 <c>cancel/1</c>.</p>
+ <title>Notes</title>
+ <p>A timer can always be removed by calling
+ <seealso marker="#cancel/1"><c>cancel/1</c></seealso>.</p>
+
+ <p>An interval timer, that is, a timer created by evaluating any of the
+ functions
+ <seealso marker="#apply_interval/4"><c>apply_interval/4</c></seealso>,
+ <seealso marker="#send_interval/3"><c>send_interval/3</c></seealso>, and
+ <seealso marker="#send_interval/2"><c>send_interval/2</c></seealso>
+ is linked to the process to which the timer performs its task.</p>
+
+ <p>A one-shot timer, that is, a timer created by evaluating any of the
+ functions
+ <seealso marker="#apply_after/4"><c>apply_after/4</c></seealso>,
+ <seealso marker="#send_after/3"><c>send_after/3</c></seealso>,
+ <seealso marker="#send_after/2"><c>send_after/2</c></seealso>,
+ <seealso marker="#exit_after/3"><c>exit_after/3</c></seealso>,
+ <seealso marker="#exit_after/2"><c>exit_after/2</c></seealso>,
+ <seealso marker="#kill_after/2"><c>kill_after/2</c></seealso>, and
+ <seealso marker="#kill_after/1"><c>kill_after/1</c></seealso>
+ 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
+ <seealso marker="#cancel/1"><c>cancel/1</c></seealso>.</p>
</section>
</erlref>