Merge branch 'rickard/time_api/OTP-11997'

* rickard/time_api/OTP-11997:
  Better OS system time implementation
  Documentation adjustments
  Fix zero timout timers
  erts_sys_hrtime() for lcnt
  Better support for poor os monotonic sources

Conflicts:
	erts/preloaded/ebin/erlang.beam

2 files changed, 123 insertions, 17 deletions

diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 880c294c73..ba5f80a9c1 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -110,10 +110,17 @@
 	  <note>
 	    <p>The value of the <c>native</c> time unit gives
 	    you more or less no information at all about the
-	    quality of time values. It sets an upper bound for
-	    the resolution as well as for the precision, but it
-	    gives absolutely no information at all about the
-	    accuracy.</p>
+	    quality of time values. It sets a limit for
+	    the
+	    <seealso marker="time_correction#Time_Resolution">resolution</seealso>
+	    as well as for the
+	    <seealso marker="time_correction#Time_Precision">precision</seealso>
+	    of time values,
+	    but it gives absolutely no information at all about the
+	    <seealso marker="time_correction#Time_Accuracy">accuracy</seealso>
+	    of time values. The resolution of the <c>native</c> time
+	    unit and the resolution of time values may differ
+	    significantly.</p>
 	  </note>
 	  </item>
 
@@ -6038,6 +6045,8 @@ ok
       <name name="system_info" arity="1" clause_i="62"/>
       <name name="system_info" arity="1" clause_i="63"/>
       <name name="system_info" arity="1" clause_i="64"/>
+      <name name="system_info" arity="1" clause_i="65"/>
+      <name name="system_info" arity="1" clause_i="66"/>
       <fsummary>Information about the system</fsummary>
       <desc>
         <p>Returns various information about the current system
@@ -6449,20 +6458,33 @@ ok
 	      <c>Function</c>.</p></item>
 
 	      <tag><c>{resolution, OsMonotonicTimeResolution}</c></tag>
-	      <item><p>Highest possible resolution of current
-	      OS monotonic time source as parts per second. If
-	      no resolution information can be retreived from
-	      the OS, <c>OsMonotonicTimeResolution</c> will be
+	      <item><p>Highest possible
+	      <seealso marker="time_correction#Time_Resolution">resolution</seealso>
+	      of current OS monotonic time source as parts per
+	      second. If no resolution information can be retreived
+	      from the OS, <c>OsMonotonicTimeResolution</c> will be
 	      set to the resolution of the time unit of
 	      <c>Function</c>s return value. That is, the actual
 	      resolution may be lower than
 	      <c>OsMonotonicTimeResolution</c>. Also note that
 	      the resolution does not say anything about the
-	      accuracy, and that the precision might not align
-	      with the resolution. You do, however, know that the
-	      precision won't be higher than
+	      <seealso marker="time_correction#Time_Accuracy">accuracy</seealso>,
+	      and that the
+	      <seealso marker="time_correction#Time_Precision">precision</seealso>
+	      might not align with the resolution. You do,
+	      however, know that the precision won't be
+	      better than
 	      <c>OsMonotonicTimeResolution</c>.</p></item>
 
+	      <tag><c>{extended, Extended}</c></tag>
+	      <item><p><c>Extended</c> equals <c>yes</c> if
+	      the range of time values has been extended;
+	      otherwise, <c>Extended</c> equals <c>no</c>. The
+	      range needs to be extended if <c>Function</c>
+	      returns values that wrap fast. This typically
+	      is the case when the return value is a 32-bit
+	      value.</p></item>
+
 	      <tag><c>{parallel, Parallel}</c></tag>
 	      <item><p><c>Parallel</c> equals <c>yes</c> if
 	      <c>Function</c> is called in parallel from multiple
@@ -6476,6 +6498,59 @@ ok
 	      <seealso marker="#type_time_unit">time unit</seealso>.</p></item>
 	    </taglist>
           </item>
