Merge branch 'rickard/time_api/OTP-11997'

* rickard/time_api/OTP-11997: (22 commits)
  Update primary bootstrap
  inets: Suppress deprecated warning on erlang:now/0
  inets: Cleanup of multiple copies of functions Add inets_lib with common functions used by multiple modules
  inets: Update comments
  Suppress deprecated warning on erlang:now/0
  Use new time API and be back-compatible in inets Remove unused functions and removed redundant test
  asn1 test SUITE: Eliminate use of now/0
  Disable deprecated warning on erlang:now/0 in diameter_lib
  Use new time API and be back-compatible in ssh
  Replace all calls to now/0 in CT with new time API functions
  test_server: Replace usage of erlang:now() with usage of new API
  Replace usage of erlang:now() with usage of new API
  Replace usage of erlang:now() with usage of new API
  Replace usage of erlang:now() with usage of new API
  Replace usage of erlang:now() with usage of new API
  otp_SUITE: Warn for calls to erlang:now/0
  Replace usage of erlang:now() with usage of new API
  Multiple timer wheels
  Erlang based BIF timer implementation for scalability
  Implement ethread events with timeout
  ...

Conflicts:
	bootstrap/bin/start.boot
	bootstrap/bin/start_clean.boot
	bootstrap/lib/compiler/ebin/beam_asm.beam
	bootstrap/lib/compiler/ebin/compile.beam
	bootstrap/lib/kernel/ebin/auth.beam
	bootstrap/lib/kernel/ebin/dist_util.beam
	bootstrap/lib/kernel/ebin/global.beam
	bootstrap/lib/kernel/ebin/hipe_unified_loader.beam
	bootstrap/lib/kernel/ebin/inet_db.beam
	bootstrap/lib/kernel/ebin/inet_dns.beam
	bootstrap/lib/kernel/ebin/inet_res.beam
	bootstrap/lib/kernel/ebin/os.beam
	bootstrap/lib/kernel/ebin/pg2.beam
	bootstrap/lib/stdlib/ebin/dets.beam
	bootstrap/lib/stdlib/ebin/dets_utils.beam
	bootstrap/lib/stdlib/ebin/erl_tar.beam
	bootstrap/lib/stdlib/ebin/escript.beam
	bootstrap/lib/stdlib/ebin/file_sorter.beam
	bootstrap/lib/stdlib/ebin/otp_internal.beam
	bootstrap/lib/stdlib/ebin/qlc.beam
	bootstrap/lib/stdlib/ebin/random.beam
	bootstrap/lib/stdlib/ebin/supervisor.beam
	bootstrap/lib/stdlib/ebin/timer.beam
	erts/aclocal.m4
	erts/emulator/beam/bif.c
	erts/emulator/beam/erl_bif_info.c
	erts/emulator/beam/erl_db_hash.c
	erts/emulator/beam/erl_init.c
	erts/emulator/beam/erl_process.h
	erts/emulator/beam/erl_thr_progress.c
	erts/emulator/beam/utils.c
	erts/emulator/sys/unix/sys.c
	erts/preloaded/ebin/erlang.beam
	erts/preloaded/ebin/erts_internal.beam
	erts/preloaded/ebin/init.beam
	erts/preloaded/src/erts_internal.erl
	lib/common_test/test/ct_hooks_SUITE_data/cth/tests/empty_cth.erl
	lib/diameter/src/base/diameter_lib.erl
	lib/kernel/src/os.erl
	lib/ssh/test/ssh_basic_SUITE.erl
	system/doc/efficiency_guide/advanced.xml

4 files changed, 1447 insertions, 300 deletions

