Merge branch 'rickard/monotonic-time-improvements/OTP-13222' into maint

* rickard/monotonic-time-improvements/OTP-13222:
  Introduce time management in native APIs
  Introduce time warp safe replacement for safe_fixed option
  Introduce time warp safe trace timestamp formats

3 files changed, 284 insertions, 4 deletions

diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml
index e717fc0c4e..e338e95938 100644
--- a/erts/doc/src/erl_driver.xml
+++ b/erts/doc/src/erl_driver.xml
@@ -347,6 +347,16 @@
 	  the driver does not handle sizes that overflow an <c>int</c>
 	  all will work as before.</p>
       </item>
+      <tag><marker id="time_measurement"/>Time Measurement</tag>
+      <item><p>Support for time measurement in drivers:
+      <list>
+	<item><seealso marker="#ErlDrvTime"><c>ErlDrvTime</c></seealso></item>
+	<item><seealso marker="#ErlDrvTimeUnit"><c>ErlDrvTimeUnit</c></seealso></item>
+	<item><seealso marker="#erl_drv_monotonic_time"><c>erl_drv_monotonic_time()</c></seealso></item>
+	<item><seealso marker="#erl_drv_time_offset"><c>erl_drv_time_offset()</c></seealso></item>
+	<item><seealso marker="#erl_drv_convert_time_unit"><c>erl_drv_convert_time_unit()</c></seealso></item>
+      </list></p>
+      </item>
     </taglist>
   </section>
 