+          <tag><marker id="system_info_os_system_time_source"><c>os_system_time_source</c></marker></tag>
+          <item>
+            <p>Returns a list containing information about the source of
+	    <seealso marker="erts:time_correction#OS_System_Time">OS
+	    system time</seealso> that is used by the runtime system.</p>
+	    <p>The list contains two-tuples with <c>Key</c>s
+	    as first element, and <c>Value</c>s as second element. The
+	    order if these tuples is undefined. Currently the following
+	    tuples may be part of the list, but more tuples may be
+	    introduced in the future:</p>
+	    <taglist>
+	      <tag><c>{function, Function}</c></tag>
+	      <item><p><c>Function</c> is the name of the funcion
+	      used.</p></item>
+
+	      <tag><c>{clock_id, ClockId}</c></tag>
+	      <item><p>This tuple only exist if <c>Function</c>
+	      can be used with different clocks. <c>ClockId</c>
+	      corresponds to the clock identifer used when calling
+	      <c>Function</c>.</p></item>
+
+	      <tag><c>{resolution, OsSystemTimeResolution}</c></tag>
+	      <item><p>Highest possible
+	      <seealso marker="time_correction#Time_Resolution">resolution</seealso>
+	      of current OS system time source as parts per
+	      second. If no resolution information can be retreived
+	      from the OS, <c>OsSystemTimeResolution</c> will be
+	      set to the resolution of the time unit of
+	      <c>Function</c>s return value. That is, the actual
+	      resolution may be lower than
+	      <c>OsSystemTimeResolution</c>. Also note that
+	      the resolution does not say anything about the
+	      <seealso marker="time_correction#Time_Accuracy">accuracy</seealso>,
+	      and that the
+	      <seealso marker="time_correction#Time_Precision">precision</seealso>
+	      might not align with the resolution. You do,
+	      however, know that the precision won't be
+	      better than
+	      <c>OsSystemTimeResolution</c>.</p></item>
+
+	      <tag><c>{parallel, Parallel}</c></tag>
+	      <item><p><c>Parallel</c> equals <c>yes</c> if
+	      <c>Function</c> is called in parallel from multiple
+	      threads. If it is not called in parallel, because
+	      calls needs to be serialized, <c>Parallel</c> equals
+	      <c>no</c>.</p></item>
+
+	      <tag><c>{time, OsSystemTime}</c></tag>
+	      <item><p><c>OsSystemTime</c> equals current OS
+	      system time in <c>native</c>
+	      <seealso marker="#type_time_unit">time unit</seealso>.</p></item>
+	    </taglist>
+          </item>
 	  <tag><marker id="system_info_port_parallelism"><c>port_parallelism</c></marker></tag>
 	  <item><p>Returns the default port parallelism scheduling hint used.
 	  For more information see the
diff --git a/erts/doc/src/time_correction.xml b/erts/doc/src/time_correction.xml
index 3bc3d04186..979a37d7ff 100644
--- a/erts/doc/src/time_correction.xml
+++ b/erts/doc/src/time_correction.xml
@@ -114,6 +114,29 @@
       happened yet), POSIX time would make a one second leap forward.</p>
     </section>
 
+    <marker id="Time_Resolution"/>
+    <section>
+      <title>Time Resolution</title>
+      <p>The shortest time interval that can be distinguished when
+      reading time values.</p>
+    </section>
+
+    <marker id="Time_Precision"/>
+    <section>
+      <title>Time Precision</title>
+      <p>The shortest time interval that can be be distinguished
+      repeatedly and reliably when reading time values. Precision
+      is limited by the
+      <seealso marker="#Time_Resolution">resolution</seealso>, but
+      resolution and precision might differ significantly.</p>
+    </section>
+
+    <marker id="Time_Accuracy"/>
+    <section>
+      <title>Time Accuracy</title>
+      <p>The correctness of time values.</p>
+    </section>
+
     <marker id="OS_System_Time"/>
     <section>
       <title>OS System Time</title>