diff --git a/erts/doc/src/Makefile b/erts/doc/src/Makefile
index e8b856c3ff..a83aa9b875 100644
--- a/erts/doc/src/Makefile
+++ b/erts/doc/src/Makefile
@@ -177,6 +177,8 @@ release_docs_spec: docs
 	$(INSTALL_DIR) "$(RELSYSDIR)/doc/html"
 	$(INSTALL_DATA) $(HTMLDIR)/* \
 		"$(RELSYSDIR)/doc/html"
+	$(INSTALL_DATA) $(ERL_TOP)/erts/example/time_compat.erl \
+		"$(RELSYSDIR)/doc/html"
 	$(INSTALL_DATA) $(INFO_FILE) "$(RELSYSDIR)"
 	$(INSTALL_DIR) "$(RELEASE_PATH)/man/man3"
 	$(INSTALL_DATA) $(MAN3DIR)/* "$(RELEASE_PATH)/man/man3"
diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml
index c25c9eeedb..ea94a4e82b 100644
--- a/erts/doc/src/erl.xml
+++ b/erts/doc/src/erl.xml
@@ -495,24 +495,35 @@
           <c><![CDATA[werl]]></c>, not <c><![CDATA[erl]]></c> (<c><![CDATA[oldshell]]></c>). Note also that
           <c><![CDATA[Ctrl-Break]]></c> is used instead of <c><![CDATA[Ctrl-C]]></c> on Windows.</p>
       </item>
-      <tag><marker id="+c"><c><![CDATA[+c]]></c></marker></tag>
-      <item>
-        <p>Disable compensation for sudden changes of system time.</p>
-        <p>Normally, <c><![CDATA[erlang:now/0]]></c> will not immediately reflect
-          sudden changes in the system time, in order to keep timers
-          (including <c><![CDATA[receive-after]]></c>) working. Instead, the time
-          maintained by <c><![CDATA[erlang:now/0]]></c> is slowly adjusted towards
-          the new system time. (Slowly means in one percent adjustments;
-          if the time is off by one minute, the time will be adjusted
-          in 100 minutes.)</p>
-        <p>When the <c><![CDATA[+c]]></c> option is given, this slow adjustment
-          will not take place. Instead <c><![CDATA[erlang:now/0]]></c> will always
-          reflect the current system time. Note that timers are based
-          on <c><![CDATA[erlang:now/0]]></c>. If the system time jumps, timers
-          then time out at the wrong time.</p>
-        <p><em>NOTE</em>: You can check whether the adjustment is enabled or
-          disabled by calling
-	  <seealso marker="erlang#system_info_tolerant_timeofday">erlang:system_info(tolerant_timeofday)</seealso>.</p>
+      <tag><marker id="+c"><c><![CDATA[+c true | false]]></c></marker></tag>
+      <item>
+        <p>Enable or disable
+	<seealso marker="time_correction#Time_Correction">time correction</seealso>:</p>
+	<taglist>
+	  <tag><c>true</c></tag>
+	  <item><p>Enable time correction. This is the default if
+	  time correction is supported on the specific platform.</p></item>
+
+	  <tag><c>false</c></tag>
+	  <item><p>Disable time correction.</p></item>
+	</taglist>
+	<p>For backwards compatibility, the boolean value can be omitted.
+	This is interpreted as <c>+c false</c>.
+	</p>
+      </item>
+      <tag><marker id="+C_"><c><![CDATA[+C no_time_warp | single_time_warp | multi_time_warp]]></c></marker></tag>
+      <item>
+        <p>Set
+	<seealso marker="time_correction#Time_Warp_Modes">time warp mode</seealso>:
+	</p>
+	<taglist>
+	  <tag><c>no_time_warp</c></tag>
+	  <item><p><seealso marker="time_correction#No_Time_Warp_Mode">No Time Warp Mode</seealso> (the default)</p></item>
+	  <tag><c>single_time_warp</c></tag>
+	  <item><p><seealso marker="time_correction#Single_Time_Warp_Mode">Single Time Warp Mode</seealso></p></item>
+	  <tag><c>multi_time_warp</c></tag>
+	  <item><p><seealso marker="time_correction#Multi_Time_Warp_Mode">Multi Time Warp Mode</seealso></p></item>
+	</taglist>
       </item>
       <tag><c><![CDATA[+d]]></c></tag>
       <item>
diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 6daa4b68a8..880c294c73 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -58,7 +58,71 @@
     </datatype>
     <datatype>
       <name name="timestamp"></name>
-      <desc><p>See <seealso marker="#now/0">now/0</seealso>.</p>
+      <desc><p>See <seealso marker="#timestamp/0">erlang:timestamp/0</seealso>.</p>
+      </desc>
+    </datatype>
+    <marker id="type_time_unit"/>
+    <datatype>
+      <name name="time_unit"></name>
+      <desc><p>Currently supported time unit representations:</p>
+        <taglist>
+	  <tag><c>PartsPerSecond :: integer() >= 1</c></tag>
+	  <item><p>Time unit expressed in parts per second. That is,
+	  the time unit equals <c>1/PartsPerSecond</c> second.</p></item>
+
+	  <tag><c>seconds</c></tag>
+	  <item><p>Symbolic representation of the time unit
+	  represented by the integer <c>1</c>.</p></item>
+
+	  <tag><c>milli_seconds</c></tag>
+	  <item><p>Symbolic representation of the time unit
+	  represented by the integer <c>1000</c>.</p></item>
+
+	  <tag><c>micro_seconds</c></tag>
+	  <item><p>Symbolic representation of the time unit
+	  represented by the integer <c>1000000</c>.</p></item>
+
+	  <tag><c>nano_seconds</c></tag>
+	  <item><p>Symbolic representation of the time unit
+	  represented by the integer <c>1000000000</c>.</p></item>
+
+	  <tag><c>native</c></tag>
+	  <item><p>Symbolic representation of the native time unit
+	  used by the Erlang runtime system.</p>
+
+	  <p>The <c>native</c> time unit is determined at
+	  runtime system start, and will remain the same until
+	  the runtime system terminates. If a runtime system
+	  is stopped and then started again (even on the same
+	  machine), the <c>native</c> time unit of the new
+	  runtime system instance may differ from the
+	  <c>native</c> time unit of the old runtime system
+	  instance.</p>
+
+	  <p>One can get an approximation of the <c>native</c>
+	  time unit by calling <c>erlang:convert_time_unit(1,
+	  seconds, native)</c>. The result equals the number
+	  of whole <c>native</c> time units per second. In case
+	  the number of <c>native</c> time units per second does
+	  not add up to a whole number, the result will be
+	  rounded downwards.</p>
+
+	  <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>
+	  </note>
+	  </item>
+
+	</taglist>
+
+	<p>The <c>time_unit/0</c> type may be extended. Use
+	<seealso marker="#convert_time_unit/3"><c>erlang:convert_time_unit/3</c></seealso>
+	in order to convert time values between time units.</p>
+
       </desc>
     </datatype>
   </datatypes>
@@ -585,6 +649,22 @@
       </desc>
     </func>
     <func>
+      <name name="convert_time_unit" arity="3"/>
+      <fsummary>Convert time unit of a time value</fsummary>
+      <desc>
+	<p>Converts the <c><anno>Time</anno></c> value of time unit
+	<c><anno>FromUnit</anno></c> to the corresponding
+	<c><anno>ConvertedTime</anno></c> value of time unit
+	<c><anno>ToUnit</anno></c>. The result is rounded
+	using the floor function.</p>
+
+	<warning><p>You may lose accuracy and precision when converting
+	between	time units. In order to minimize such loss, collect all
+	data at <c>native</c> time unit and do the conversion on the end
+	result.</p></warning>
+      </desc>
+    </func>
+    <func>
       <name name="crc32" arity="1"/>
       <fsummary>Compute crc32 (IEEE 802.3) checksum</fsummary>
       <desc>
@@ -2205,14 +2285,15 @@ os_prompt% </pre>
     </func>
     <func>
       <name name="make_ref" arity="0"/>
-      <fsummary>Return an almost unique reference</fsummary>
+      <fsummary>Return a unique reference</fsummary>
       <desc>
-        <p>Returns an almost unique reference.</p>
-        <p>The returned reference will re-occur after approximately 2^82
-          calls; therefore it is unique enough for practical purposes.</p>
-        <pre>
-> <input>make_ref().</input>
-#Ref&lt;0.0.0.135></pre>
+	<p>Return a <seealso marker="doc/efficiency_guide:advanced#unique_references">unique
+	reference</seealso>. The reference is unique among
+	connected nodes.</p>
+	<warning><p>Known issue: When a node is restarted multiple
+	times with the same node name, references created
+	on a newer node can be mistaken for a reference
+	created on an older node with the same node name.</p></warning>
       </desc>
     </func>
     <func>
@@ -2513,97 +2594,178 @@ os_prompt% </pre>
       </desc>
     </func>
     <func>
-      <name name="monitor" arity="2"/>
+      <name name="monitor" arity="2" clause_i="1"/>
+      <name name="monitor" arity="2" clause_i="2"/>
+      <type name="registered_name"/>
+      <type name="registered_process_identifier"/>
+      <type name="monitor_process_identifier"/>
       <fsummary>Start monitoring</fsummary>
       <desc>
-        <p>The calling process starts monitoring <c><anno>Item</anno></c> which is
-          an object of type <c><anno>Type</anno></c>.</p>
-        <p>Currently only processes can be monitored, i.e. the only
-          allowed <c><anno>Type</anno></c> is <c>process</c>, but other types may be
-          allowed in the future.</p>
-        <p><c><anno>Item</anno></c> can be:</p>
-        <taglist>
-          <tag><c>pid()</c></tag>
-          <item>
-            <p>The pid of the process to monitor.</p>
-          </item>
-          <tag><c>{RegName, Node}</c></tag>
-          <item>
-            <p>A tuple consisting of a registered name of a process and
-              a node name. The process residing on the node <c>Node</c>
-              with the registered name <c>RegName</c> will be monitored.</p>
-          </item>
-          <tag><c>RegName</c></tag>
-          <item>
-            <p>The process locally registered as <c>RegName</c> will be
-              monitored.</p>
-          </item>
-        </taglist>
-        <note>
-          <p>When a process is monitored by registered name, the process
-            that has the registered name at the time when
-            <c>monitor/2</c> is called will be monitored.
+	<p>Send a monitor request of type <c><anno>Type</anno></c> to the
+	entity identified by <c><anno>Item</anno></c>. The caller of
+	<c>monitor/2</c> will later be notified by a monitor message on the
+	following format if the monitored state is changed:</p>
+        <code type="none">{Tag, <anno>MonitorRef</anno>, <anno>Type</anno>, Object, Info}</code>
+	<note><p>The monitor request is an asynchronous signal. That is, it
+	takes time before the signal reach its destination.</p></note>
+	<p>Currently valid <c><anno>Type</anno></c>s:</p>
+	<taglist>
+	  <tag><marker id="monitor_process"/><c>process</c></tag>
+	  <item>
+	    <p>Monitor the existence of the process identified by
+	    <c><anno>Item</anno></c>. Currently valid
+	    <c><anno>Item</anno></c>s in combination with the
+	    <c>process <anno>Type</anno></c>:</p>
+            <taglist>
+              <tag><c>pid()</c></tag>
+              <item>
+		<p>The process identifier of the process to monitor.</p>
+              </item>
+              <tag><c>{RegisteredName, Node}</c></tag>
+              <item>
+		<p>A tuple consisting of a registered name of a process and
+		a node name. The process residing on the node <c>Node</c>
+		with the registered name <c>{RegisteredName, Node}</c> will
+		be monitored.</p>
+              </item>
+              <tag><c>RegisteredName</c></tag>
+              <item>
+		<p>The process locally registered as <c>RegisteredName</c>
+		will become monitored.</p>
+              </item>
+            </taglist>
+            <note><p>When a process is monitored by registered name, the
+	    process that has the registered name at the time when the
+            monitor request reach its destination will be monitored.
             The monitor will not be effected, if the registered name is
-            unregistered.</p>
-        </note>
-        <p>A <c>'DOWN'</c> message will be sent to the monitoring
-          process if <c><anno>Item</anno></c> dies, if <c><anno>Item</anno></c> does not exist,
-          or if the connection is lost to the node which <c><anno>Item</anno></c>
-          resides on. A <c>'DOWN'</c> message has the following pattern:</p>
-        <code type="none">
-{'DOWN', MonitorRef, Type, Object, Info}</code>
-        <p>where <c>MonitorRef</c> and <c>Type</c> are the same as
-          described above, and:</p>
-        <taglist>
-          <tag><c>Object</c></tag>
-          <item>
-            <p>A reference to the monitored object:</p>
-            <list type="bulleted">
-              <item>the pid of the monitored process, if <c><anno>Item</anno></c> was
-               specified as a pid.</item>
-              <item><c>{RegName, Node}</c>, if <c><anno>Item</anno></c> was specified as
-              <c>{RegName, Node}</c>.</item>
-              <item><c>{RegName, Node}</c>, if <c><anno>Item</anno></c> was specified as
-              <c>RegName</c>. <c>Node</c> will in this case be the
-               name of the local node (<c>node()</c>).</item>
-            </list>
-          </item>
-          <tag><c>Info</c></tag>
-          <item>
-            <p>Either the exit reason of the process, <c>noproc</c>
-              (non-existing process), or <c>noconnection</c> (no
-              connection to <c><anno>Node</anno></c>).</p>
-          </item>
-        </taglist>
-        <note>
-          <p>If/when <c>monitor/2</c> is extended (e.g. to
-            handle other item types than <c>process</c>), other
-            possible values for <c>Object</c>, and <c>Info</c> in the
-            <c>'DOWN'</c> message will be introduced.</p>
-        </note>
-        <p>The monitoring is turned off either when the <c>'DOWN'</c>
-          message is sent, or when
-          <seealso marker="#demonitor/1">demonitor/1</seealso>
-          is called.</p>
-        <p>If an attempt is made to monitor a process on an older node
-          (where remote process monitoring is not implemented or one
-          where remote process monitoring by registered name is not
-          implemented), the call fails with <c>badarg</c>.</p>
-        <p>Making several calls to <c>monitor/2</c> for the same
-          <c><anno>Item</anno></c> is not an error; it results in as many, completely
-          independent, monitorings.</p>
+            unregistered, or unregistered and later registered on another
+	    process.</p></note>
+	    <p>The monitor is triggered either when the monitored process
+	    terminates, is non existing, or if the connection to it is
+	    lost. In the case the connection to it is lost, we do not know
+	    if it still exist or not. After this type of monitor has been
+	    triggered, the monitor is automatically removed.</p>
+            <p>When the monitor is triggered a <c>'DOWN'</c> message will
+	    be sent to the monitoring process. A <c>'DOWN'</c> message has
+	    the following pattern:</p>
+            <code type="none">{'DOWN', MonitorRef, Type, Object, Info}</code>
+            <p>where <c>MonitorRef</c> and <c>Type</c> are the same as
+            described above, and:</p>
+            <taglist>
+              <tag><c>Object</c></tag>
+              <item>
+		<p>equals:</p>
+		<taglist>
+		  <tag><c><anno>Item</anno></c></tag>
+		  <item>If <c><anno>Item</anno></c> was specified by a
+		  pid.</item>
+		  <tag><c>{RegisteredName, Node}</c></tag>
+		  <item>If <c><anno>Item</anno></c> was specified as
+		  <c>RegisteredName</c>, or <c>{RegisteredName, Node}</c>
+		  where <c>Node</c> corresponds to the node that the
+		  monitored process resides on.</item>
+		</taglist>
+              </item>
+              <tag><c>Info</c></tag>
+              <item>
+		<p>Either the exit reason of the process, <c>noproc</c>
+		(non-existing process), or <c>noconnection</c> (no
+		connection to the node where the monitored process
+		resides).</p></item>
+	    </taglist>
+	    <p>The monitoring is turned off either when the <c>'DOWN'</c>
+	    message is sent, or when
+	    <seealso marker="#demonitor/1">demonitor/1</seealso>
+	    is called.</p>
+	    <p>If an attempt is made to monitor a process on an older node
+	    (where remote process monitoring is not implemented or one
+	    where remote process monitoring by registered name is not
+	    implemented), the call fails with <c>badarg</c>.</p>
+	    <note>
+	      <p>The format of the <c>'DOWN'</c> message changed in the 5.2
+	      version of the emulator (OTP release R9B) for monitor
+	      <em>by registered name</em>. The <c>Object</c> element of
+	      the <c>'DOWN'</c> message could in earlier versions
+	      sometimes be the pid of the monitored process and sometimes
+	      be the registered name. Now the <c>Object</c> element is
+	      always a tuple consisting of the registered name and
+	      the node name. Processes on new nodes (emulator version 5.2
+	      or greater) will always get <c>'DOWN'</c> messages on
+	      the new format even if they are monitoring processes on old
+	      nodes. Processes on old nodes will always get <c>'DOWN'</c>
+	      messages on the old format.</p>
+	    </note>
+	  </item>
+	  <tag><marker id="monitor_time_offset"/><c>time_offset</c></tag>
+	  <item>
+	    <p>Monitor changes in
+	    <seealso marker="#time_offset/0">time offset</seealso>
+	    between
+	    <seealso marker="time_correction#Erlang_Monotonic_Time">Erlang
+	    monotonic time</seealso> and
+	    <seealso marker="time_correction#Erlang_System_Time">Erlang
+	    system time</seealso>. There is only one valid
+	    <c><anno>Item</anno></c> in combination with the
+	    <c>time_offset <anno>Type</anno></c>, namely the atom
+	    <c>clock_service</c>. Note that the atom <c>clock_service</c> is
+	    <em>not</em> the registered name of a process. In this specific
+	    case it serves as an identifier of the runtime system internal
+	    clock service at current runtime system instance.</p>
+
+	    <p>The monitor is triggered when the time offset is changed.
+	    This either if the time offset value is changed, or if the
+	    offset is changed from preliminary to final during
+	    <seealso marker="#system_flag_time_offset">finalization
+	    of the time offset</seealso> when the
+	    <seealso marker="time_correction#Single_Time_Warp_Mode">single
+	    time warp mode</seealso> is used. When a change from preliminary
+	    to final time offset is made, the monitor will be triggered once
+	    regardless of whether the time offset value was changed due to
+	    the finalization or not.</p>
+
+	    <p>If the runtime system is in
+	    <seealso marker="time_correction#Multi_Time_Warp_Mode">multi
+	    time warp mode</seealso>, the time offset will be changed when
+	    the runtime system detects that the
+	    <seealso marker="time_correction#OS_System_Time">OS system
+	    time</seealso> has changed. The runtime system will, however,
+	    not detect this immediately when it happens. A task checking
+	    the time offset is scheduled to execute at least once a minute,
+	    so under normal operation this should be detected within a
+	    minute, but during heavy load it might take longer time.</p>
+
+	    <p>The monitor will <em>not</em> be automatically removed
+	    after it has been triggered. That is, repeated changes of
+	    the time offset will trigger the monitor repeatedly.</p>
+
+            <p>When the monitor is triggered a <c>'CHANGE'</c> message will
+	    be sent to the monitoring process. A <c>'CHANGE'</c> message has
+	    the following pattern:</p>
+            <code type="none">{'CHANGE', MonitorRef, Type, Item, NewTimeOffset}</code>
+            <p>where <c>MonitorRef</c>, <c><anno>Type</anno></c>, and 
+	    <c><anno>Item</anno></c> are the same as described above, and
+	    <c>NewTimeOffset</c> is the new time offset.</p>
+
+	    <p>When the <c>'CHANGE'</c> message has been received you are
+	    guaranteed not to retrieve the old time offset when calling
+	    <seealso marker="#time_offset/0"><c>erlang:time_offset()</c></seealso>.
+	    Note that you may observe the change of the time offset
+	    when calling <c>erlang:time_offset()</c> before you
+	    get the <c>'CHANGE'</c> message.</p>
+
+	  </item>
+	</taglist>
+	<p>Making several calls to <c>monitor/2</c> for the same
+	<c><anno>Item</anno></c> and/or <c><anno>Type</anno></c> is not
+	an error; it results in many, completely independent,
+	monitorings.</p>
+	<p>The monitor functionality is expected to be extended. That is,
+	other <c><anno>Type</anno></c>s and <c><anno>Item</anno></c>s
+	are expected to be supported in	the future.</p>
         <note>
-          <p>The format of the <c>'DOWN'</c> message changed in the 5.2
-            version of the emulator (OTP release R9B) for monitor <em>by registered name</em>. The <c>Object</c> element of
-            the <c>'DOWN'</c> message could in earlier versions
-            sometimes be the pid of the monitored process and sometimes
-            be the registered name. Now the <c>Object</c> element is
-            always a tuple consisting of the registered name and
-            the node name. Processes on new nodes (emulator version 5.2
-            or greater) will always get <c>'DOWN'</c> messages on
-            the new format even if they are monitoring processes on old
-            nodes. Processes on old nodes will always get <c>'DOWN'</c>
-            messages on the old format.</p>
+          <p>If/when <c>monitor/2</c> is extended, other
+            possible values for <c>Tag</c>, <c>Object</c>, and
+	    <c>Info</c> in the monitor message will be introduced.</p>
         </note>
       </desc>
     </func>
@@ -2654,6 +2816,51 @@ os_prompt% </pre>
       </desc>
     </func>
     <func>
+      <name name="monotonic_time" arity="0"/>
+      <fsummary>Current Erlang monotonic time</fsummary>
+      <desc>
+	<p>Returns the current
+	<seealso marker="time_correction#Erlang_Monotonic_Time">Erlang
+	monotonic time</seealso> in <c>native</c>
+	<seealso marker="#type_time_unit">time unit</seealso>. This
+	is a monotonically increasing time since some unspecified point in
+	time.</p>
+
+	<note><p>This is a
+	<seealso marker="time_correction#Monotonically_Increasing">monotonically increasing</seealso> time, but <em>not</em> a
+	<seealso marker="time_correction#Strictly_Monotonically_Increasing">strictly monotonically increasing</seealso>
+	time. That is, consecutive calls to
+	<c>erlang:monotonic_time/0</c> may produce the same result.</p>
+
+	<p>Different runtime system instances will use different
+	unspecified points in time as base for their Erlang monotonic clocks.
+	That is, it is <em>pointless</em> comparing monotonic times from
+	different runtime system instances. Different runtime system instances
+	may also place this unspecified point in time different relative
+	runtime system start. It may be placed in the future (time at start
+	will be a negative value), the past (time at start will be a
+	positive value), or the runtime system start (time at start will
+	be zero). The monotonic time as of runtime system start can be
+	retrieved by calling
+	<seealso marker="#system_info_start_time"><c>erlang:system_info(start_time)</c></seealso>.</p></note>
+      </desc>
+    </func>
+    <func>
+      <name name="monotonic_time" arity="1"/>
+      <fsummary>Current Erlang monotonic time</fsummary>
+      <desc>
+	<p>Returns the current
+	<seealso marker="time_correction#Erlang_Monotonic_Time">Erlang
+	monotonic time</seealso> converted
+	into the <c><anno>Unit</anno></c> passed as argument.</p>
+
+	<p>Same as calling
+	<seealso marker="#convert_time_unit/3"><c>erlang:convert_time_unit</c></seealso><c>(</c><seealso marker="#monotonic_time/0"><c>erlang:monotonic_time()</c></seealso><c>,
+	native, <anno>Unit</anno>)</c>
+	however optimized for commonly used <c><anno>Unit</anno></c>s.</p>
+      </desc>
+    </func>
+    <func>
       <name name="nif_error" arity="1"/>
       <fsummary>Stop execution with a given reason</fsummary>
       <desc>
@@ -2748,6 +2955,13 @@ os_prompt% </pre>
       <type name="timestamp"/>
       <fsummary>Elapsed time since 00:00 GMT</fsummary>
       <desc>
+	<warning><p><em>This function is deprecated! Do not use it!</em>
+	See the users guide chapter
+	<seealso marker="time_correction">Time and Time Correction</seealso>
+	for more information. Specifically the 
+	<seealso marker="time_correction#Dos_and_Donts">Dos and Dont's</seealso>
+	section for information on what to use instead of <c>erlang:now/0</c>.
+	</p></warning>
         <p>Returns the tuple <c>{MegaSecs, Secs, MicroSecs}</c> which is
           the elapsed time since 00:00 GMT, January 1, 1970 (zero hour)
           on the assumption that the underlying OS supports this.
@@ -2760,10 +2974,6 @@ os_prompt% </pre>
         <p>It can only be used to check the local time of day if
           the time-zone info of the underlying operating system is
           properly configured.</p>
-        <p>If you do not need the return value to be unique and
-          monotonically increasing, use
-          <seealso marker="kernel:os#timestamp/0">os:timestamp/0</seealso>
-          instead to avoid some overhead.</p>
       </desc>
     </func>
     <func>
@@ -5510,6 +5720,35 @@ ok
         <p>Returns the old value of the flag.</p>
       </desc>
     </func>
+    <marker id="system_flag_time_offset"/>
+    <func>
+      <name name="system_flag" arity="2" clause_i="12"/>
+      <fsummary>Finalize the Time Offset</fsummary>
+      <desc>
+        <p>Finalizes the <seealso marker="#time_offset/0">time offset</seealso>
+	when the <seealso marker="time_correction#Single_Time_Warp_Mode">single
+	time warp mode</seealso> is being used. If another time warp mode than
+	the "single time warp mode" is used, the time offset state will be left
+	unchanged.</p>
+        <p>Returns the old state identifier. That is, if:</p>
+	<list>
+	  <item><p><c>preliminary</c> is returned, finalization was
+	  performed and the time offset is now final.</p></item>
+
+	  <item><p><c>final</c> is returned, the time offset was
+	  already in the final state. This either due to another
+	  <c>erlang:system_flag(time_offset, finalize)</c> call, or
+	  due to the
+	  <seealso marker="time_correction#No_Time_Warp_Mode">no
+	  time warp mode</seealso> being used.</p></item>
+
+	  <item><p><c>volatile</c> is returned, the time offset
+	  cannot be finalized due to the 
+	  <seealso marker="time_correction#Multi_Time_Warp_Mode">multi
+	  time warp mode</seealso> being used.</p></item>
+	</list>
+      </desc>
+    </func>
     <func>
       <name name="system_info" arity="1" clause_i="1"/>
       <name name="system_info" arity="1" clause_i="2"/>
@@ -5790,6 +6029,15 @@ ok
       <name name="system_info" arity="1" clause_i="53"/>
       <name name="system_info" arity="1" clause_i="54"/>
       <name name="system_info" arity="1" clause_i="55"/>
+      <name name="system_info" arity="1" clause_i="56"/>
+      <name name="system_info" arity="1" clause_i="57"/>
+      <name name="system_info" arity="1" clause_i="58"/>
+      <name name="system_info" arity="1" clause_i="59"/>
+      <name name="system_info" arity="1" clause_i="60"/>
+      <name name="system_info" arity="1" clause_i="61"/>
+      <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"/>
       <fsummary>Information about the system</fsummary>
       <desc>
         <p>Returns various information about the current system
@@ -6177,6 +6425,57 @@ ok
 	    documentation of versions in the system principles
 	    guide</seealso>.</p>
           </item>
+          <tag><marker id="system_info_os_monotonic_time_source"><c>os_monotonic_time_source</c></marker></tag>
+          <item>
+            <p>Returns a list containing information about the source of
+	    <seealso marker="erts:time_correction#OS_Monotonic_Time">OS
+	    monotonic time</seealso> that is used by the runtime system.</p>
+	    <p>In case <c>[]</c> is returned, no OS monotonic time is
+	    available. 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. This tuple always exist if OS monotonic time is
+	      available to the runtime system.</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, 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
+	      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
+	      <c>OsMonotonicTimeResolution</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, OsMonotonicTime}</c></tag>
+	      <item><p><c>OsMonotonicTime</c> equals current OS
+	      monotonic 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
@@ -6302,6 +6601,11 @@ ok
             <p>Returns <c>true</c> if the emulator has been compiled
               with smp support; otherwise, <c>false</c>.</p>
           </item>
+	  <tag><marker id="system_info_start_time"/><c>start_time</c></tag>
+	  <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>
           <tag><c>system_version</c></tag>
           <item>
             <p>Returns a string containing version number and
@@ -6325,12 +6629,64 @@ ok
               (<seealso marker="erts:erl_driver#driver_async">driver_async()</seealso>)
               as an integer.</p>
           </item>
+	  <tag><marker id="system_info_time_correction"/><c>time_correction</c></tag>
+	  <item><p>Returns a boolean value indicating whether
+	  <seealso marker="time_correction#Time_Correction">time correction</seealso>
+	  is enabled or not.
+	  </p></item>
+	  <tag><marker id="system_info_time_offset"/><c>time_offset</c></tag>
+	  <item><p>Returns the state of the time offset:</p>
+	  <taglist>
+	    <tag><c>preliminary</c></tag>
+	    <item><p>The time offset is preliminary, and will be changed
+	    at a later time when being finalized. The preliminary time offset
+	    is used during the preliminary phase of the
+	    <seealso marker="time_correction#Single_Time_Warp_Mode">single
+	    time warp mode</seealso>.</p></item>
+
+	    <tag><c>final</c></tag>
+	    <item><p>The time offset is final. This
+	    either due to the use of the
+	    <seealso marker="time_correction#No_Time_Warp_Mode">no
+	    time warp mode</seealso>, or due to the time offset having
+	    been finalized when using the
+	    <seealso marker="time_correction#Single_Time_Warp_Mode">single
+	    time warp mode</seealso>.</p></item>
+
+	    <tag><c>volatile</c></tag>
+	    <item><p>The time offset is volatile. That is, it may
+	    change at any time. This due to the
+	    <seealso marker="time_correction#Multi_Time_Warp_Mode">multi
+	    time warp mode</seealso> being used.</p></item>
+	  </taglist>
+	  </item>
+	  <tag><marker id="system_info_time_warp_mode"/><c>time_warp_mode</c></tag>
+	  <item><p>Returns a value identifying the
+	  <seealso marker="time_correction#Time_Warp_Modes">time warp
+	  mode</seealso> being used:</p>
+	  <taglist>
+	    <tag><c>no_time_warp</c></tag>
+	    <item><p>The <seealso marker="time_correction#No_Time_Warp_Mode">no
+	    time warp mode</seealso> is being used.</p></item>
+
+	    <tag><c>single_time_warp</c></tag>
+	    <item><p>The <seealso marker="time_correction#Single_Time_Warp_Mode">single
+	    time warp mode</seealso> is being used.</p></item>
+
+	    <tag><c>multi_time_warp</c></tag>
+	    <item><p>The <seealso marker="time_correction#Multi_Time_Warp_Mode">multi
+	    time warp mode</seealso> is being used.</p></item>
+	  </taglist>
+	  </item>
           <tag><marker id="system_info_tolerant_timeofday"><c>tolerant_timeofday</c></marker></tag>
           <item>
-            <p>Returns whether compensation for sudden changes of system
-              time is <c>enabled</c> or <c>disabled</c>.</p>
-            <p>See also <seealso marker="erts:erl#+c">+c</seealso>
-              command line flag.</p>
+            <p>Returns whether a pre erts-7.0 backwards compatible compensation
+	    for sudden changes of system time is <c>enabled</c> or <c>disabled</c>.
+	    Such compensation is <c>enabled</c> when the
+	    <seealso marker="#system_info_time_offset">time offset</seealso> is
+	    <c>final</c>, and
+	    <seealso marker="#system_info_time_correction">time correction</seealso>
+	    is enabled.</p>
           </item>
           <tag><c>trace_control_word</c></tag>
           <item>
@@ -6609,7 +6965,44 @@ ok
         </note>
       </desc>
     </func>
+    <func>
+      <name name="system_time" arity="0"/>
+      <fsummary>Current Erlang system time</fsummary>
+      <desc>
+	<p>Returns current
+	<seealso marker="time_correction#Erlang_System_Time">Erlang system time</seealso>
+	in <c>native</c>
+	<seealso marker="#type_time_unit">time unit</seealso>.</p>
 
+	<p>Calling <c>erlang:system_time()</c> is equivalent to: 
+	<seealso marker="#monotonic_time/0"><c>erlang:monotonic_time()</c></seealso><c>
+	+
+        </c><seealso marker="#time_offset/0"><c>erlang:time_offset()</c></seealso>.</p>
+
+	<note><p>This time is <em>not</em> a monotonically increasing time
+	in the general case. For more information, see the documentation of
+	<seealso marker="time_correction#Time_Warp_Modes">time warp modes</seealso> in the
+	ERTS User's Guide.</p></note>
+      </desc>
+    </func>
+    <func>
+      <name name="system_time" arity="1"/>
+      <fsummary>Current Erlang system time</fsummary>
+      <desc>
+	<p>Returns current
+	<seealso marker="time_correction#Erlang_System_Time">Erlang system time</seealso>
+	converted into the <c><anno>Unit</anno></c> passed as argument.</p>
+
+	<p>Calling <c>erlang:system_time(<anno>Unit</anno>)</c> is equivalent to: 
+	<seealso marker="#convert_time_unit/3"><c>erlang:convert_time_unit</c></seealso><c>(</c><seealso marker="#system_time/0"><c>erlang:system_time()</c></seealso><c>,
+	native, <anno>Unit</anno>)</c>.</p>
+
+	<note><p>This time is <em>not</em> a monotonically increasing time
+	in the general case. For more information, see the documentation of
+	<seealso marker="time_correction#Time_Warp_Modes">time warp modes</seealso> in the
+	ERTS User's Guide.</p></note>
+      </desc>
+    </func>
     <func>
       <name name="term_to_binary" arity="1"/>
       <fsummary>Encode a term to an Erlang external term format binary</fsummary>
@@ -6686,6 +7079,88 @@ ok
       </desc>
     </func>
     <func>
+      <name name="time_offset" arity="0"/>
+      <fsummary>Current time offset</fsummary>
+      <desc>
+	<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> in
+	<c>native</c> <seealso marker="#type_time_unit">time unit</seealso>.
+	Current time offset added to an Erlang monotonic time gives
+	corresponding Erlang system time.</p>
+
+	<p>The time offset may or may not change during operation depending
+	on the <seealso marker="time_correction#Time_Warp_Modes">time
+	warp mode</seealso> used.</p>
+
+	<note>
+	  <p>A change in time offset may be observed at slightly
+	  different points in time by different processes.</p>
+
+	  <p>If the runtime system is in
+	  <seealso marker="time_correction#Multi_Time_Warp_Mode">multi
+	  time warp mode</seealso>, the time offset will be changed when
+	  the runtime system detects that the
+	  <seealso marker="time_correction#OS_System_Time">OS system
+	  time</seealso> has changed. The runtime system will, however,
+	  not detect this immediately when it happens. A task checking
+	  the time offset is scheduled to execute at least once a minute,
+	  so under normal operation this should be detected within a
+	  minute, but during heavy load it might take longer time.</p>
+	</note>
+      </desc>
+    </func>
+    <func>
+      <name name="time_offset" arity="1"/>
+      <fsummary>Current time offset</fsummary>
+      <desc>
+	<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><anno>Unit</anno></c> passed as argument.</p>
+
+	<p>Same as calling	
+	<seealso marker="#convert_time_unit/3"><c>erlang:convert_time_unit</c></seealso><c>(</c><seealso marker="#time_offset/0"><c>erlang:time_offset()</c></seealso><c>, native, <anno>Unit</anno>)</c>
+	however optimized for commonly used <c><anno>Unit</anno></c>s.</p>
+      </desc>
+    </func>
+    <func>
+      <name name="timestamp" arity="0"/>
+      <type name="timestamp"/>
+      <fsummary>Current Erlang System time</fsummary>
+      <desc>
+	<p>Returns current
+	<seealso marker="time_correction#Erlang_System_Time">Erlang system time</seealso>
+	on the format <c>{MegaSecs, Secs, MicroSecs}</c>. This format is 
+	the same that <seealso marker="kernel:os#timestamp/0"><c>os:timestamp/0</c></seealso>
+	and the now deprecated <seealso marker="#now/0"><c>erlang:now/0</c></seealso>
+	uses. The reason for the existence of <c>erlang:timestamp()</c> is
+	purely to simplify usage for existing code that assumes this timestamp
+	format. Current Erlang system time can more efficiently be retrieved in
+	the time unit of your choice using
+	<seealso marker="#system_time/1"><c>erlang:system_time/1</c></seealso>.</p>
+
+	<p>The <c>erlang:timestamp()</c> BIF is equivalent to:</p><code type="none">
+timestamp() ->
+    ErlangSystemTime = erlang:system_time(micro_seconds),
+    MegaSecs = ErlangSystemTime div 1000000000000,
+    Secs = ErlangSystemTime div 1000000 - MegaSecs*1000000,
+    MicroSecs = ErlangSystemTime rem 1000000,
+    {MegaSecs, Secs, MicroSecs}.</code>
+        <p>It however use a native implementation which does
+	not build garbage on the heap and with slightly better
+	performance.</p>
+
+	<note><p>This time is <em>not</em> a monotonically increasing time
+	in the general case. For more information, see the documentation of
+	<seealso marker="time_correction#Time_Warp_Modes">time warp modes</seealso> in the
+	ERTS User's Guide.</p></note>
+      </desc>
+
+    </func>
+    <func>
       <name name="tl" arity="1"/>
       <fsummary>Tail of a list</fsummary>
       <desc>
@@ -7452,6 +7927,100 @@ ok
       </desc>
     </func>
     <func>
+      <name name="unique_integer" arity="0"/>
+      <fsummary>Get a unique integer value</fsummary>
+      <desc>
+	<p>Generates and returns an
+	<seealso marker="doc/efficiency_guide:advanced#unique_integers">integer
+	unique on current runtime system instance</seealso>. The same as calling
+	<seealso marker="#unique_integer/1"><c>erlang:unique_integer([])</c></seealso>.</p>
+      </desc>
+    </func>
+    <func>
+      <name name="unique_integer" arity="1"/>
+      <fsummary>Get a unique integer value</fsummary>
+      <desc>
+	<p>Generates and returns an
+	<seealso marker="doc/efficiency_guide:advanced#unique_integers">integer
+	unique on current runtime system
+	instance</seealso>. The integer is unique in the
+	sense that this BIF, using the same set of
+	modifiers, will not return the same integer more
+	than once on the current runtime system instance.
+	Each integer value can of course be constructed
+	by other means.</p>
+
+	<p>By default, i.e. when <c>[]</c> is passed as
+	<c><anno>ModifierList</anno></c>, both negative and
+	positive integers will be returned. This is order
+	to be able to utilize the range of integers that do
+	not need to be heap allocated as much as possible.
+	By default the returned integers are also only
+	guaranteed to be unique, i.e., any integer returned
+	may be either smaller, or larger than previously
+	returned integers.</p>
+
+	<p>Currently valid <c><anno>Modifier</anno></c>s:</p>
+	<taglist>
+
+	  <tag>positive</tag>
+	  <item><p>Return only positive integers.</p>
+	  <p>Note that by passing the <c>positive</c> modifier
+	  you will get heap allocated integers (big-nums)
+	  quicker.</p>
+	  </item>
+
+	  <tag>monotonic</tag>
+	  <item><p>Return
+	  <seealso marker="time_correction#Strictly_Monotonically_Increasing">strictly
+	  monotonically increasing</seealso> integers
+	  corresponding to creation time. That is, the integer
+	  returned will always be larger than previously
+	  returned integers on the current runtime system
+	  instance.</p>
+	  <p>These values can be used when ordering events
+	  on the runtime system instance. That is, if both
+	  <c>X = erlang:unique_integer([monotonic])</c> and
+	  <c>Y = erlang:unique_integer([monotonic])</c> are
+	  executed by different processes (or the same
+	  process) on the same runtime system instance and
+	  <c>X &lt; Y</c> we know that <c>X</c> was created
+	  before <c>Y</c>.</p>
+	  <warning><p>Strictly monotonically increasing values
+	  are inherently quite expensive to generate and scales
+	  poorly. This since the values needs to be
+	  synchronized. That is, do not pass the <c>monotonic</c>
+	  modifier unless you really need strictly monotonically
+	  increasing values.</p></warning>
+	  </item>
+
+	</taglist>
+
+	<p>All currently valid <c><anno>Modifier</anno></c>s
+	can be combined. Repeated (valid)
+	<c><anno>Modifier</anno></c>s in the <c>ModifierList</c>
+	are ignored.</p>
+
+	<note><p>Note that the set of integers returned by
+	<c>unique_integer/1</c> using diffrent sets of
+	<c><anno>Modifier</anno></c>s <em>will overlap</em>.
+	For example, by calling	<c>unique_integer([monotonic])</c>,
+	and <c>unique_integer([positive, monotonic])</c>
+	repeatedly, you will eventually see some integers being
+	returned by both calls.</p></note>
+
+        <p>Failures:</p>
+	<taglist>
+	  <tag><c>badarg</c></tag>
+	  <item>if <c><anno>ModifierList</anno></c> is not a
+	  proper list.</item>
+	  <tag><c>badarg</c></tag>
+	  <item>if <c><anno>Modifier</anno></c> is not a
+	  valid modifier.</item>
+	</taglist>
+      </desc>
+    </func>
+    <func>
       <name name="unlink" arity="1"/>
       <fsummary>Remove a link, if there is one, to another process or port</fsummary>
       <desc>
diff --git a/erts/doc/src/time_correction.xml b/erts/doc/src/time_correction.xml
index 7f7c28fc30..3bc3d04186 100644
--- a/erts/doc/src/time_correction.xml
+++ b/erts/doc/src/time_correction.xml
@@ -21,8 +21,8 @@
 
     </legalnotice>
 
-    <title>Time and time correction in Erlang</title>
-    <prepared>Patrik Nyblom</prepared>
+    <title>Time and Time Correction in Erlang</title>
+    <prepared></prepared>
     <responsible></responsible>
     <docno></docno>
     <approved></approved>
@@ -31,6 +31,176 @@
     <rev>PA1</rev>
     <file>time_correction.xml</file>
   </header>
+
+  <section>
+    <title>New Extended Time Functionality</title>
+    <note><p>As of OTP 18 (ERTS version 7.0) the time functionality of
+    Erlang has been extended. This both includes a
+    <seealso marker="#The_New_Time_API">new API</seealso>
+    for time, as well as
+    <seealso marker="#Time_Warp_Modes">time warp
+    modes</seealso> which alters the behavior of the system when
+    system time changes.</p>
+    <p>The <seealso marker="#No_Time_Warp_Mode">default
+    time warp mode</seealso> has the same behavior as before, and the
+    old API will still work, so you are not required to change
+    anything unless you want to. However, <em>you are strongly
+    encouraged to use the new API</em> instead of the old API based
+    on <seealso marker="erlang#now/0"><c>erlang:now/0</c></seealso>.
+    <c>erlang:now/0</c> has been deprecated since it is and forever
+    will be a scalability bottleneck. By using the new API you will
+    automatically get scalability and performance improvements. This
+    will also enable you to use the
+    <seealso marker="#Multi_Time_Warp_Mode">multi time warp mode</seealso>
+    which improves accuracy, and precision of time measurements.</p></note>
+  </section>
+
+  <section>
+    <title>Some Terminology</title>
+    <p>In order to make it easier to understand this document we first
+    define some terminology. This is a mixture of our own terminology
+    (Erlang/OS system time, Erlang/OS monotonic time, time warp)
+    and globally accepted terminology.</p>
+
+    <marker id="Monotonically_Increasing"/>
+    <section>
+      <title>Monotonically Increasing</title>
+      <p>In a monotonically increasing sequence of values, all values
+      that have a predecessor are either larger than, or equal to its
+      predecessor.</p>
+    </section>
+
+    <marker id="Strictly_Monotonically_Increasing"/>
+    <section>
+      <title>Strictly Monotonically Increasing</title>
+      <p>In a strictly monotonically increasing sequence of values,
+      all values that have a predecessor are larger than its
+      predecessor.</p>
+    </section>
+
+    <marker id="UT1"/>
+    <section>
+      <title>UT1</title>
+      <p>Universal Time. Based on the rotation of the earth. Conceptually
+      mean solar time at 0° longitude.</p>
+    </section>
+
+    <marker id="UTC"/>
+    <section>
+      <title>UTC</title>
+      <p>Coordinated Universal Time. UTC almost align with
+      <seealso marker="#UT1">UT1</seealso>, however, UTC uses the
+      SI definition of a second which is not exactly of the same length
+      as the second used by UT1. This means that UTC slowly drifts from
+      UT1. In order to keep UTC relatively in sync with UT1, leap seconds
+      are inserted, and potentially also deleted. That is, an UTC day may
+      be 86400, 86401, or 86399 seconds long.</p>
+    </section>
+
+    <marker id="POSIX_Time"/>
+    <section>
+      <title>POSIX Time</title>
+      <p>Time since
+      <url href="http://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xbd_chap03.html#tag_21_03_00_17">Epoch</url>.
+      Epoch is defined to be 00:00:00 <seealso marker="#UTC">UTC</seealso>,
+      January 1, 1970.
+      <url href="http://pubs.opengroup.org/onlinepubs/009604499/basedefs/xbd_chap04.html#tag_04_14">A day in POSIX time</url>
+      is defined to be exactly 86400 seconds long. Strangely enough
+      Epoch is defined to be a time in UTC, and UTC have another
+      definition of how long a day is. Quoting the Open Group
+      <url href="http://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xbd_chap04.html#tag_21_04_15">"POSIX time is therefore not necessarily UTC, despite its appearance"</url>. The effect of this is that when an UTC leap second is
+      inserted, POSIX time either stops for a second, or repeats the
+      last second. If an UTC leap second would be deleted (has never
+      happened yet), POSIX time would make a one second leap forward.</p>
+    </section>
+
+    <marker id="OS_System_Time"/>
+    <section>
+      <title>OS System Time</title>
+      <p>The operating systems view of
+      <seealso marker="#POSIX_Time">POSIX time</seealso>. It can be
+      retrieved by calling
+      <seealso marker="kernel:os#system_time/0"><c>os:system_time()</c></seealso>.
+      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>
+    </section>
+
+    <marker id="OS_Monotonic_Time"/>
+    <section>
+      <title>OS Monotonic Time</title>
+      <p>A monotonically increasing time provided by the operating
+      system. This time does not leap and have a relatively steady
+      frequency although not completely correct. However, it is not
+      uncommon that the OS monotonic time stops if the system is
+      suspended. This time typically increase since some unspecified
+      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>
+    </section>
+
+    <marker id="Erlang_System_Time"/>
+    <section>
+      <title>Erlang System Time</title>
+      <p>The Erlang runtime systems view of
+      <seealso marker="#POSIX_Time">POSIX time</seealso>. It can be
+      retrieved by calling
+      <seealso marker="erlang#system_time/0"><c>erlang:system_time()</c></seealso>.
+      This time may or may not be an accurate view of POSIX time, and may
+      or may not align with <seealso marker="#OS_System_Time">OS system
+      time</seealso>.  The <seealso marker="#Time_Warp_Modes">time
+      warp mode</seealso> determines how it behaves when OS system
+      time suddenly change.</p>
+    </section>
+
+    <marker id="Erlang_Monotonic_Time"/>
+    <section>
+      <title>Erlang Monotonic Time</title>
+      <p>A monotonically increasing time provided by the
+      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
+      <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
+      as on the
+      <seealso marker="#Time_Warp_Modes">time warp mode</seealso>
+      used. On a system that is lacking OS monotonic time, the Erlang
+      monotonic time can only guarantee monotonicity and can more or less
+      not give any other guarantees. The frequency adjustments made to
+      the Erlang monotonic time depends on the time warp mode
+      used.</p>
+
+      <p>Internally in the runtime system the Erlang monotonic
+      time is the "time engine" that is used for more or less
+      everything that has anything to do with time. All timers
+      regardless of it is a <c>receive ... after</c> timer, BIF timer,
+      or a timer in the <c>timer</c> module are triggered
+      relative Erlang monotonic time. Even
+      <seealso marker="#Erlang_System_Time">Erlang system
+      time</seealso> is based on Erlang monotonic time.
+      By adding current Erlang monotonic time with current time
+      offset you get current Erlang system time. Current time
+      offset can be retrieved by calling
+      <seealso marker="erlang#time_offset/0"><c>erlang:time_offset/0</c></seealso>.
+      </p>
+    </section>
+
+    <marker id="Time_Warp"/>
+    <section>
+      <title>Time Warp</title>
+      <p>A time warp is a leap forwards or backwards in time.</p>
+    </section>
+
+  </section>
+
+  <section>
+    <title>Introduction</title>
+
   <p>Time is vital to an Erlang program and, more importantly, <em>correct</em>
   time is vital to an Erlang program. As Erlang is a language with
   soft real time properties and we have the possibility to express
@@ -83,192 +253,587 @@
   microsecond resolution or much less, but generally it has a drift
   that is not to be ignored.</p>
 
-  <p>So we have this monotonic ticking and we have the wall clock
-  time. Two unreliable times that together can give us an estimate of
-  an actual wall clock time that does not jump around and that
-  monotonically moves forward. If the tick counter has a high
-  resolution, this is fairly easy to do, if the counter has a low
-  resolution, it's more expensive, but still doable down to
-  frequencies of 50-60 Hz (of the tick counter).</p>
-
-  <p>So the corrected time is the nearest approximation of an atomic
-  clock that is available on the computer. We want it to have the
-  following properties:</p>
-  <taglist>
-    <tag>Monotonic</tag>
-    <item>The clock should not move backwards</item>
-    <tag>Intervals should be near the truth</tag>
-    <item>We want the actual time (as measured by an atomic clock or
-    an astronomer) that passes between two time stamps, T1 and T2, to be as
-    near to T2 - T1 as possible.</item>
-    <tag>Tight coupling to the wall clock</tag>
-    <item>We want a timer that is to be fired when the wall clock
-    reaches a time in the future, to fire as near to that point in
-    time as possible</item>
-  </taglist>
-  <p>To meet all the criteria, we have to utilize both times in such a
-  way that Erlangs "corrected time" moves slightly slower or slightly
-  faster than the wall clock to get in sync with it. The word
-  "slightly" means a maximum of 1% difference to the wall clock time,
-  meaning that a sudden change in the wall clock of one minute, takes
-  100 minutes to fix, by letting all "corrected time" move 1% slower
-  or faster.</p>
-
-  <p>Needless to say, correcting for a faulty handling of daylight
-  saving time may be disturbing to a user comparing wall clock
-  time to for example calendar:now_to_local_time(erlang:now()). But
-  calendar:now_to_local_time/1 is not supposed to be used for presenting wall
-  clock time to the user.</p>
-
-  <p>Time correction is not perfect, but it saves you from the havoc
-  of clocks jumping around, which would make timers in your program
-  fire far to late or far to early and could bring your whole system
-  to it's knees (or worse) just because someone detected a small error
-  in the wall clock time of the server where your program runs. So
-  while it might be confusing, it is still a really good feature of
-  Erlang and you should not throw it away using time functions which
-  may give you higher benchmark results, not unless you really know
-  what you're doing.</p>
+  </section>
 
+  <marker id="Time_Correction"/>
   <section>
-    <title>What does time correction mean in my system?</title>
-    <p>Time correction means that Erlang estimates a time from current
-    and previous settings of the wall clock, and it uses a fairly
-    exact tick counter to detect when the wall clock time has jumped
-    for some reason, slowly adjusting to the new value.</p>
-
-    <p>In practice, this means that the difference between two calls
-    to time corrected functions, like erlang:now(), might differ up to
-    one percent from the corresponding calls to non time corrected
-    functions (like os:timestamp()). Furthermore, if comparing
-    calendar:local_time/0 to calendar:now_to_local_time(erlang:now()),
-    you might temporarily see a difference, depending on how well kept your
-    system is.</p>
-
-    <p>It is important to understand that it is (to the program)
-    always unknown if it is the wall clock time that moves in the
-    wrong pace or the Erlang corrected time. The only way to determine
-    that, is to have an external source of universally correct time. If
-    some such source is available, the wall clock time can be kept
-    nearly perfect at all times, and no significant difference will be
-    detected between erlang:now/0's pace and the wall clock's.</p>
-
-    <p>Still, the time correction will mean that your system keeps
-    it's real time characteristics very well, even when the wall clock
-    is unreliable.</p>
+    <title>Time Correction</title>
+    <p>If time correction is enabled, the Erlang runtime system
+    will make use of both
+    <seealso marker="#OS_System_Time">OS system time</seealso>
+    and <seealso marker="#OS_Monotonic_Time">OS monotonic time</seealso>,
+    in order to make adjustments of the frequency of the Erlang
+    monotonic clock. Time correction will ensure that
+    <seealso marker="#Erlang_Monotonic_Time">Erlang monotonic time</seealso>
+    will not warp, and that the frequency is relatively accurate.
+    The type of adjustments made to the frequency depends on the
+    time warp mode used. This will be discussed in more details in
+    the <seealso marker="#Time_Warp_Modes">time warp modes</seealso>
+    section below.</p>
+
+    <p>By default time correction will be enabled if support for
+    it on the specific platform exist. Support for it includes
+    both an OS monotonic time provided by the OS, and an
+    implementation in the Erlang runtime system utilizing the
+    OS monotonic time. You can check if your system has support
+    for OS monotonic time by calling
+    <seealso marker="erlang#system_info_os_monotonic_time_source"><c>erlang:system_info(os_monotonic_time_source)</c></seealso>,
+    and you can check if time correction is enabled on your
+    system by calling
+    <seealso marker="erlang#system_info_time_correction"><c>erlang:system_info(time_correction)</c></seealso>.</p>
+
+    <p>Time correction is enabled or disabled by passing the
+    <seealso marker="erl#+c"><c>+c [true|false]</c></seealso>
+    command line argument to <c>erl</c>.</p>
+
+    <p>If time correction is disabled, Erlang monotonic time
+    may warp forwards, it may stop and even freeze for extended
+    periods of time, and there are no guarantees that the frequency
+    of the Erlang monotonic clock is accurate or stable.</p>
+
+    <p><em>You typically never want to disable time correction</em>.
+    Previously there was a performance penalty associated with time
+    correction, but nowadays it is most often the other way around.
+    By disabling time correction you are likely to get bad scalability,
+    bad performance, and bad time measurements.</p>
   </section>
+
+
+  <marker id="Time_Warp_Safe_Code"/>
   <section>
-    <title>Where does Erlang use corrected time?</title>
-    <p>For all functionality where real time characteristics are
-    desirable, time correction is used. This basically means:</p>
-    <taglist>
-      <tag>erlang:now/0</tag>
-      <item>The infamous erlang:now/0 function uses time correction so
-      that differences between two "now-timestamps" will correspond to
-      other timeouts in the system. erlang:now/0 also holds other
-      properties, discussed later.</item>
-      <tag>receive ... after</tag>
-      <item>Timeouts on receive uses time correction to determine a
-      stable timeout interval.</item>
-      <tag>The timer module</tag>
-      <item>As the timer module uses other built in functions which
-      deliver corrected time, the timer module itself works with
-      corrected time.</item>
-      <tag>erlang:start_timer/3 and erlang:send_after/3</tag>
-      <item>The timer BIF's work with corrected time, so that they
-      will not fire prematurely or too late due to changes in the wall
-      clock time.</item>
-    </taglist>
-
-    <p>All other functionality in the system where erlang:now/0 or any
-    other time corrected functionality is used, will of course
-    automatically benefit from it, as long as it's not "optimized" to
-    use some other time stamp function (like os:timestamp/0).</p>
-
-    <p>Modules like calendar and functions like erlang:localtime/0 use
-    the wall clock time as it is currently set on the system. They
-    will not use corrected time. However, if you use a now-value and
-    convert it to local time, you will get a corrected local time
-    value, which may or may not be what you want. Typically older code
-    tend to use erlang:now/0 as a wall clock time, which is usually
-    correct (at least when testing), but might surprise you when
-    compared to other times in the system.</p>
+    <title>Time Warp Safe Code</title>
+    <p>Time warp safe code is code that is able to handle
+    a time warp of
+    <seealso marker="#Erlang_System_Time">Erlang system time</seealso>.
+    </p>
+
+    <p><seealso marker="erlang#now/0"><c>erlang:now/0</c></seealso>
+    behaves very bad when Erlang system time warps. When Erlang
+    system time do a time warp backwards, the values returned
+    from <c>erlang:now/0</c> will freeze (if you disregard the
+    micro second increments made due to the actual call) until
+    OS system time reach the point of the last value returned by
+    <c>erlang:now/0</c>. This freeze might continue for very
+    long periods of time. It might take years, decades,
+    and even longer than this until the freeze stops.</p>
+
+    <p>All uses of <c>erlang:now/0</c> are not necessarily
+    time warp unsafe. If you do not use it to get time, it
+    will be time warp safe. However <em>all uses of
+    <c>erlang:now/0</c> are suboptimal</em> from a performance
+    and scalability perspective. So you really want to replace
+    the usage of it with other functionality. For examples
+    of how to replace the usage of <c>erlang:now/0</c>,
+    see the <seealso marker="#Dos_and_Donts">Dos and Donts</seealso>
+    section.</p>
   </section>
+
+  <marker id="Time_Warp_Modes"/>
   <section>
-    <title>What is erlang:now/0 really?</title>
-    <p>erlang:now/0 is a function designed to serve multiple purposes
-    (or a multi-headed beast if you're a VM designer). It is expected
-    to hold the following properties:</p>
-    <taglist>
-      <tag>Monotonic</tag>
-      <item>erlang:now() never jumps backwards - it always moves
-      forward</item>
-      <tag>Interval correct</tag>
-      <item>The interval between two erlang:now() calls is expected to
-      correspond to the correct time in real life (as defined by an
-      atomic clock, or better)</item>
-      <tag>Absolute correctness</tag>
-      <item>The erlang:now/0 value should be possible to convert to an
-      absolute and correct date-time, corresponding to the real world
-      date and time (the wall clock)</item>
-      <tag>System correspondence</tag>
-      <item>The erlang:now/0 value converted to a date-time is
-      expected to correspond to times given by other programs on the
-      system (or by functions like os:timestamp/0)</item>
-      <tag>Unique</tag>
-      <item>No two calls to erlang:now on one Erlang node should
-      return the same value</item>
-    </taglist>
-    <p>All these requirements are possible to uphold at the same
-    time if (and only if):</p>
-    <taglist>
-      <tag>The wall clock time of the system is perfect</tag>
-      <item>The system (Operating System) time needs to be perfectly
-      in sync with the actual time as defined by an atomic clock or
-      a better time source. A good installation using NTP, and that is
-      up to date before Erlang starts, will have properties that for
-      most users and programs will be near indistinguishable from the
-      perfect time. Note that any larger corrections to the time done
-      by hand, or after Erlang has started, will partly (or
-      temporarily) invalidate some of the properties, as the time is
-      no longer perfect.</item>
-      <tag>Less than one call per microsecond to erlang:now/0 is
-      done</tag>
-      <item>This means that at <em>any</em> microsecond interval in
-      time, there can be no more than one call to erlang:now/0 in the
-      system. However, for the system not to loose it's properties
-      completely, it's enough that it on average is no more than one
-      call per microsecond (in one Erlang node).</item>
-    </taglist>
-    <p>The uniqueness property of erlang:now/0 is the most limiting
-    property. It means that erlang:now() maintains a global state and
-    that there is a hard-to-check property of the system that needs to
-    be maintained. For most applications this is still not a problem,
-    but a future system might very well manage to violate the
-    frequency limit on the calls globally. The uniqueness property is
-    also quite useless, as there are globally unique references that
-    provide a much better unique value to programs. However the
-    property will need to be maintained unless a really subtle
-    backward compatibility issue is to be introduced.</p>
+    <title>Time Warp Modes</title>
+
+    <p>Current <seealso marker="#Erlang_System_Time">Erlang system
+    time</seealso> is determined by adding current
+    <seealso marker="erlang#monotonic_time/0">Erlang monotonic time</seealso>
+    with current
+    <seealso marker="erlang#time_offset/0">time offset</seealso>. The
+    time offset is managed differently depending on which time
+    warp mode you use. The time warp mode is set by passing the
+    <seealso marker="erl#+C_"><c>+C
+    [no_time_warp|single_time_warp|multi_time_warp]</c></seealso>
+    command line argument to <c>erl</c>.</p>
+
+    <marker id="No_Time_Warp_Mode"/>
+    <section>
+      <title>No Time Warp Mode</title>
+      <p>The time offset is determined at runtime system start
+      and will after this not change. This is the default behavior.
+      Not because it is the best mode (which it isn't). It is
+      default only because this is how the runtime system always
+      has behaved until ERTS version 7.0, and you have to ensure
+      that your Erlang code that may execute during a time warp is
+      <seealso marker="#Time_Warp_Safe_Code">time warp safe</seealso>
+      before you can enable other modes.</p>
+
+      <p>Since the time offset is not allowed to change, time
+      correction needs to adjust the frequency of the Erlang
+      monotonic clock in order to smoothly align Erlang system
+      time with OS system time. A big downside of this approach
+      is that we on purpose will use a faulty frequency on the
+      Erlang monotonic clock if adjustments are needed. This
+      error may be as big as 1%. This error will show up in all
+      time measurements in the runtime system.</p>
+
+      <p>If time correction is not enabled, the Erlang monotonic
+      time will freeze when the OS system time leap backwards.
+      The freeze of the monotonic time will continue until
+      OS system time catch up. The freeze may continue for
+      a very long time. When OS system time leaps forwards,
+      Erlang monotonic time will also leap forward.</p>
+    </section>
+
+    <marker id="Single_Time_Warp_Mode"/>
+    <section>
+      <title>Single Time Warp Mode</title>
+      <p>This mode is more or less a backwards compatibility mode
+      as of its introduction.</p>
+      <p>On an embedded system it is not uncommon that the system
+      has no power supply at all, not even a battery, when it is
+      shut off. The system clock on such a system will typically
+      be way off when the system boots. If the
+      <seealso marker="#No_Time_Warp_Mode">no time warp mode</seealso>
+      is used, and the Erlang runtime system is started before
+      the OS system time has been corrected, the Erlang system
+      time may be wrong for a very long time, even centuries or
+      more.</p>
+      <p>If you for some reason need to use Erlang code that
+      is not
+      <seealso marker="#Time_Warp_Safe_Code">time warp safe</seealso>,
+      and you need to start the Erlang runtime system before the OS
+      system time has been corrected, you may want to use the single
+      time warp mode. Note that there are limitations to when you can
+      execute time warp unsafe code using this mode. If it is possible
+      to only utilize time warp safe code, it is much better to use
+      the <seealso marker="#Multi_Time_Warp_Mode">multi time warp
+      mode</seealso> instead.
+      </p>
+
+      <p>Using the single time warp mode, the time offset is
+      handled in two phases:</p>
+
+      <taglist>
+	<tag>Preliminary Phase</tag>
+	<item>
+	  <p>The preliminary phase starts when the runtime
+	  system starts. A preliminary time offset based on
+	  current OS system time is determined. This offset will
+	  from now on be fixed during the whole preliminary phase.</p>
+
+	  <p>If time correction is enabled, the Erlang
+	  monotonic clock will only use the OS monotonic time as
+	  time source during this phase. That is, during the
+	  preliminary phase changes in OS system time will have
+	  no effect on Erlang system time and/or Erlang
+	  monotonic time what so ever.</p>
+
+	  <p>If time correction is disabled, changes in OS system
+	  time will effect the monotonic clock the same way as
+	  when the <seealso marker="#No_Time_Warp_Mode">no time warp
+	  mode</seealso> is used.</p>
+	</item>
+
+	<tag>Final Phase</tag>
+	<item>
+
+	  <p>The final phase begin when the user finalize the time
+	  offset by calling
+	  <seealso marker="erlang#system_flag_time_offset"><c>erlang:system_flag(time_offset, finalize)</c></seealso>.
+	  The finalization can only be performed once.
+	  </p>
+
+	  <p>During finalization, the time offset is adjusted and
+	  fixated so that current Erlang system time align with
+	  current OS system time. Since the time offset
+	  may be changed, the Erlang system time may do
+	  a time warp at this point. The time offset will from
+	  now on be fixed until the runtime system terminates.
+	  If time correction has been enabled, the time correction
+	  also begins when this phase begins. When the system is
+	  in the final phase it behaves exactly as in the
+	  <seealso marker="#No_Time_Warp_Mode">no time warp
+	  mode</seealso>.</p>
+
+	</item>
+      </taglist>
+
+      <p>In order for this to work properly there are two
+      requirements that the user needs to ensure are
+      satisfied:</p>
+
+      <taglist>
+	<tag>Forward Time Warp</tag>
+	<item><p>The time warp made when finalizing the time offset
+	can only be done forwards without encountering problems.
+	This implies that the user has to ensure that the OS
+	system time is set to a time earlier or equal to actual
+	POSIX time before starting the Erlang runtime system. If
+	you are not completely sure the OS system time is correct,
+	set it to a time that is guaranteed to be earlier than
+	actual POSIX time before starting the Erlang runtime
+	system just to be safe.</p></item>
+
+	<tag>Finalize Correct OS System Time</tag>
+	<item><p>The OS system time needs to be correct when the
+	the user finalizes the time offset.</p></item>
+      </taglist>
+
+      <p>If these requirements are not fulfilled, the system
+      may behave very bad.
+      </p>
+
+      <p>Assuming that the requirements above are fulfilled,
+      time correction is enabled, and that the OS system time
+      is adjusted using some time adjustment protocol like NTP
+      or similar, only small adjustments of the Erlang monotonic
+      time should be needed in order to keep system times
+      aligned after finilization. As long as the system is not
+      suspended, the largest adjustments needed should be for
+      inserted (or deleted) leap seconds.</p>
+
+      <warning><p>In order to be able to use this mode you have
+      to ensure that all Erlang code that will execute in
+      both phases are
+      <seealso marker="#Time_Warp_Safe_Code">time warp
+      safe</seealso>.</p>
+      <p>Code that only execute in the final phase does not have
+      to be able to cope with the time warp.</p></warning>
+
+    </section>
+
+    <marker id="Multi_Time_Warp_Mode"/>
+    <section>
+      <title>Multi Time Warp Mode</title>
+
+      <p><em>Multi time warp mode in combination with time
+      correction is the preferred configuration</em>. This since,
+      on almost all platforms, the Erlang runtime system will have
+      better performance, will scale better, will behave better,
+      and since the accuracy, and precision of time measurements
+      will be better. Only Erlang runtime systems executing on
+      ancient platforms will benefit from another configuration.</p>
+
+      <p>The time offset may change at any time without limitations.
+      That is, Erlang system time may perform time warps both
+      forwards and backwards at <em>any</em> time. Since we align
+      the Erlang system time with the OS system time by changing
+      the time offset, we can enable a time correction that tries
+      to adjust the frequency of the Erlang monotonic clock to be as
+      correct as possible. This will make time measurements using
+      the Erlang monotonic time more accurate and precise.</p>
+
+      <p>If time correction is disabled, Erlang monotonic time
+      will leap forward if OS system time leaps forward. If the
+      OS system time leaps backwards, Erlang monotonic time will
+      stop briefly but it does not freeze for extended periods
+      of time. This since the time offset is changed in order to
+      align Erlang system time with OS system time.</p>
+
+      <warning><p>In order to be able to use this mode you have
+      to ensure that all Erlang code that will execute on the
+      runtime system is
+      <seealso marker="#Time_Warp_Safe_Code">time warp
+      safe</seealso>.</p></warning>
+    </section>
   </section>
+
+  <marker id="The_New_Time_API"/>
   <section>
-    <title>Should I use erlang:now/0 or os:timestamp/0</title>
-    <p>The simple answer is to use erlang:now/0 for everything where
-    you want to keep real time characteristics, but use os:timestamp
-    for things like logs, user communication and debugging (typically
-    timer:ts uses os:timestamp, as it is a test tool, not a real world
-    application API). The benefit of using os:timestamp/0 is that it's
-    faster and does not involve any global state (unless the operating
-    system has one). The downside is that it will be vulnerable to wall
-    clock time changes.</p>
+    <title>The New Time API</title>
+
+    <p>The old time API is based on
+    <seealso marker="erlang#now/0"><c>erlang:now/0</c></seealso>.
+    The major issue with <c>erlang:now/0</c> is that it was
+    intended to be used for so many unrelated things. This
+    tied these unrelated operations together and unnecessarily
+    caused performance, scalability as well as accuracy, and
+    precision issues for operations that do not need to have
+    such issues. The new API spreads different functionality
+    over multiple functions in order to improve on this.</p>
+
+    <p>In order to be backwards compatible <c>erlang:now/0</c> will
+    remain as is, but <em>you are strongly discouraged from using
+    it</em>. A lot of uses of <c>erlang:now/0</c> will also
+    prevent you from using the new
+    <seealso marker="#Multi_Time_Warp_Mode">multi time warp
+    mode</seealso> which is an important part of this
+    new time functionality improvement.</p>
+
+    <p>Some of the new BIFs on some systems, perhaps surprisingly,
+    return negative integer values on a newly started run time
+    system. This is not a bug, but a memory usage optimization.</p>
+
+    <p>The new API consists of a number of new BIFs:</p>
+    <list>
+      <item><p><seealso marker="erlang#convert_time_unit/3"><c>erlang:convert_time_unit/3</c></seealso></p></item>
+      <item><p><seealso marker="erlang#monotonic_time/0"><c>erlang:monotonic_time/0</c></seealso></p></item>
+      <item><p><seealso marker="erlang#monotonic_time/1"><c>erlang:monotonic_time/1</c></seealso></p></item>
+      <item><p><seealso marker="erlang#system_time/0"><c>erlang:system_time/0</c></seealso></p></item>
+      <item><p><seealso marker="erlang#system_time/1"><c>erlang:system_time/1</c></seealso></p></item>
+      <item><p><seealso marker="erlang#time_offset/0"><c>erlang:time_offset/0</c></seealso></p></item>
+      <item><p><seealso marker="erlang#time_offset/1"><c>erlang:time_offset/1</c></seealso></p></item>
+      <item><p><seealso marker="erlang#timestamp/0"><c>erlang:timestamp/0</c></seealso></p></item>
+      <item><p><seealso marker="erlang#unique_integer/0"><c>erlang:unique_integer/0</c></seealso></p></item>
+      <item><p><seealso marker="erlang#unique_integer/1"><c>erlang:unique_integer/1</c></seealso></p></item>
+      <item><p><seealso marker="kernel:os#system_time/0"><c>os:system_time/0</c></seealso></p></item>
+      <item><p><seealso marker="kernel:os#system_time/1"><c>os:system_time/1</c></seealso></p></item>
+    </list>
+    <p>and a number of extensions of existing BIFs:</p>
+    <list>
+      <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_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>
+      <item><p><seealso marker="erlang#system_info_start_time"><c>erlang:system_info(start_time)</c></seealso></p></item>
+    </list>
+
+    <marker id="The_New_Erlang_Monotonic_Time"/>
+    <section>
+      <title>The New Erlang Monotonic Time</title>
+      <p>The Erlang monotonic time as such is new as of ERTS
+      version 7.0. It has been introduced in order to be able
+      to detach time measurements such as elapsed time from
+      calender time. It is very common that one is interested
+      in measuring elapsed time or specifying a time relative
+      to another point in time without having any need to know
+      what the involved times are in UTC or any other
+      globally defined time scale. By introducing a time scale
+      that has a local definition of where it starts, it is
+      possible to manage time that do not concern calender
+      time on that time scale. Erlang monotonic time use
+      such a time scale with a locally defined start.</p>
+
+      <p>The introduction of Erlang monotonic time gives us
+      the possibility to adjust the two Erlang times (Erlang
+      monotonic time and Erlang system time) separately. By
+      doing this, accuracy of elapsed time does not have to
+      suffer just because the system time happened to be
+      wrong at some point in time. Separate adjustments
+      of the two times are only performed in the time warp
+      modes, and only fully separated in the
+      <seealso marker="#Multi_Time_Warp_Mode">multi
+      time warp mode</seealso>. All other modes than the
+      multi time warp mode are there for backwards
+      compatibility reasons, and when using these the
+      accuracy of Erlang monotonic time suffer since
+      the adjustments of Erlang monotonic time in these
+      modes are more or less tied to the Erlang system
+      time.</p>
+
+      <p>The adjustment of system time could have been made
+      smother than using a time warp approach, but we think
+      that would be a bad choice. Since we are able to
+      express and measure time that aren't connected to
+      calender time by the use of Erlang monotonic time, it
+      is better to expose the change in Erlang system time
+      immediately. This since it makes it possible for the
+      Erlang applications executing on the system to react
+      on the change in system time as soon as possible. This
+      is also more or less exactly how most OSes handle this
+      (OS monotonic time and OS system time). By adjusting
+      system time smoothly we would just hide the fact that
+      system time changed and make it harder for the Erlang
+      applications to react to the change in a sensible way.</p>
+
+      <p>In order to be able to react to a change in Erlang
+      system time you have to be able to detect that it
+      happened. The change in Erlang system time occurs when
+      current time offset is changed. We have therefore
+      introduced the possibility to monitor the time offset
+      using
+      <seealso marker="erlang#monitor/2"><c>erlang:monitor(time_offset, clock_service)</c></seealso>. A process monitoring the time
+      offset will be sent a message on the following format
+      when the time offset is changed:</p>
+      <code type="none">{'CHANGE', MonitorReference, time_offset, clock_service, NewTimeOffset}</code>
+    </section>
+
+    <marker id="Unique_Values"/>
+    <section>
+      <title>Unique Values</title>
+      <p>Besides reporting time <c>erlang:now/0</c> also
+      produce unique and strictly monotonically increasing
+      values. In order to detach this functionality from
+      time measurements we have introduced
+      <seealso marker="erlang#unique_integer/1"><c>erlang:unique_integer()</c></seealso>.
+      </p>
+    </section>
+
+    <marker id="Dos_and_Donts"/>
+    <section>
+      <title>Dos and Don'ts</title>
+      <p>Previously <c>erlang:now/0</c> was the only option for doing
+      quite a lot of things. We will look at a few different things
+      <c>erlang:now/0</c> could be used for, and how you want to do
+      this using the new API:</p>
+
+      <marker id="Dos_and_Donts_Retrieve_Erlang_System_Time"/>
+      <section>
+	<title>Retrieve Erlang System Time</title>
+	<dont>
+	  <p>
+	    use <c>erlang:now/0</c> in order to retrieve current Erlang
+	    system time.
+	  </p>
+	</dont>
+	<do>
+	  <p>
+	    use
+	    <seealso marker="erlang#system_time/1"><c>erlang:system_time/1</c></seealso>
+	    in order to retrieve current Erlang system time on the
+	    <seealso marker="erlang#type_time_unit">time unit</seealso>
+	    of your choice.</p>
+	    <p>If you want the same format as returned by <c>erlang:now/0</c>, use
+	    <seealso marker="erlang#timestamp/0"><c>erlang:timestamp/0</c></seealso>.
+	    </p>
+	</do>
+      </section>
+
+      <marker id="Dos_and_Donts_Measure_Elapsed_Time"/>
+      <section>
+	<title>Measure Elapsed Time</title>
+	<dont>
+	  <p>
+	    take timestamps with <c>erlang:now/0</c> and calculate
+	    the difference in time with
+	    <seealso marker="stdlib:timer#now_diff/2"><c>timer:now_diff/2</c></seealso>.
+	  </p>
+	</dont>
+	<do>
+	  <p>
+	    take timestamps with
+	    <seealso marker="erlang#monotonic_time/0"><c>erlang:monotonic_time/0</c></seealso>
+	    and calculate the time difference using ordinary subtraction.
+	    The result will be in <c>native</c>
+	    <seealso marker="erlang#type_time_unit">time unit</seealso>.
+	    If you want to convert the
+	    result to another time unit you can do this using
+	    <seealso marker="erlang#convert_time_unit/3"><c>erlang:convert_time_unit/3</c></seealso>.
+	    </p>
+	    <p>Another easier way of doing this is to use
+	    <seealso marker="erlang#monotonic_time/1"><c>erlang:monotonic_time/1</c></seealso>
+	    with desired time unit. However, you may lose accuracy,
+	    and precision this way.
+	    </p>
+	</do>
+      </section>
+
+      <marker id="Dos_and_Donts_Determine_Order_of_Events"/>
+      <section>
+	<title>Determine Order of Events</title>
+	<dont>
+	  <p>
+	    determine the order of events by saving a timestamp
+	    with <c>erlang:now/0</c> when the event happens.
+	  </p>
+	</dont>
+	<do>
+	  <p>
+	    determine the order of events by saving the integer
+	    returned by
+	    <seealso marker="erlang#unique_integer/1"><c>erlang:unique_integer([monotonic])</c></seealso>
+	    when the event happens. These integers will be strictly
+	    monotonically ordered on current runtime system instance
+	    corresponding to creation time.
+	  </p>
+	</do>
+      </section>
+
+      <marker id="Dos_and_Donts_Determine_Order_of_Events_With_Time_of_the_Event"/>
+      <section>
+	<title>Determine Order of Events With Time of the Event</title>
+	<dont>
+	  <p>
+	    determine the order of events by saving a timestamp
+	    with <c>erlang:now/0</c> when the event happens.
+	  </p>
+	</dont>
+	<do>
+	  <p>
+	    determine the order of events by saving a tuple
+	    containing
+	    <seealso marker="erlang#monotonic_time/0">monotonic time</seealso>
+	    and a <seealso marker="erlang#unique_integer/1">strictly
+	    monotonically increasing integer</seealso> like this:</p>
+	    <code type="none">
+Time = erlang:monotonic_time(),
+UMI = erlang:unique_integer([monotonic]),
+EventTag = {Time, UMI}</code>
+	    <p>These tuples will be strictly monotonically ordered
+	    on the current runtime system instance according to
+	    creation time. Note that it is important that the
+	    monotonic time is in the first element (the most
+	    significant element when comparing 2-tuples). Using
+	    the monotonic time in the tuples, you can calculate time
+	    between events.</p>
+	    <p>If you are interested in the Erlang system time at the
+	    time when the event occurred you can also save the time
+	    offset before or after saving the events using
+	    <seealso marker="erlang#time_offset/0"><c>erlang:time_offset/0</c></seealso>.
+	    Erlang monotonic time added with the time
+	    offset corresponds to Erlang system time.</p>
+	    <p>If you are executing in a mode where time offset
+	    may change and you want to be able to get the actual
+	    Erlang system time when the event occurred you can
+	    save the time offset as a third element in the tuple
+	    (the least significant element when comparing 3-tuples).</p>
+	</do>
+      </section>
+
+      <marker id="Dos_and_Donts_Create_a_Unique_Name"/>
+      <section>
+	<title>Create a Unique Name</title>
+	<dont>
+	  <p>
+	    use the values returned from <c>erlang:now/0</c>
+	    in order to create a name unique on the current
+	    runtime system instance.
+	  </p>
+	</dont>
+	<do>
+	  <p>
+	    use the value returned from
+	    <seealso marker="erlang#unique_integer/0"><c>erlang:unique_integer/0</c></seealso>
+	    in order to create a name unique on the current runtime system
+	    instance. If you only want positive integers, you can use
+	    <seealso marker="erlang#unique_integer/1"><c>erlang:unique_integer([positive])</c></seealso>.
+	  </p>
+	</do>
+      </section>
+
+      <marker id="Dos_and_Donts_Seed_Random_Number_Generation_With_a_Unique_Value"/>
+      <section>
+	<title>Seed Random Number Generation With a Unique Value</title>
+	<dont>
+	  <p>
+	    seed random number generation using <c>erlang:now()</c>.
+	  </p>
+	</dont>
+	<do>
+	  <p>
+	    seed random number generation using a combination of
+	    <seealso marker="erlang#monotonic_time/0"><c>erlang:monotonic_time()</c></seealso>,
+	    <seealso marker="erlang#time_offset/0"><c>erlang:time_offset()</c></seealso>,
+	    <seealso marker="erlang#unique_integer/0"><c>erlang:unique_integer()</c></seealso>, and other functionality.
+	  </p>
+	  </do>
+      </section>
+
+      <p>To sum this section up: <em>Don't use <c>erlang:now/0</c>!</em></p>
+    </section>
   </section>
+
+  <marker id="Supporting_Both_New_and_Old_OTP_Releases"/>
   <section>
-    <title>Turning off time correction</title>
-    <p>If, for some reason, time correction causes trouble and you are
-    absolutely confident that the wall clock on the system is nearly
-    perfect, you can turn off time correction completely by giving the
-    <c>+c</c> option to <c>erl</c>. The probability for this being a
-    good idea, is very low.</p>
+    <title>Supporting Both New and Old OTP Releases</title>
+    <p>Your code may be required to be able to run on a variety 
+    of OTP installations of different OTP releases. If so, you
+    can not just use the new API out of the box, since it will
+    not be available on old pre OTP 18 releases. The solution
+    is <em>not</em> to avoid using the new API, since your
+    code then won't be able to benefit from the scalability
+    and accuracy improvements made. Instead you want to use the
+    new API when available, and fall back on <c>erlang:now/0</c>
+    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>).
+    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
+    the problem is solved. These wrappers can for example
+    be implemented as in
+    <url href="time_compat.erl"><c>$ERL_TOP/erts/example/time_compat.erl</c></url>.</p>
   </section>
 </chapter>
-