@@ -860,6 +870,24 @@ typedef struct ErlIOVec {
 	   <seealso marker="#erl_drv_tsd_get">erl_drv_tsd_get()</seealso>.
 	</p>
       </item>
+      <tag><marker id="ErlDrvTime"/>ErlDrvTime</tag>
+      <item>
+        <p>A signed 64-bit integer type for representation of time.</p>
+      </item>
+      <tag><marker id="ErlDrvTimeUnit"/>ErlDrvTimeUnit</tag>
+      <item>
+        <p>An enumeration of time units supported by the driver API:</p>
+	<taglist>
+	  <tag><c>ERL_DRV_SEC</c></tag>
+	  <item><p>Seconds</p></item>
+	  <tag><c>ERL_DRV_MSEC</c></tag>
+	  <item><p>Milliseconds</p></item>
+	  <tag><c>ERL_DRV_USEC</c></tag>
+	  <item><p>Microseconds</p></item>
+	  <tag><c>ERL_DRV_NSEC</c></tag>
+	  <item><p>Nanoseconds</p></item>
+	</taglist>
+      </item>
      </taglist>
    </section>
 
@@ -1023,6 +1051,10 @@ typedef struct ErlIOVec {
       <fsummary>Read a system timestamp</fsummary>
       <desc>
         <marker id="driver_get_now"></marker>
+	<warning><p><em>This function is deprecated! Do not use it!</em>
+	Use the documented 
+	<seealso marker="#time_measurement">time measurement functionality</seealso>
+	instead.</p></warning>
         <p>This function reads a timestamp into the memory pointed to by
           the parameter <c>now</c>. See the description of <seealso marker="#ErlDrvNowData">ErlDrvNowData</seealso> for
           specification of its fields.  </p>
@@ -2997,6 +3029,86 @@ ERL_DRV_MAP          int sz
 		</desc>
 	</func>
 
+	<func>
+	  <name><ret>ErlDrvTime</ret><nametext>erl_drv_monotonic_time(ErlDrvTimeUnit time_unit)</nametext></name>
+	  <fsummary>Get Erlang Monotonic Time</fsummary>
+	  <desc>
+	    <marker id="erl_drv_monotonic_time"></marker>
+	    <p>Arguments:</p>
+	    <taglist>
+	      <tag><c>time_unit</c></tag>
+	      <item>Time unit of returned value.</item>
+	    </taglist>
+	    <p>
+	      Returns
+	      <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang
+	      monotonic time</seealso>. Note that it is not uncommon with
+	      negative values.
+	    </p>
+	    <p>Returns <c>ERL_DRV_TIME_ERROR</c> if called with an invalid
+	    time unit argument, or if called from a thread that is not a
+	    scheduler thread.</p>
+	    <p>See also:</p>
+	    <list>
+	      <item><seealso marker="#ErlDrvTime"><c>ErlDrvTime</c></seealso></item>
+	      <item><seealso marker="#ErlDrvTimeUnit"><c>ErlDrvTimeUnit</c></seealso></item>
+	    </list>
+	  </desc>
+	</func>
+
+	<func>
+	  <name><ret>ErlDrvTime</ret><nametext>erl_drv_time_offset(ErlDrvTimeUnit time_unit)</nametext></name>
+	  <fsummary>Get current Time Offset</fsummary>
+	  <desc>
+	    <marker id="erl_drv_time_offset"></marker>
+	    <p>Arguments:</p>
+	    <taglist>
+	      <tag><c>time_unit</c></tag>
+	      <item>Time unit of returned value.</item>
+	    </taglist>
+	    <p>Returns the current time offset between
+	    <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang monotonic time</seealso>
+	    and
+	    <seealso marker="time_correction#Erlang_System_Time">Erlang system time</seealso>
+	    converted into the <c>time_unit</c> passed as argument.</p>
+	    <p>Returns <c>ERL_DRV_TIME_ERROR</c> if called with an invalid
+	    time unit argument, or if called from a thread that is not a
+	    scheduler thread.</p>
+	    <p>See also:</p>
+	    <list>
+	      <item><seealso marker="#ErlDrvTime"><c>ErlDrvTime</c></seealso></item>
+	      <item><seealso marker="#ErlDrvTimeUnit"><c>ErlDrvTimeUnit</c></seealso></item>
+	    </list>
+	  </desc>
+	</func>
+
+	<func>
+	  <name><ret>ErlDrvTime</ret><nametext>erl_drv_convert_time_unit(ErlDrvTime val, ErlDrvTimeUnit from, ErlDrvTimeUnit to)</nametext></name>
+	  <fsummary>Convert time unit of a time value</fsummary>
+	  <desc>
+	    <marker id="erl_drv_convert_time_unit"></marker>
+	    <p>Arguments:</p>
+	    <taglist>
+	      <tag><c>val</c></tag>
+	      <item>Value to convert time unit for.</item>
+	      <tag><c>from</c></tag>
+	      <item>Time unit of <c>val</c>.</item>
+	      <tag><c>to</c></tag>
+	      <item>Time unit of returned value.</item>
+	    </taglist>
+	    <p>Converts the <c>val</c> value of time unit <c>from</c> to
+	    the corresponding value of time unit <c>to</c>. The result is
+	    rounded using the floor function.</p>
+	    <p>Returns <c>ERL_DRV_TIME_ERROR</c> if called with an invalid
+	    time unit argument.</p>
+	    <p>See also:</p>
+	    <list>
+	      <item><seealso marker="#ErlDrvTime"><c>ErlDrvTime</c></seealso></item>
+	      <item><seealso marker="#ErlDrvTimeUnit"><c>ErlDrvTimeUnit</c></seealso></item>
+	    </list>
+	  </desc>
+	</func>
+
   </funcs>
   <section>
     <title>SEE ALSO</title>
diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml
index 2d8706169f..420c9fea38 100644
--- a/erts/doc/src/erl_nif.xml
+++ b/erts/doc/src/erl_nif.xml
@@ -317,6 +317,17 @@ ok
       libraries might however fail if deprecated features are used.
       </p></item>
 
+      <tag><marker id="time_measurement"/>Time Measurement</tag>
+      <item><p>Support for time measurement in NIF libraries:
+      <list>
+	<item><seealso marker="#ErlNifTime"><c>ErlNifTime</c></seealso></item>
+	<item><seealso marker="#ErlNifTimeUnit"><c>ErlNifTimeUnit</c></seealso></item>
+	<item><seealso marker="#enif_monotonic_time"><c>enif_monotonic_time()</c></seealso></item>
+	<item><seealso marker="#enif_time_offset"><c>enif_time_offset()</c></seealso></item>
+	<item><seealso marker="#enif_convert_time_unit"><c>enif_convert_time_unit()</c></seealso></item>
+      </list></p>
+      </item>
+
       <tag>Long-running NIFs</tag>
       <item><p><marker id="dirty_nifs"/>Native functions
       <seealso marker="#lengthy_work">
@@ -560,6 +571,25 @@ typedef enum {
                <item><p>A native signed 64-bit integer type.</p></item>
               <tag><marker id="ErlNifUInt64"/>ErlNifUInt64</tag>
                <item><p>A native unsigned 64-bit integer type.</p></item>
+	       
+      <tag><marker id="ErlNifTime"/>ErlNifTime</tag>
+      <item>
+        <p>A signed 64-bit integer type for representation of time.</p>
+      </item>
+      <tag><marker id="ErlNifTimeUnit"/>ErlNifTimeUnit</tag>
+      <item>
+        <p>An enumeration of time units supported by the NIF API:</p>
+	<taglist>
+	  <tag><c>ERL_NIF_SEC</c></tag>
+	  <item><p>Seconds</p></item>
+	  <tag><c>ERL_NIF_MSEC</c></tag>
+	  <item><p>Milliseconds</p></item>
+	  <tag><c>ERL_NIF_USEC</c></tag>
+	  <item><p>Microseconds</p></item>
+	  <tag><c>ERL_NIF_NSEC</c></tag>
+	  <item><p>Nanoseconds</p></item>
+	</taglist>
+      </item>
 
     </taglist>
   </section>
@@ -1486,6 +1516,88 @@ enif_map_iterator_destroy(env, &amp;iter);
     <desc><p>Same as <seealso marker="erl_driver#erl_drv_tsd_set">erl_drv_tsd_set</seealso>.
           </p></desc>
     </func>
+
+
+    <func>
+      <name><ret>ErlNifTime</ret><nametext>enif_monotonic_time(ErlNifTimeUnit time_unit)</nametext></name>
+      <fsummary>Get Erlang Monotonic Time</fsummary>
+      <desc>
+	<marker id="enif_monotonic_time"></marker>
+	<p>Arguments:</p>
+	<taglist>
+	  <tag><c>time_unit</c></tag>
+	  <item>Time unit of returned value.</item>
+	</taglist>
+	<p>
+	  Returns
+	  <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang
+	  monotonic time</seealso>. Note that it is not uncommon with
+	  negative values.
+	</p>
+	<p>Returns <c>ERL_NIF_TIME_ERROR</c> if called with an invalid
+	time unit argument, or if called from a thread that is not a
+	scheduler thread.</p>
+	<p>See also:</p>
+	<list>
+	  <item><seealso marker="#ErlNifTime"><c>ErlNifTime</c></seealso></item>
+	  <item><seealso marker="#ErlNifTimeUnit"><c>ErlNifTimeUnit</c></seealso></item>
+	</list>
+      </desc>
+    </func>
+
+    <func>
+      <name><ret>ErlNifTime</ret><nametext>enif_time_offset(ErlNifTimeUnit time_unit)</nametext></name>
+      <fsummary>Get current Time Offset</fsummary>
+      <desc>
+	<marker id="enif_time_offset"></marker>
+	<p>Arguments:</p>
+	<taglist>
+	  <tag><c>time_unit</c></tag>
+	  <item>Time unit of returned value.</item>
+	</taglist>
+	<p>Returns the current time offset between
+	<seealso marker="time_correction#Erlang_Monotonic_Time">Erlang monotonic time</seealso>
+	and
+	<seealso marker="time_correction#Erlang_System_Time">Erlang system time</seealso>
+	converted into the <c>time_unit</c> passed as argument.</p>
+	<p>Returns <c>ERL_NIF_TIME_ERROR</c> if called with an invalid
+	time unit argument, or if called from a thread that is not a
+	scheduler thread.</p>
+	<p>See also:</p>
+	<list>
+	  <item><seealso marker="#ErlNifTime"><c>ErlNifTime</c></seealso></item>
+	  <item><seealso marker="#ErlNifTimeUnit"><c>ErlNifTimeUnit</c></seealso></item>
+	</list>
+      </desc>
+    </func>
+
+    <func>
+      <name><ret>ErlNifTime</ret><nametext>enif_convert_time_unit(ErlNifTime val, ErlNifTimeUnit from, ErlNifTimeUnit to)</nametext></name>
+      <fsummary>Convert time unit of a time value</fsummary>
+      <desc>
+	<marker id="enif_convert_time_unit"></marker>
+	<p>Arguments:</p>
+	<taglist>
+	  <tag><c>val</c></tag>
+	  <item>Value to convert time unit for.</item>
+	  <tag><c>from</c></tag>
+	  <item>Time unit of <c>val</c>.</item>
+	  <tag><c>to</c></tag>
+	  <item>Time unit of returned value.</item>
+	</taglist>
+	<p>Converts the <c>val</c> value of time unit <c>from</c> to
+	the corresponding value of time unit <c>to</c>. The result is
+	rounded using the floor function.</p>
+	<p>Returns <c>ERL_NIF_TIME_ERROR</c> if called with an invalid
+	time unit argument.</p>
+	<p>See also:</p>
+	<list>
+	  <item><seealso marker="#ErlNifTime"><c>ErlNifTime</c></seealso></item>
+	  <item><seealso marker="#ErlNifTimeUnit"><c>ErlNifTimeUnit</c></seealso></item>
+	</list>
+      </desc>
+    </func>
+
   </funcs>
   <section>
     <title>SEE ALSO</title>
diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 13b16d1ed3..964601f195 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -7739,6 +7739,13 @@ ok
              <c>inactive</c>, and later <c>active</c> when the port
 	     callback returns.</p>
           </item>
+          <tag><c>monotonic_timestamp</c></tag>
+          <item>
+            <p>Timestamps in profile messages will use
+	    <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang
+	    monotonic time</seealso>. The time-stamp (Ts) has the same
+	    format and value as produced by <c>erlang:monotonic_time()</c>.</p>
+          </item>
           <tag><c>runnable_procs</c></tag>
           <item>
           <p>If a process is put into or removed from the run queue, a
@@ -7759,6 +7766,25 @@ ok
              <c>{profile, scheduler, Id, State, NoScheds, Ts}</c>, is
              sent to <c><anno>ProfilerPid</anno></c>.</p>
           </item>
+          <tag><c>strict_monotonic_timestamp</c></tag>
+          <item>
+            <p>Timestamps in profile messages will consisting of
+	    <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang
+	    monotonic time</seealso> and a monotonically increasing
+	    integer. The time-stamp (Ts) has the same format and value
+	    as produced by <c>{erlang:monotonic_time(),
+	    erlang:unique_integer([monotonic])}</c>.</p>
+          </item>
+          <tag><c>timestamp</c></tag>
+          <item>
+            <p>Timestamps in profile messages will include a
+            time-stamp (Ts) that has the same form as returned by
+            <c>erlang:now()</c>. This is also the default if no
+	    timestamp flag is given. If <c>cpu_timestamp</c> has
+	    been enabled via <c>erlang:trace/3</c>, this will also
+	    effect the timestamp produced in profiling messages
+	    when <c>timestamp</c> flag is enabled.</p>
+          </item>
         </taglist>
         <note><p><c>erlang:system_profile</c> is considered experimental
           and its behavior can change in a future release.</p>
@@ -8118,7 +8144,10 @@ timestamp() ->
           <tag><c>cpu_timestamp</c></tag>
           <item>
             <p>A global trace flag for the Erlang node that makes all
-              trace time-stamps to be in CPU time, not wall clock time.
+              trace time-stamps using the <c>timestamp</c> flag to be
+	      in CPU time, not wall clock time. That is, <c>cpu_timestamp</c>
+	      will not be used if <c>monotonic_timestamp</c>, or
+	      <c>strict_monotonic_timestamp</c> is enabled.
               Only allowed with <c>PidSpec==all</c>. If the host
               machine OS does not support high-resolution
               CPU time measurements, <c>trace/3</c> exits with
@@ -8126,6 +8155,26 @@ timestamp() ->
               not synchronize this value across cores, so be prepared
               that time might seem to go backwards when using this option.</p>
           </item>
+          <tag><c>monotonic_timestamp</c></tag>
+          <item>
+            <p>Includes an
+	    <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang
+	    monotonic time</seealso> time-stamp in all trace messages. The
+            time-stamp (Ts) has the same format and value as produced by
+            <c>erlang:monotonic_time()</c>. This flag overrides
+	    the <c>cpu_timestamp</c> flag.</p>
+          </item>
+          <tag><c>strict_monotonic_timestamp</c></tag>
+          <item>
+            <p>Includes an timestamp consisting of
+	    <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang
+	    monotonic time</seealso> and a monotonically increasing
+	    integer in all trace messages. The time-stamp (Ts) has the
+	    same format and value as produced by
+            <c>{erlang:monotonic_time(),
+	    erlang:unique_integer([monotonic])}</c>. This flag overrides
+	    the <c>cpu_timestamp</c> flag.</p>
+          </item>
           <tag><c>arity</c></tag>
           <item>
             <p>Used with the <c>call</c> trace flag.
@@ -8172,9 +8221,16 @@ timestamp() ->
 	in the following list. <c>Pid</c> is the process identifier of the
 	traced process in which the traced event has occurred. The
 	third tuple element is the message tag.</p>
-        <p>If flag <c>timestamp</c> is given, the first tuple
-          element is <c>trace_ts</c> instead, and the time-stamp
-          is added last in the message tuple.</p>
+        <p>If flag <c>timestamp</c>, <c>strict_monotonic_timestamp</c>, or
+	<c>monotonic_timestamp</c> is given, the first tuple
+        element is <c>trace_ts</c> instead, and the time-stamp
+        is added as an extra element last in the message tuple. If
+	multiple timestamp flags are passed, <c>timestamp</c> has
+	precedence over <c>strict_monotonic_timestamp</c> which
+	in turn has precedence over <c>monotonic_timestamp</c>. All
+	timestamp flags are remembered, so if two are passed
+	and the one with highest precedence later is disabled
+	the other one will become active.</p>
         <marker id="trace_3_trace_messages"></marker>
         <taglist>
           <tag><c>{trace, Pid, 'receive', Msg}</c></tag>