@@ -124,7 +147,9 @@
       This may or may not be an accurate view of POSIX time. This time
       may typically be adjusted both backwards and forwards without
       limitation. That is, huge leaps both backwards and forwards in time
-      may be observed.</p>
+      may be observed. You can get information about the Erlang runtime
+      system's source of OS system time by calling
+      <seealso marker="erlang#system_info_os_system_time_source"><c>erlang:system_info(os_system_time_source)</c></seealso>.</p>
     </section>
 
     <marker id="OS_Monotonic_Time"/>
@@ -138,7 +163,9 @@
       point in time that is not connected to
       <seealso marker="#OS_System_Time">OS system time</seealso>. Note that
       this type of time is not necessarily provided by all operating
-      systems.</p>
+      systems. You can get information about the Erlang runtime
+      system's source of OS monotonic time by calling
+      <seealso marker="erlang#system_info_os_monotonic_time_source"><c>erlang:system_info(os_monotonic_time_source)</c></seealso>.</p>
     </section>
 
     <marker id="Erlang_System_Time"/>
@@ -162,8 +189,10 @@
       Erlang runtime system. The Erlang monotonic time increase since
       some unspecified point in time. It can be retrieved by calling
       <seealso marker="erlang#monotonic_time/0"><c>erlang:monotonic_time()</c></seealso>.
-      The accuracy, and precision of Erlang monotonic time heavily
-      depends on the accuracy and precision of
+      The
+      <seealso marker="#Time_Accuracy">accuracy</seealso>, and
+      <seealso marker="#Time_Precision">precision</seealso> of Erlang
+      monotonic time heavily depends on the accuracy and precision of
       <seealso marker="#OS_Monotonic_Time">OS monotonic time</seealso>,
       the accuracy and precision of
       <seealso marker="#OS_System_Time">OS system time</seealso> as well
@@ -572,6 +601,7 @@
       <item><p><seealso marker="erlang#monitor/2"><c>erlang:monitor(time_offset, clock_service)</c></seealso></p></item>
       <item><p><seealso marker="erlang#system_flag_time_offset"><c>erlang:system_flag(time_offset, finalize)</c></seealso></p></item>
       <item><p><seealso marker="erlang#system_info_os_monotonic_time_source"><c>erlang:system_info(os_monotonic_time_source)</c></seealso></p></item>
+      <item><p><seealso marker="erlang#system_info_os_system_time_source"><c>erlang:system_info(os_system_time_source)</c></seealso></p></item>
       <item><p><seealso marker="erlang#system_info_time_offset"><c>erlang:system_info(time_offset)</c></seealso></p></item>
       <item><p><seealso marker="erlang#system_info_time_warp_mode"><c>erlang:system_info(time_warp_mode)</c></seealso></p></item>
       <item><p><seealso marker="erlang#system_info_time_correction"><c>erlang:system_info(time_correction)</c></seealso></p></item>
@@ -827,8 +857,9 @@ EventTag = {Time, UMI}</code>
     when it is not available. Fortunately almost all of the new
     API can easily be implemented using existing primitives
     (except for
-    <seealso marker="erlang#system_info_start_time"><c>erlang:system_info(start_time)</c></seealso>, and
-    <seealso marker="erlang#system_info_os_monotonic_time_source"><c>erlang:system_info(os_monotonic_time_source)</c></seealso>).
+    <seealso marker="erlang#system_info_start_time"><c>erlang:system_info(start_time)</c></seealso>,
+    <seealso marker="erlang#system_info_os_monotonic_time_source"><c>erlang:system_info(os_monotonic_time_source)</c></seealso>, and
+    <seealso marker="erlang#system_info_os_system_time_source"><c>erlang:system_info(os_system_time_source)</c></seealso>).
     By wrapping the API with functions that fall back on
     <c>erlang:now/0</c> when the new API is not available,
     and using these wrappers instead of using the API directly