Merge branch 'rickard/timer-improvement/OTP-12650'

* rickard/timer-improvement/OTP-12650:
  Fix bug causing timeout to overwrite exit instruction
  Doc fixes

1 files changed, 189 insertions, 169 deletions

diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 6ca57566aa..3fea64cef5 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -539,55 +539,94 @@
       <name name="cancel_timer" arity="2"/>
       <fsummary>Cancel a timer</fsummary>
       <desc>
-        <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>
+        <p>
+	  Cancels a timer that has been created by either
+	  <seealso marker="#start_timer/4"><c>erlang:start_timer()</c></seealso>,
+	  or <seealso marker="#send_after/4"><c>erlang:send_after()</c></seealso>.
+	  <c><anno>TimerRef</anno></c> identifies the timer, and
+	  was returned by the BIF that created the timer.
+	</p>
+	<p>Currently available <c><anno>Option</anno></c>s:</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>
+	    <p>
+	      Asynchronous request for cancellation. <c>Async</c>
+	      defaults to <c>false</c> which will cause the
+	      cancellation to be performed synchronously. When
+	      <c>Async</c> is set to <c>true</c>, the cancel
+	      operation will be performed asynchronously. That is,
+	      <c>erlang:cancel_timer()</c> will send an asynchronous
+	      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>
+	    <p>
+	      Request information about the <c><anno>Result</anno></c>
+	      of the cancellation. <c>Info</c> defaults to <c>true</c>
+	      which means that the <c><anno>Result</anno></c> will
+	      be given. When <c>Info</c> is set to <c>false</c>, no
+	      information about the result of the cancellation
+	      will be given. When the operation is performed</p>
+              <taglist>
+		<tag>synchronously</tag>
+		<item>
+		  <p>
+		    If <c>Info</c> is <c>true</c>, the <c>Result</c> will
+		    returned by <c>erlang:cancel_timer()</c>; otherwise,
+		    <c>ok</c> will be returned.
+		  </p>
+		</item>
+		<tag>asynchronously</tag>
+		<item>
+		  <p>
+		    If <c>Info</c> is <c>true</c>, a message on the form
+		    <c>{cancel_timer, <anno>TimerRef</anno>,
+		    <anno>Result</anno>}</c> will be sent to the
+		    caller of <c>erlang:cancel_timer()</c> when the
+		    cancellation operation has been performed; otherwise,
+		    no message will be sent.
+		  </p>
+		</item>
+            </taglist>
+	  </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>
+	  More <c><anno>Option</anno></c>s may be added in the future.
+	</p>
+	<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,
+	  already had been canceled, or because <c><anno>TimerRef</anno></c>
+	  never has corresponded to a timer. If the timer has expired,
+	  the timeout message has been sent, but it does not tell you
+	  whether or not it has arrived at its destination yet. When the
+	  <c><anno>Result</anno></c> is an integer, it represents the
+	  time in milli-seconds left until 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. If this is the case, communication
+	    with the timer service will take much longer time than if it
+	    is located locally. If the calling process is in critical
+	    path, and can do other things while waiting for the result
+	    of this operation, or is not interested in the result of
+	    the operation, you want to use the <c>{async, true}</c>
+	    option. If using the <c>{async, false}</c> option, the calling
+	    process will be blocked until the operation has been
+	    performed.
+	  </p>
+	</note>
         <p>See also 
           <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/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>
@@ -596,7 +635,7 @@
       <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>
+	[])</c></seealso>.</p>
       </desc>
     </func>
     <func>
@@ -4548,37 +4587,60 @@ os_prompt% </pre>
       <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>
+	  Read the state of a timer that has been created by either
+	  <seealso marker="#start_timer/4"><c>erlang:start_timer()</c></seealso>,
+	  or <seealso marker="#send_after/4"><c>erlang:send_after()</c></seealso>.
+	  <c><anno>TimerRef</anno></c> identifies the timer, and
+	  was returned by the BIF that created the timer.
+	</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>
+	    <p>
+	      Asynchronous request for state information. <c>Async</c>
+	      defaults to <c>false</c> which will cause the operation
+	      to be performed synchronously. In this case, the <c>Result</c>
+	      will be returned by <c>erlang:read_timer()</c>. When
+	      <c>Async</c> is set to <c>true</c>, <c>erlang:read_timer()</c>
+	      will send an asynchronous request for the state information
+	      to the 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>erlang: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>
+	  More <c><anno>Option</anno></c>s may be added in the future.
+	</p>
+	<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,
+	  had been canceled, or because <c><anno>TimerRef</anno></c>
+	  never has corresponded to a timer. If the timer has expired,
+	  the timeout message has been sent, but it does not tell you
+	  whether or not it has arrived at its destination yet. When the
+	  <c><anno>Result</anno></c> is an integer, it represents the
+	  time in milli-seconds left until 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. If this is the case, communication
+	    with the timer service will take much longer time than if it
+	    is located locally. 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. If using the <c>{async, false}</c> option, the calling
+	    process will be blocked until the operation has been
+	    performed.
+	  </p>
+	</note>
         <p>See also 
           <seealso marker="#send_after/4"><c>erlang:send_after/4</c></seealso>,
           <seealso marker="#start_timer/4"><c>erlang:start_timer/4</c></seealso>,
