Timer fixes, documentation, and test cases

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.