aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc
diff options
context:
space:
mode:
authorRickard Green <[email protected]>2015-03-20 21:29:30 +0100
committerRickard Green <[email protected]>2015-03-20 21:29:30 +0100
commitf4e3cd1c970cfc5ad54f2ed64832d05749c305d4 (patch)
treea008c88d68c801ac290373920435d952b027905c /erts/doc
parentc0d3f4cbb5775a9214366e0d9cb76847d69c3459 (diff)
parente7a713167e3390bfa7d7ada2eafe5fe16f185405 (diff)
downloadotp-f4e3cd1c970cfc5ad54f2ed64832d05749c305d4.tar.gz
otp-f4e3cd1c970cfc5ad54f2ed64832d05749c305d4.tar.bz2
otp-f4e3cd1c970cfc5ad54f2ed64832d05749c305d4.zip
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
Diffstat (limited to 'erts/doc')
-rw-r--r--erts/doc/src/Makefile2
-rw-r--r--erts/doc/src/erl.xml47
-rw-r--r--erts/doc/src/erlang.xml775
-rw-r--r--erts/doc/src/time_correction.xml923
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>
-