@@ -4592,7 +4654,7 @@ os_prompt% </pre>
       <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>
+	[])</c></seealso>.</p>
       </desc>
     </func>
     <func>
@@ -4744,48 +4806,14 @@ true</pre>
       <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>
+        <p>
+	  Starts a timer. When the timer expires, the message
+          <c><anno>Msg</anno></c> will be sent to the process
+	  identified by <c><anno>Dest</anno></c>. Appart from
+	  the format of the message sent to
+	  <c><anno>Dest</anno></c> when the timer expires
+	  <c>erlang:send_after/4</c> works exactly as
+	  <seealso marker="#start_timer/4"><c>erlang:start_timer/4</c></seealso>.</p>
       </desc>
     </func>
     <func>
@@ -4793,36 +4821,8 @@ true</pre>
       <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>
-      <desc>
-        <p>Starts a timer which will send the message <c>Msg</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>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/3">erlang:start_timer/3</seealso>,
-          <seealso marker="#cancel_timer/2">erlang:cancel_timer/2</seealso>,
-          and
-          <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>
+	<seealso marker="#send_after/4"><c>erlang:send_after(<anno>Time</anno>,
+	<anno>Dest</anno>, <anno>Msg</anno>, [])</c></seealso>.</p>
       </desc>
     </func>
     <func>
@@ -5231,41 +5231,59 @@ true</pre>
       <name name="start_timer" arity="4"/>
       <fsummary>Start a timer</fsummary>
       <desc>
-        <p>Starts a timer. When the timer expires, the message
+        <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>
+	  will be sent to the process identified by
+	  <c><anno>Dest</anno></c>.
+	</p>
+	<p>Currently available <c><anno>Option</anno></c>s:</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>
+	    <p>
+	      Absolute <c><anno>Time</anno></c> value. <c>Abs</c>
+	      defaults to <c>false</c> which means that 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 set to
+	      <c>true</c>, the <c><anno>Time</anno></c> value will
+	      be interpreted as an absolute Erlang monotonic time of
+	      milli-seconds
+	      <seealso marker="#type_time_unit">time unit</seealso>.
+	    </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>
+	  More <c><anno>Option</anno></c>s may be added in the future.
+	</p>
+	<p>
+	  The absolute point in time that the timer is set to expire on
+	  has to be in the interval
+	  <c>[</c><seealso marker="#system_info_start_time"><c>erlang:system_info(start_time)</c></seealso><c>,
+	  </c><seealso marker="#system_info_end_time"><c>erlang:system_info(end_time)</c></seealso><c>]</c>.
+	  Further, if a relative time is specified, the <c><anno>Time</anno></c> value
+	  is not allowed to be negative.
+	</p>
+	<p>
+	  If <c><anno>Dest</anno></c> is a <c>pid()</c>, it has to
+	  be a <c>pid()</c> of a process created on the current
+	  runtime system instance. This process may or may not
+	  have terminated. If <c><anno>Dest</anno></c> is an
+	  <c>atom()</c>, it will be interpreted as the name of a
+	  locally registered process. The process referred to by the
+	  name is looked up at the time of timer expiration. 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="#send_after/4"><c>erlang:send_after/4</c></seealso>,
           <seealso marker="#cancel_timer/2"><c>erlang:cancel_timer/2</c></seealso>,
@@ -5281,7 +5299,7 @@ true</pre>
       <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>
+	<anno>Dest</anno>, <anno>Msg</anno>, [])</c></seealso>.</p>
       </desc>
     </func>
     <func>
@@ -6845,7 +6863,9 @@ ok
 	  <item><p>The <seealso marker="#monotonic_time/0">Erlang monotonic
 	  time</seealso> in <c>native</c>
 	  <seealso marker="#type_time_unit">time unit</seealso> at the
-	  time when current Erlang runtime system instance started.</p></item>
+	  time when current Erlang runtime system instance started. See also
+	  <seealso marker="#system_info_end_time"><c>erlang:system_info(end_time)</c></seealso>.
+	  </p></item>
           <tag><c>system_version</c></tag>
           <item>
             <p>Returns a string containing version number and