aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc/src
diff options
context:
space:
mode:
authorRickard Green <rickard@erlang.org>2015-05-12 17:33:03 +0200
committerRickard Green <rickard@erlang.org>2015-05-12 17:33:03 +0200
commit4030cfbb8de3445e80b3dcb3a1a45d0c6bac6483 (patch)
tree0d1208936003936433ba3793ee5b677dbc9d1697 /erts/doc/src
parentff2400d7b5b1b090e128bc537d7bdd94c6aad97e (diff)
parent849a2ed2db2bd54422ec9284468f80cc86978974 (diff)
downloadotp-4030cfbb8de3445e80b3dcb3a1a45d0c6bac6483.tar.gz
otp-4030cfbb8de3445e80b3dcb3a1a45d0c6bac6483.tar.bz2
otp-4030cfbb8de3445e80b3dcb3a1a45d0c6bac6483.zip
Merge branch 'rickard/timer-optimization/OTP-12650'
* rickard/timer-optimization/OTP-12650: Timer fixes, documentation, and test cases Conflicts: erts/emulator/beam/erl_hl_timer.c
Diffstat (limited to 'erts/doc/src')
-rw-r--r--erts/doc/src/erlang.xml249
1 files changed, 207 insertions, 42 deletions
diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index ba5f80a9c1..6ca57566aa 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -536,29 +536,69 @@
</desc>
</func>
<func>
- <name name="cancel_timer" arity="1"/>
+ <name name="cancel_timer" arity="2"/>
<fsummary>Cancel a timer</fsummary>
<desc>
- <p>Cancels a timer, where <c><anno>TimerRef</anno></c> was returned by
- either
- <seealso marker="#send_after/3">erlang:send_after/3</seealso>
- or
- <seealso marker="#start_timer/3">erlang:start_timer/3</seealso>.
- If the timer is there to be removed, the function returns
- the time in milliseconds left until the timer would have expired,
- otherwise <c>false</c> (which means that <c><anno>TimerRef</anno></c> was
- never a timer, that it has already been cancelled, or that it
- has already delivered its message).</p>
+ <p>Cancels a timer. <c><anno>TimerRef</anno></c> needs to refer to
+ a timer that was created by either
+ <seealso marker="#send_after/4"><c>erlang:send_after()</c></seealso>,
+ or <seealso marker="#start_timer/4"><c>erlang:start_timer()</c></seealso>.</p>
+ <p>Currently available <c><anno>Option</anno>s</c>:</p>
+ <taglist>
+ <tag><c>{async, Async}</c></tag>
+ <item>
+ <p>Asynchronous request for cancellation. <c>Async</c>
+ defaults to <c>false</c>. That is the operation will be
+ performed synchronously. When <c>Async</c> is set to
+ <c>true</c> the cancel operation will be performed
+ asynchronously. That is, <c>cancel_timer()</c> will send
+ a request for cancellation to the timer service that
+ manages the timer, and then return <c>ok</c>.</p></item>
+ <tag><c>{info, Info}</c></tag>
+ <item>
+ <p>Request information about the <c>Result</c> of the
+ cancellation. <c>Info</c> defaults to <c>true</c>. That
+ is information will be given. When <c>Info</c> is set to
+ <c>false</c> no information about the result of the cancel
+ operation will be given. When the operation is performed
+ synchronously the <c>Result</c> will returned from
+ <c>cancel_timer()</c>. When the operation is performed
+ asynchronously, a message on the form
+ <c>{cancel_timer, <anno>TimerRef</anno>, <anno>Result</anno>}</c>
+ will be sent to the caller of <c>cancel_timer()</c> when
+ the operation has been performed.</p></item>
+ </taglist>
+ <p>When the <c><anno>Result</anno></c> equals <c>false</c> a timer
+ corresponding to <c><anno>TimerRef</anno></c> could not be found. This
+ can be either because the timer had expired, been canceled, or because
+ <c><anno>TimerRef</anno></c> do not correspond to a timer. When the
+ <c><anno>Result</anno></c> is an integer, it represents
+ the time in milli seconds left before the timer will expire.</p>
+ <note><p>The timer service that manages the timer may be co-located
+ with another scheduler than the scheduler that the calling process
+ is executing on. In this case communication with the timer
+ service will be performed using asynchronous signals. If the calling
+ process is in critical path and can do other things while waiting
+ for the result of this operation, you want to use the <c>{async, true}</c>
+ option.</p></note>
<p>See also
- <seealso marker="#send_after/3">erlang:send_after/3</seealso>,
- <seealso marker="#start_timer/3">erlang:start_timer/3</seealso>,
+ <seealso marker="#send_after/4"><c>erlang:send_after/4</c></seealso>,
+ <seealso marker="#start_timer/4"><c>erlang:start_timer/4</c></seealso>,
and
- <seealso marker="#read_timer/1">erlang:read_timer/1</seealso>.</p>
+ <seealso marker="#read_timer/2"><c>erlang:read_timer/2</c></seealso>.</p>
<p>Note: Cancelling a timer does not guarantee that the message
has not already been delivered to the message queue.</p>
</desc>
</func>
-
+ <func>
+ <name name="cancel_timer" arity="1"/>
+ <fsummary>Cancel a timer</fsummary>
+ <desc>
+ <p>Cancels a timer. The same as calling
+ <seealso marker="#cancel_timer/2"><c>erlang:cancel_timer(TimerRef,
+ [{async, false}, {info, true}])</c></seealso>.</p>
+ </desc>
+ </func>
<func>
<name name="check_old_code" arity="1"/>
<fsummary>Check if a module has old code</fsummary>
@@ -4505,23 +4545,54 @@ os_prompt% </pre>
</desc>
</func>
<func>
- <name name="read_timer" arity="1"/>
- <fsummary>Number of milliseconds remaining for a timer</fsummary>
- <desc>
- <p><c><anno>TimerRef</anno></c> is a timer reference returned by
- <seealso marker="#send_after/3">erlang:send_after/3</seealso>
- or
- <seealso marker="#start_timer/3">erlang:start_timer/3</seealso>.
- If the timer is active, the function returns the time in
- milliseconds left until the timer will expire, otherwise
- <c>false</c> (which means that <c><anno>TimerRef</anno></c> was never a
- timer, that it has been cancelled, or that it has already
- delivered its message).</p>
+ <name name="read_timer" arity="2"/>
+ <fsummary>Read the state of a timer</fsummary>
+ <desc>
+ <p>Read the state of a timer. <c><anno>TimerRef</anno></c>
+ needs to refer to a timer that was created by either
+ <seealso marker="#send_after/4"><c>erlang:send_after()</c></seealso>,
+ or <seealso marker="#start_timer/4"><c>erlang:start_timer()</c></seealso>.</p>
+ <p>Currently available <c><anno>Option</anno>s</c>:</p>
+ <taglist>
+ <tag><c>{async, Async}</c></tag>
+ <item>
+ <p>Asynchronous request. <c>Async</c> defaults to <c>false</c>. That
+ is the operation will be performed synchronously, and the <c>Result</c>
+ will returned from <c>read_timer()</c>. When <c>Async</c> is set to
+ <c>true</c>, <c>read_timer()</c> will send a request for the
+ <c>Result</c> to a timer service that manages the timer and then
+ return <c>ok</c>. A message on the format
+ <c>{read_timer, <anno>TimerRef</anno>, <anno>Result</anno>}</c>
+ will be sent to the caller of <c>read_timer()</c> when
+ the operation has been processed.</p></item>
+ </taglist>
+ <p>When the <c><anno>Result</anno></c> equals <c>false</c> a timer
+ corresponding to <c><anno>TimerRef</anno></c> could not be found. This
+ can be either because the timer had expired, been canceled, or because
+ <c><anno>TimerRef</anno></c> do not correspond to a timer. When the
+ <c><anno>Result</anno></c> is an integer, it represents
+ the time in milli seconds left before the timer will expire.</p>
+ <note><p>The timer service that manages the timer may be co-located
+ with another scheduler than the scheduler that the calling process
+ is executing on. In this case communication with the timer
+ service will be performed using asynchronous signals. If the calling
+ process is in critical path and can do other things while waiting
+ for the result of this operation, you want to use the <c>{async, true}</c>
+ option.</p></note>
<p>See also
- <seealso marker="#send_after/3">erlang:send_after/3</seealso>,
- <seealso marker="#start_timer/3">erlang:start_timer/3</seealso>,
+ <seealso marker="#send_after/4"><c>erlang:send_after/4</c></seealso>,
+ <seealso marker="#start_timer/4"><c>erlang:start_timer/4</c></seealso>,
and
- <seealso marker="#cancel_timer/1">erlang:cancel_timer/1</seealso>.</p>
+ <seealso marker="#cancel_timer/2"><c>erlang:cancel_timer/2</c></seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name name="read_timer" arity="1"/>
+ <fsummary>Read the state of a timer</fsummary>
+ <desc>
+ <p>Read the state of a timer. The same as calling
+ <seealso marker="#read_timer/2"><c>erlang:read_timer(TimerRef,
+ [{async, false}])</c></seealso>.</p>
</desc>
</func>
<func>
@@ -4670,6 +4741,63 @@ true</pre>
</desc>
</func>
<func>
+ <name name="send_after" arity="4"/>
+ <fsummary>Start a timer</fsummary>
+ <desc>
+ <p>Starts a timer. When the timer expires, the message
+ <c><anno>Msg</anno></c> will be sent to
+ <c><anno>Dest</anno></c>.</p>
+ <p>If <c><anno>Dest</anno></c> is a <c>pid()</c> it has to
+ be a <c>pid()</c> of a local process, dead or alive.</p>
+ <p>Currently available <c><anno>Option</anno>s</c>:</p>
+ <taglist>
+ <tag><c>{abs, Abs}</c></tag>
+ <item>
+ <p>Absolute timeout. When <c>Abs</c> is <c>false</c>
+ the <c><anno>Time</anno></c> value will be interpreted
+ as a time in milli-seconds relative current
+ <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang
+ monotonic time</seealso>. When <c>Abs</c> is <c>true</c> the
+ <c><anno>Time</anno></c> value will be interpreted as an absolute
+ Erlang monotonic time of milli second time unit. <c>Abs</c>
+ defaults to <c>false</c>.</p>
+ </item>
+ </taglist>
+ <p>The absolute time when the timer is set to expire needs
+ to be in the range between
+ <seealso marker="#system_info_start_time"><c>erlang:system_info(start_time)</c></seealso>
+ and
+ <seealso marker="#system_info_end_time"><c>erlang:system_info(end_time)</c></seealso>.
+ If a negative relative time is specified the time is not
+ allowed to be negative.</p>
+ <p>If <c><anno>Dest</anno></c> is an <c>atom()</c>, it is supposed to be the name of
+ a registered process. The process referred to by the name is
+ looked up at the time of delivery. No error is given if
+ the name does not refer to a process.</p>
+ <p>If <c><anno>Dest</anno></c> is a <c>pid()</c>, the timer will be automatically
+ canceled if the process referred to by the <c>pid()</c> is not alive,
+ or when the process exits. This feature was introduced in
+ erts version 5.4.11. Note that timers will not be
+ automatically canceled when <c><anno>Dest</anno></c> is an <c>atom()</c>.</p>
+ <p>See also
+ <seealso marker="#start_timer/4"><c>erlang:send_timer/4</c></seealso>,
+ <seealso marker="#cancel_timer/2"><c>erlang:cancel_timer/2</c></seealso>,
+ and
+ <seealso marker="#read_timer/2"><c>erlang:read_timer/2</c></seealso>.</p>
+ <p>Failure: <c>badarg</c> if the arguments does not satisfy
+ the requirements specified above.</p>
+ </desc>
+ </func>
+ <func>
+ <name name="send_after" arity="3"/>
+ <fsummary>Start a timer</fsummary>
+ <desc>
+ <p>Starts a timer. The same as calling
+ <seealso marker="#send_timer/4"><c>erlang:send_after(<anno>Time</anno>,
+ <anno>Dest</anno>, <anno>Msg</anno>, [{abs, false}])</c></seealso>.</p>
+ </desc>
+ </func>
+ <func>
<name name="send_after" arity="3"/>
<type_desc variable="Time">0 &lt;= Time &lt;= 4294967295</type_desc>
<fsummary>Start a timer</fsummary>
@@ -4690,9 +4818,9 @@ true</pre>
automatically canceled when <c><anno>Dest</anno></c> is an <c>atom</c>.</p>
<p>See also
<seealso marker="#start_timer/3">erlang:start_timer/3</seealso>,
- <seealso marker="#cancel_timer/1">erlang:cancel_timer/1</seealso>,
+ <seealso marker="#cancel_timer/2">erlang:cancel_timer/2</seealso>,
and
- <seealso marker="#read_timer/1">erlang:read_timer/1</seealso>.</p>
+ <seealso marker="#read_timer/2">erlang:read_timer/2</seealso>.</p>
<p>Failure: <c>badarg</c> if the arguments does not satisfy
the requirements specified above.</p>
</desc>
@@ -5100,15 +5228,35 @@ true</pre>
</desc>
</func>
<func>
- <name name="start_timer" arity="3"/>
- <type_desc variable="Time">0 &lt;= Time &lt;= 4294967295</type_desc>
+ <name name="start_timer" arity="4"/>
<fsummary>Start a timer</fsummary>
<desc>
- <p>Starts a timer which will send the message
- <c>{timeout, <anno>TimerRef</anno>, <anno>Msg</anno>}</c> to <c><anno>Dest</anno></c>
- after <c><anno>Time</anno></c> milliseconds.</p>
- <p>If <c><anno>Dest</anno></c> is a <c>pid()</c> it has to be a <c>pid()</c> of a local process, dead or alive.</p>
- <p>The <c><anno>Time</anno></c> value can, in the current implementation, not be greater than 4294967295.</p>
+ <p>Starts a timer. When the timer expires, the message
+ <c>{timeout, <anno>TimerRef</anno>, <anno>Msg</anno>}</c>
+ will be sent to <c><anno>Dest</anno></c>.</p>
+ <p>If <c><anno>Dest</anno></c> is a <c>pid()</c> it has to
+ be a <c>pid()</c> of a local process, dead or alive.</p>
+ <p>Currently available <c><anno>Option</anno>s</c>:</p>
+ <taglist>
+ <tag><c>{abs, Abs}</c></tag>
+ <item>
+ <p>Absolute timeout. When <c>Abs</c> is <c>false</c>
+ the <c><anno>Time</anno></c> value will be interpreted
+ as a time in milli-seconds relative current
+ <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang
+ monotonic time</seealso>. When <c>Abs</c> is <c>true</c> the
+ <c><anno>Time</anno></c> value will be interpreted as an absolute
+ Erlang monotonic time of milli second time unit. <c>Abs</c>
+ defaults to <c>false</c>.</p>
+ </item>
+ </taglist>
+ <p>The absolute time when the timer is set to expire needs
+ to be in the range between
+ <seealso marker="#system_info_start_time"><c>erlang:system_info(start_time)</c></seealso>
+ and
+ <seealso marker="#system_info_end_time"><c>erlang:system_info(end_time)</c></seealso>.
+ If a negative relative time is specified the time is not
+ allowed to be negative.</p>
<p>If <c><anno>Dest</anno></c> is an <c>atom()</c>, it is supposed to be the name of
a registered process. The process referred to by the name is
looked up at the time of delivery. No error is given if
@@ -5119,15 +5267,24 @@ true</pre>
erts version 5.4.11. Note that timers will not be
automatically canceled when <c><anno>Dest</anno></c> is an <c>atom()</c>.</p>
<p>See also
- <seealso marker="#send_after/3">erlang:send_after/3</seealso>,
- <seealso marker="#cancel_timer/1">erlang:cancel_timer/1</seealso>,
+ <seealso marker="#send_after/4"><c>erlang:send_after/4</c></seealso>,
+ <seealso marker="#cancel_timer/2"><c>erlang:cancel_timer/2</c></seealso>,
and
- <seealso marker="#read_timer/1">erlang:read_timer/1</seealso>.</p>
+ <seealso marker="#read_timer/2"><c>erlang:read_timer/2</c></seealso>.</p>
<p>Failure: <c>badarg</c> if the arguments does not satisfy
the requirements specified above.</p>
</desc>
</func>
<func>
+ <name name="start_timer" arity="3"/>
+ <fsummary>Start a timer</fsummary>
+ <desc>
+ <p>Starts a timer. The same as calling
+ <seealso marker="#start_timer/4"><c>erlang:start_timer(<anno>Time</anno>,
+ <anno>Dest</anno>, <anno>Msg</anno>, [{abs, false}])</c></seealso>.</p>
+ </desc>
+ </func>
+ <func>
<name name="statistics" arity="1" clause_i="1"/>
<fsummary>Information about context switches</fsummary>
<desc>
@@ -6236,6 +6393,14 @@ ok
(i.e. <c>system_info(dynamic_trace)</c> returns
<c>dtrace</c> or <c>systemtap</c>).</p>
</item>
+ <tag><marker id="system_info_end_time"/><c>end_time</c></tag>
+ <item><p>The last <seealso marker="#monotonic_time/0">Erlang monotonic
+ time</seealso> in <c>native</c>
+ <seealso marker="#type_time_unit">time unit</seealso> that
+ can be represented internally in the current Erlang runtime system
+ instance. The time between the
+ <seealso marker="#system_info_start_time">start time</seealso> and
+ the end time is at least a quarter of a millennium.</p></item>
<tag><c>elib_malloc</c></tag>
<item>
<p>This option will be removed in a future release.