diff options
Diffstat (limited to 'lib/stdlib/doc/src/timer.xml')
| -rw-r--r-- | lib/stdlib/doc/src/timer.xml | 382 |
1 files changed, 218 insertions, 164 deletions
diff --git a/lib/stdlib/doc/src/timer.xml b/lib/stdlib/doc/src/timer.xml index 7609487300..e913e33589 100644 --- a/lib/stdlib/doc/src/timer.xml +++ b/lib/stdlib/doc/src/timer.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2013</year> + <year>1996</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -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">Kernel</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="erts:erlang#monotonic_time/0"> + <c>erlang:monotonic_time/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> |