From 6487aac5977cf470bc6a2cd0964da2850ee38717 Mon Sep 17 00:00:00 2001 From: Rickard Green Date: Thu, 30 Oct 2014 23:57:01 +0100 Subject: Introduce a new time API The old time API is based on erlang:now/0. The major issue with erlang:now/0 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. The new API consists of a number of new BIFs: - erlang:convert_time_unit/3 - erlang:monotonic_time/0 - erlang:monotonic_time/1 - erlang:system_time/0 - erlang:system_time/1 - erlang:time_offset/0 - erlang:time_offset/1 - erlang:timestamp/0 - erlang:unique_integer/0 - erlang:unique_integer/1 - os:system_time/0 - os:system_time/1 and a number of extensions of existing BIFs: - erlang:monitor(time_offset, clock_service) - erlang:system_flag(time_offset, finalize) - erlang:system_info(os_monotonic_time_source) - erlang:system_info(time_offset) - erlang:system_info(time_warp_mode) - erlang:system_info(time_correction) - erlang:system_info(start_time) See the "Time and Time Correction in Erlang" chapter of the ERTS User's Guide for more information. --- erts/doc/src/Makefile | 2 + erts/doc/src/erl.xml | 47 +- erts/doc/src/erlang.xml | 775 +++++++++++++++++++++++++++----- erts/doc/src/time_correction.xml | 923 +++++++++++++++++++++++++++++++-------- 4 files changed, 1447 insertions(+), 300 deletions(-) (limited to 'erts/doc/src') 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 d11f6b0c6d..19a8e1f789 100644 --- a/erts/doc/src/erl.xml +++ b/erts/doc/src/erl.xml @@ -495,24 +495,35 @@ , not (). Note also that is used instead of on Windows.

- - -

Disable compensation for sudden changes of system time.

-

Normally, will not immediately reflect - sudden changes in the system time, in order to keep timers - (including ) working. Instead, the time - maintained by 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.)

-

When the option is given, this slow adjustment - will not take place. Instead will always - reflect the current system time. Note that timers are based - on . If the system time jumps, timers - then time out at the wrong time.

-

NOTE: You can check whether the adjustment is enabled or - disabled by calling - erlang:system_info(tolerant_timeofday).

+ + +

Enable or disable + time correction:

+ + true +

Enable time correction. This is the default if + time correction is supported on the specific platform.

 + + false +

Disable time correction.

 + +

For backwards compatibility, the boolean value can be omitted. + This is interpreted as +c false. +

+ + + +

Set + time warp mode: +

+ + no_time_warp +

No Time Warp Mode (the default)

 + single_time_warp +

Single Time Warp Mode

 + multi_time_warp +

Multi Time Warp Mode

 + diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 483d81cfb6..3cbfd372ce 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -58,7 +58,71 @@ -

See now/0.

+

See erlang:timestamp/0.

+ + + + + +

Currently supported time unit representations:

+ + PartsPerSecond :: integer() >= 1 +

Time unit expressed in parts per second. That is, + the time unit equals 1/PartsPerSecond second.

 + + seconds +

Symbolic representation of the time unit + represented by the integer 1.

 + + milli_seconds +

Symbolic representation of the time unit + represented by the integer 1000.

 + + micro_seconds +

Symbolic representation of the time unit + represented by the integer 1000000.

 + + nano_seconds +

Symbolic representation of the time unit + represented by the integer 1000000000.

 + + native +

Symbolic representation of the native time unit + used by the Erlang runtime system.

+ +

The native 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 native time unit of the new + runtime system instance may differ from the + native time unit of the old runtime system + instance.

+ +

One can get an approximation of the native + time unit by calling erlang:convert_time_unit(1, + seconds, native). The result equals the number + of whole native time units per second. In case + the number of native time units per second does + not add up to a whole number, the result will be + rounded downwards.

+ + +

The value of the native 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.

+ + + + + +

The time_unit/0 type may be extended. Use + erlang:convert_time_unit/3 + in order to convert time values between time units.

+ @@ -584,6 +648,22 @@ + + + Convert time unit of a time value + +

Converts the Time value of time unit + FromUnit to the corresponding + ConvertedTime value of time unit + ToUnit. The result is rounded + using the floor function.

+ +

You may lose accuracy and precision when converting + between time units. In order to minimize such loss, collect all + data at native time unit and do the conversion on the end + result.

 + + Compute crc32 (IEEE 802.3) checksum @@ -2191,14 +2271,15 @@ os_prompt% - Return an almost unique reference + Return a unique reference -

Returns an almost unique reference.

-

The returned reference will re-occur after approximately 2^82 - calls; therefore it is unique enough for practical purposes.

- 
-> make_ref().
-#Ref<0.0.0.135>
+

Return a unique + reference. The reference is unique among + connected nodes.

+

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.

 @@ -2499,97 +2580,178 @@ os_prompt% - + + + + + Start monitoring -

The calling process starts monitoring Item which is - an object of type Type.

-

Currently only processes can be monitored, i.e. the only - allowed Type is process, but other types may be - allowed in the future.

-

Item can be:

- - pid() - -

The pid of the process to monitor.

- - {RegName, Node} - -

A tuple consisting of a registered name of a process and - a node name. The process residing on the node Node - with the registered name RegName will be monitored.

- - RegName - -

The process locally registered as RegName will be - monitored.

- - - -

When a process is monitored by registered name, the process - that has the registered name at the time when - monitor/2 is called will be monitored. +

Send a monitor request of type Type to the + entity identified by Item. The caller of + monitor/2 will later be notified by a monitor message on the + following format if the monitored state is changed:

+ {Tag, MonitorRef, Type, Object, Info} +

The monitor request is an asynchronous signal. That is, it + takes time before the signal reach its destination.

 +

Currently valid Types:

+ + process + +

Monitor the existence of the process identified by + Item. Currently valid + Items in combination with the + process Type:

+ + pid() + +

The process identifier of the process to monitor.

+ + {RegisteredName, Node} + +

A tuple consisting of a registered name of a process and + a node name. The process residing on the node Node + with the registered name {RegisteredName, Node} will + be monitored.

+ + RegisteredName + +

The process locally registered as RegisteredName + will become monitored.

+ + +

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.

- -

A 'DOWN' message will be sent to the monitoring - process if Item dies, if Item does not exist, - or if the connection is lost to the node which Item - resides on. A 'DOWN' message has the following pattern:

- -{'DOWN', MonitorRef, Type, Object, Info} -

where MonitorRef and Type are the same as - described above, and:

- - Object - -

A reference to the monitored object:

- - the pid of the monitored process, if Item was - specified as a pid. - {RegName, Node}, if Item was specified as - {RegName, Node}. - {RegName, Node}, if Item was specified as - RegName. Node will in this case be the - name of the local node (node()). - - - Info - -

Either the exit reason of the process, noproc - (non-existing process), or noconnection (no - connection to Node).

- - - -

If/when monitor/2 is extended (e.g. to - handle other item types than process), other - possible values for Object, and Info in the - 'DOWN' message will be introduced.

- -

The monitoring is turned off either when the 'DOWN' - message is sent, or when - demonitor/1 - is called.

-

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 badarg.

-

Making several calls to monitor/2 for the same - Item is not an error; it results in as many, completely - independent, monitorings.

+ unregistered, or unregistered and later registered on another + process.

 +

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.

+

When the monitor is triggered a 'DOWN' message will + be sent to the monitoring process. A 'DOWN' message has + the following pattern:

+ {'DOWN', MonitorRef, Type, Object, Info} +

where MonitorRef and Type are the same as + described above, and:

+ + Object + +

equals:

+ + Item + If Item was specified by a + pid. + {RegisteredName, Node} + If Item was specified as + RegisteredName, or {RegisteredName, Node} + where Node corresponds to the node that the + monitored process resides on. + + + Info + +

Either the exit reason of the process, noproc + (non-existing process), or noconnection (no + connection to the node where the monitored process + resides).

 + +

The monitoring is turned off either when the 'DOWN' + message is sent, or when + demonitor/1 + is called.

+

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 badarg.

+ +

The format of the 'DOWN' message changed in the 5.2 + version of the emulator (OTP release R9B) for monitor + by registered name. The Object element of + the 'DOWN' message could in earlier versions + sometimes be the pid of the monitored process and sometimes + be the registered name. Now the Object 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 'DOWN' messages on + the new format even if they are monitoring processes on old + nodes. Processes on old nodes will always get 'DOWN' + messages on the old format.

+ + + time_offset + +

Monitor changes in + time offset + between + Erlang + monotonic time and + Erlang + system time. There is only one valid + Item in combination with the + time_offset Type, namely the atom + clock_service. Note that the atom clock_service is + not 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.

+ +

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 + finalization + of the time offset when the + single + time warp mode 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.

+ +

If the runtime system is in + multi + time warp mode, the time offset will be changed when + the runtime system detects that the + OS system + time 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.

+ +

The monitor will not be automatically removed + after it has been triggered. That is, repeated changes of + the time offset will trigger the monitor repeatedly.

+ +

When the monitor is triggered a 'CHANGE' message will + be sent to the monitoring process. A 'CHANGE' message has + the following pattern:

+ {'CHANGE', MonitorRef, Type, Item, NewTimeOffset} +

where MonitorRef, Type, and + Item are the same as described above, and + NewTimeOffset is the new time offset.

+ +

When the 'CHANGE' message has been received you are + guaranteed not to retrieve the old time offset when calling + erlang:time_offset(). + Note that you may observe the change of the time offset + when calling erlang:time_offset() before you + get the 'CHANGE' message.

+ + + +

Making several calls to monitor/2 for the same + Item and/or Type is not + an error; it results in many, completely independent, + monitorings.

+

The monitor functionality is expected to be extended. That is, + other Types and Items + are expected to be supported in the future.

-

The format of the 'DOWN' message changed in the 5.2 - version of the emulator (OTP release R9B) for monitor by registered name. The Object element of - the 'DOWN' message could in earlier versions - sometimes be the pid of the monitored process and sometimes - be the registered name. Now the Object 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 'DOWN' messages on - the new format even if they are monitoring processes on old - nodes. Processes on old nodes will always get 'DOWN' - messages on the old format.

+

If/when monitor/2 is extended, other + possible values for Tag, Object, and + Info in the monitor message will be introduced.

 @@ -2639,6 +2801,51 @@ os_prompt% option list is malformed.

+ + + Current Erlang monotonic time + +

Returns the current + Erlang + monotonic time in native + time unit. This + is a monotonically increasing time since some unspecified point in + time.

+ +

This is a + monotonically increasing time, but not a + strictly monotonically increasing + time. That is, consecutive calls to + erlang:monotonic_time/0 may produce the same result.

+ +

Different runtime system instances will use different + unspecified points in time as base for their Erlang monotonic clocks. + That is, it is pointless 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 + erlang:system_info(start_time).

 + + + + + Current Erlang monotonic time + +

Returns the current + Erlang + monotonic time converted + into the Unit passed as argument.

+ +

Same as calling + erlang:convert_time_unit(erlang:monotonic_time(), + native, Unit) + however optimized for commonly used Units.

+ + Stop execution with a given reason @@ -2734,6 +2941,13 @@ os_prompt% Elapsed time since 00:00 GMT +

This function is deprecated! Do not use it! + See the users guide chapter + Time and Time Correction + for more information. Specifically the + Dos and Dont's + section for information on what to use instead of erlang:now/0. +

Returns the tuple {MegaSecs, Secs, MicroSecs} which is the elapsed time since 00:00 GMT, January 1, 1970 (zero hour) on the assumption that the underlying OS supports this. @@ -2746,10 +2960,6 @@ os_prompt%

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.

-

If you do not need the return value to be unique and - monotonically increasing, use - os:timestamp/0 - instead to avoid some overhead.

 @@ -5496,6 +5706,35 @@ ok

Returns the old value of the flag.

 + + + + Finalize the Time Offset + +

Finalizes the time offset + when the single + time warp mode is being used. If another time warp mode than + the "single time warp mode" is used, the time offset state will be left + unchanged.

+

Returns the old state identifier. That is, if:

+ +

preliminary is returned, finalization was + performed and the time offset is now final.

 + +

final is returned, the time offset was + already in the final state. This either due to another + erlang:system_flag(time_offset, finalize) call, or + due to the + no + time warp mode being used.

 + +

volatile is returned, the time offset + cannot be finalized due to the + multi + time warp mode being used.

 + + + @@ -5776,6 +6015,15 @@ ok + + + + + + + + + Information about the system

Returns various information about the current system @@ -6163,6 +6411,57 @@ ok documentation of versions in the system principles guide.

 + os_monotonic_time_source + +

Returns a list containing information about the source of + OS + monotonic time that is used by the runtime system.

+

In case [] is returned, no OS monotonic time is + available. The list contains two-tuples with Keys + as first element, and Values 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:

+ + {function, Function} +

Function is the name of the funcion + used. This tuple always exist if OS monotonic time is + available to the runtime system.

 + + {clock_id, ClockId} +

This tuple only exist if Function + can be used with different clocks. ClockId + corresponds to the clock identifer used when calling + Function.

 + + {resolution, OsMonotonicTimeResolution} +

Highest possible resolution of current + OS monotonic time source as parts per second. If + no resolution information can be retreived from + the OS, OsMonotonicTimeResolution will be + set to the resolution of the time unit of + Functions return value. That is, the actual + resolution may be lower than + OsMonotonicTimeResolution. 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 + OsMonotonicTimeResolution.

 + + {parallel, Parallel} +

Parallel equals yes if + Function is called in parallel from multiple + threads. If it is not called in parallel, because + calls needs to be serialized, Parallel equals + no.

 + + {time, OsMonotonicTime} +

OsMonotonicTime equals current OS + monotonic time in native + time unit.

 + + port_parallelism

Returns the default port parallelism scheduling hint used. For more information see the @@ -6288,6 +6587,11 @@ ok

Returns true if the emulator has been compiled with smp support; otherwise, false.

 + start_time +

The Erlang monotonic + time in native + time unit at the + time when current Erlang runtime system instance started.

 system_version

Returns a string containing version number and @@ -6311,12 +6615,64 @@ ok (driver_async()) as an integer.

 + time_correction +

Returns a boolean value indicating whether + time correction + is enabled or not. +

+ time_offset +

Returns the state of the time offset:

+ + preliminary +

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 + single + time warp mode.

 + + final +

The time offset is final. This + either due to the use of the + no + time warp mode, or due to the time offset having + been finalized when using the + single + time warp mode.

 + + volatile +

The time offset is volatile. That is, it may + change at any time. This due to the + multi + time warp mode being used.

 + + + time_warp_mode +

Returns a value identifying the + time warp + mode being used:

+ + no_time_warp +

The no + time warp mode is being used.

 + + single_time_warp +

The single + time warp mode is being used.

 + + multi_time_warp +

The multi + time warp mode is being used.

 + + tolerant_timeofday -

Returns whether compensation for sudden changes of system - time is enabled or disabled.

-

See also +c - command line flag.

+

Returns whether a pre erts-7.0 backwards compatible compensation + for sudden changes of system time is enabled or disabled. + Such compensation is enabled when the + time offset is + final, and + time correction + is enabled.

 trace_control_word @@ -6595,7 +6951,44 @@ ok + + + Current Erlang system time + +

Returns current + Erlang system time + in native + time unit.

+

Calling erlang:system_time() is equivalent to: + erlang:monotonic_time() + + + erlang:time_offset().

+ +

This time is not a monotonically increasing time + in the general case. For more information, see the documentation of + time warp modes in the + ERTS User's Guide.

 + + + + + Current Erlang system time + +

Returns current + Erlang system time + converted into the Unit passed as argument.

+ +

Calling erlang:system_time(Unit) is equivalent to: + erlang:convert_time_unit(erlang:system_time(), + native, Unit).

+ +

This time is not a monotonically increasing time + in the general case. For more information, see the documentation of + time warp modes in the + ERTS User's Guide.

 + + Encode a term to an Erlang external term format binary @@ -6671,6 +7064,88 @@ ok {9,42,44} + + + Current time offset + +

Returns the current time offset between + Erlang monotonic time + and + Erlang system time in + native time unit. + Current time offset added to an Erlang monotonic time gives + corresponding Erlang system time.

+ +

The time offset may or may not change during operation depending + on the time + warp mode used.

+ + +

A change in time offset may be observed at slightly + different points in time by different processes.

+ +

If the runtime system is in + multi + time warp mode, the time offset will be changed when + the runtime system detects that the + OS system + time 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.

+ + + + + + Current time offset + +

Returns the current time offset between + Erlang monotonic time + and + Erlang system time + converted into the Unit passed as argument.

+ +

Same as calling + erlang:convert_time_unit(erlang:time_offset(), native, Unit) + however optimized for commonly used Units.

+ + + + + + Current Erlang System time + +

Returns current + Erlang system time + on the format {MegaSecs, Secs, MicroSecs}. This format is + the same that os:timestamp/0 + and the now deprecated erlang:now/0 + uses. The reason for the existence of erlang:timestamp() 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 + erlang:system_time/1.

+ +

The erlang:timestamp() BIF is equivalent to:

+timestamp() -> + ErlangSystemTime = erlang:system_time(micro_seconds), + MegaSecs = ErlangSystemTime div 1000000000000, + Secs = ErlangSystemTime div 1000000 - MegaSecs*1000000, + MicroSecs = ErlangSystemTime rem 1000000, + {MegaSecs, Secs, MicroSecs}. +

It however use a native implementation which does + not build garbage on the heap and with slightly better + performance.

+ +

This time is not a monotonically increasing time + in the general case. For more information, see the documentation of + time warp modes in the + ERTS User's Guide.

 + + + Tail of a list @@ -7435,6 +7910,100 @@ ok a valid date and time.

 + + + Get a unique integer value + +

Generates and returns an + integer + unique on current runtime system instance. The same as calling + erlang:unique_integer([]).

+ + + + + Get a unique integer value + +

Generates and returns an + integer + unique on current runtime system + instance. 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.

+ +

By default, i.e. when [] is passed as + ModifierList, 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.

+ +

Currently valid Modifiers:

+ + + positive +

Return only positive integers.

+

Note that by passing the positive modifier + you will get heap allocated integers (big-nums) + quicker.

+ + + monotonic +

Return + strictly + monotonically increasing integers + corresponding to creation time. That is, the integer + returned will always be larger than previously + returned integers on the current runtime system + instance.

+

These values can be used when ordering events + on the runtime system instance. That is, if both + X = erlang:unique_integer([monotonic]) and + Y = erlang:unique_integer([monotonic]) are + executed by different processes (or the same + process) on the same runtime system instance and + X < Y we know that X was created + before Y.

+

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 monotonic + modifier unless you really need strictly monotonically + increasing values.

 + + + + +

All currently valid Modifiers + can be combined. Repeated (valid) + Modifiers in the ModifierList + are ignored.

+ +

Note that the set of integers returned by + unique_integer/1 using diffrent sets of + Modifiers will overlap. + For example, by calling unique_integer([monotonic]), + and unique_integer([positive, monotonic]) + repeatedly, you will eventually see some integers being + returned by both calls.

 + +

Failures:

+ + badarg + if ModifierList is not a + proper list. + badarg + if Modifier is not a + valid modifier. + + + Remove a link, if there is one, to another process or port 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 @@ - Time and time correction in Erlang - Patrik Nyblom + Time and Time Correction in Erlang + @@ -31,6 +31,176 @@ PA1 time_correction.xml + +
+ New Extended Time Functionality +

As of OTP 18 (ERTS version 7.0) the time functionality of + Erlang has been extended. This both includes a + new API + for time, as well as + time warp + modes which alters the behavior of the system when + system time changes.

+

The default + time warp mode 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, you are strongly + encouraged to use the new API instead of the old API based + on erlang:now/0. + erlang:now/0 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 + multi time warp mode + which improves accuracy, and precision of time measurements.

 +
+ +
+ Some Terminology +

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.

+ + +
+ Monotonically Increasing +

In a monotonically increasing sequence of values, all values + that have a predecessor are either larger than, or equal to its + predecessor.

+
+ + +
+ Strictly Monotonically Increasing +

In a strictly monotonically increasing sequence of values, + all values that have a predecessor are larger than its + predecessor.

+
+ + +
+ UT1 +

Universal Time. Based on the rotation of the earth. Conceptually + mean solar time at 0° longitude.

+
+ + +
+ UTC +

Coordinated Universal Time. UTC almost align with + UT1, 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.

+
+ + +
+ POSIX Time +

Time since + Epoch. + Epoch is defined to be 00:00:00 UTC, + January 1, 1970. + A day in POSIX time + 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 + "POSIX time is therefore not necessarily UTC, despite its appearance". 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.

+
+ + +
+ OS System Time +

The operating systems view of + POSIX time. It can be + retrieved by calling + os:system_time(). + 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.

+
+ + +
+ OS Monotonic Time +

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 + OS system time. Note that + this type of time is not necessarily provided by all operating + systems.

+
+ + +
+ Erlang System Time +

The Erlang runtime systems view of + POSIX time. It can be + retrieved by calling + erlang:system_time(). + This time may or may not be an accurate view of POSIX time, and may + or may not align with OS system + time. The time + warp mode determines how it behaves when OS system + time suddenly change.

+
+ + +
+ Erlang Monotonic Time +

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 + erlang:monotonic_time(). + The accuracy, and precision of Erlang monotonic time heavily + depends on the accuracy and precision of + OS monotonic time, + the accuracy and precision of + OS system time as well + as on the + time warp mode + 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.

+ +

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 receive ... after timer, BIF timer, + or a timer in the timer module are triggered + relative Erlang monotonic time. Even + Erlang system + time 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 + erlang:time_offset/0. +

+
+ + +
+ Time Warp +

A time warp is a leap forwards or backwards in time.

+
+ +
+ +
+ Introduction +

Time is vital to an Erlang program and, more importantly, correct 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.

-

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).

- -

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:

- - Monotonic - The clock should not move backwards - Intervals should be near the truth - 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. - Tight coupling to the wall clock - 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 - -

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.

- -

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.

- -

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.

+
+
- What does time correction mean in my system? -

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.

- -

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.

- -

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.

- -

Still, the time correction will mean that your system keeps - it's real time characteristics very well, even when the wall clock - is unreliable.

+ Time Correction +

If time correction is enabled, the Erlang runtime system + will make use of both + OS system time + and OS monotonic time, + in order to make adjustments of the frequency of the Erlang + monotonic clock. Time correction will ensure that + Erlang monotonic time + 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 time warp modes + section below.

+ +

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 + erlang:system_info(os_monotonic_time_source), + and you can check if time correction is enabled on your + system by calling + erlang:system_info(time_correction).

+ +

Time correction is enabled or disabled by passing the + +c [true|false] + command line argument to erl.

+ +

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.

+ +

You typically never want to disable time correction. + 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.

+ + +
- Where does Erlang use corrected time? -

For all functionality where real time characteristics are - desirable, time correction is used. This basically means:

- - erlang:now/0 - 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. - receive ... after - Timeouts on receive uses time correction to determine a - stable timeout interval. - The timer module - As the timer module uses other built in functions which - deliver corrected time, the timer module itself works with - corrected time. - erlang:start_timer/3 and erlang:send_after/3 - 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. - - -

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).

- -

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.

+ Time Warp Safe Code +

Time warp safe code is code that is able to handle + a time warp of + Erlang system time. +

+ +

erlang:now/0 + behaves very bad when Erlang system time warps. When Erlang + system time do a time warp backwards, the values returned + from erlang:now/0 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 + erlang:now/0. This freeze might continue for very + long periods of time. It might take years, decades, + and even longer than this until the freeze stops.

+ +

All uses of erlang:now/0 are not necessarily + time warp unsafe. If you do not use it to get time, it + will be time warp safe. However all uses of + erlang:now/0 are suboptimal 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 erlang:now/0, + see the Dos and Donts + section.

+ +
- What is erlang:now/0 really? -

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:

- - Monotonic - erlang:now() never jumps backwards - it always moves - forward - Interval correct - 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) - Absolute correctness - 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) - System correspondence - 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) - Unique - No two calls to erlang:now on one Erlang node should - return the same value - -

All these requirements are possible to uphold at the same - time if (and only if):

- - The wall clock time of the system is perfect - 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. - Less than one call per microsecond to erlang:now/0 is - done - This means that at any 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). - -

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.

+ Time Warp Modes + +

Current Erlang system + time is determined by adding current + Erlang monotonic time + with current + time offset. The + time offset is managed differently depending on which time + warp mode you use. The time warp mode is set by passing the + +C + [no_time_warp|single_time_warp|multi_time_warp] + command line argument to erl.

+ + +
+ No Time Warp Mode +

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 + time warp safe + before you can enable other modes.

+ +

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.

+ +

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.

+
+ + +
+ Single Time Warp Mode +

This mode is more or less a backwards compatibility mode + as of its introduction.

+

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 + no time warp mode + 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.

+

If you for some reason need to use Erlang code that + is not + time warp safe, + 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 multi time warp + mode instead. +

+ +

Using the single time warp mode, the time offset is + handled in two phases:

+ + + Preliminary Phase + +

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.

+ +

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.

+ +

If time correction is disabled, changes in OS system + time will effect the monotonic clock the same way as + when the no time warp + mode is used.

+ + + Final Phase + + +

The final phase begin when the user finalize the time + offset by calling + erlang:system_flag(time_offset, finalize). + The finalization can only be performed once. +

+ +

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 + no time warp + mode.

+ + + + +

In order for this to work properly there are two + requirements that the user needs to ensure are + satisfied:

+ + + Forward Time Warp +

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.

 + + Finalize Correct OS System Time +

The OS system time needs to be correct when the + the user finalizes the time offset.

 + + +

If these requirements are not fulfilled, the system + may behave very bad. +

+ +

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.

+ +

In order to be able to use this mode you have + to ensure that all Erlang code that will execute in + both phases are + time warp + safe.

+

Code that only execute in the final phase does not have + to be able to cope with the time warp.

 + +
+ + +
+ Multi Time Warp Mode + +

Multi time warp mode in combination with time + correction is the preferred configuration. 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.

+ +

The time offset may change at any time without limitations. + That is, Erlang system time may perform time warps both + forwards and backwards at any 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.

+ +

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.

+ +

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 + time warp + safe.

 +
+ +
- Should I use erlang:now/0 or os:timestamp/0 -

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.

+ The New Time API + +

The old time API is based on + erlang:now/0. + The major issue with erlang:now/0 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.

+ +

In order to be backwards compatible erlang:now/0 will + remain as is, but you are strongly discouraged from using + it. A lot of uses of erlang:now/0 will also + prevent you from using the new + multi time warp + mode which is an important part of this + new time functionality improvement.

+ +

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.

+ +

The new API consists of a number of new BIFs:

+ +

erlang:convert_time_unit/3

 +

erlang:monotonic_time/0

 +

erlang:monotonic_time/1

 +

erlang:system_time/0

 +

erlang:system_time/1

 +

erlang:time_offset/0

 +

erlang:time_offset/1

 +

erlang:timestamp/0

 +

erlang:unique_integer/0

 +

erlang:unique_integer/1

 +

os:system_time/0

 +

os:system_time/1

 + +

and a number of extensions of existing BIFs:

+ +

erlang:monitor(time_offset, clock_service)

 +

erlang:system_flag(time_offset, finalize)

 +

erlang:system_info(os_monotonic_time_source)

 +

erlang:system_info(time_offset)

 +

erlang:system_info(time_warp_mode)

 +

erlang:system_info(time_correction)

 +

erlang:system_info(start_time)

 + + + +
+ The New Erlang Monotonic Time +

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.

+ +

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 + multi + time warp mode. 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.

+ +

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.

+ +

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 + erlang:monitor(time_offset, clock_service). A process monitoring the time + offset will be sent a message on the following format + when the time offset is changed:

+ {'CHANGE', MonitorReference, time_offset, clock_service, NewTimeOffset} +
+ + +
+ Unique Values +

Besides reporting time erlang:now/0 also + produce unique and strictly monotonically increasing + values. In order to detach this functionality from + time measurements we have introduced + erlang:unique_integer(). +

+
+ + +
+ Dos and Don'ts +

Previously erlang:now/0 was the only option for doing + quite a lot of things. We will look at a few different things + erlang:now/0 could be used for, and how you want to do + this using the new API:

+ + +
+ Retrieve Erlang System Time + +

+ use erlang:now/0 in order to retrieve current Erlang + system time. +

+ + +

+ use + erlang:system_time/1 + in order to retrieve current Erlang system time on the + time unit + of your choice.

+

If you want the same format as returned by erlang:now/0, use + erlang:timestamp/0. +

+ +
+ + +
+ Measure Elapsed Time + +

+ take timestamps with erlang:now/0 and calculate + the difference in time with + timer:now_diff/2. +

+ + +

+ take timestamps with + erlang:monotonic_time/0 + and calculate the time difference using ordinary subtraction. + The result will be in native + time unit. + If you want to convert the + result to another time unit you can do this using + erlang:convert_time_unit/3. +

+

Another easier way of doing this is to use + erlang:monotonic_time/1 + with desired time unit. However, you may lose accuracy, + and precision this way. +

+ +
+ + +
+ Determine Order of Events + +

+ determine the order of events by saving a timestamp + with erlang:now/0 when the event happens. +

+ + +

+ determine the order of events by saving the integer + returned by + erlang:unique_integer([monotonic]) + when the event happens. These integers will be strictly + monotonically ordered on current runtime system instance + corresponding to creation time. +

+ +
+ + +
+ Determine Order of Events With Time of the Event + +

+ determine the order of events by saving a timestamp + with erlang:now/0 when the event happens. +

+ + +

+ determine the order of events by saving a tuple + containing + monotonic time + and a strictly + monotonically increasing integer like this:

+ +Time = erlang:monotonic_time(), +UMI = erlang:unique_integer([monotonic]), +EventTag = {Time, UMI} +

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.

+

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 + erlang:time_offset/0. + Erlang monotonic time added with the time + offset corresponds to Erlang system time.

+

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).

+ +
+ + +
+ Create a Unique Name + +

+ use the values returned from erlang:now/0 + in order to create a name unique on the current + runtime system instance. +

+ + +

+ use the value returned from + erlang:unique_integer/0 + in order to create a name unique on the current runtime system + instance. If you only want positive integers, you can use + erlang:unique_integer([positive]). +

+ +
+ + +
+ Seed Random Number Generation With a Unique Value + +

+ seed random number generation using erlang:now(). +

+ + +

+ seed random number generation using a combination of + erlang:monotonic_time(), + erlang:time_offset(), + erlang:unique_integer(), and other functionality. +

+ +
+ +

To sum this section up: Don't use erlang:now/0!

+
+ +
- Turning off time correction -

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 option to erl. The probability for this being a - good idea, is very low.

+ Supporting Both New and Old OTP Releases +

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 not 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 erlang:now/0 + when it is not available. Fortunately almost all of the new + API can easily be implemented using existing primitives + (except for + erlang:system_info(start_time), and + erlang:system_info(os_monotonic_time_source)). + By wrapping the API with functions that fall back on + erlang:now/0 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 + $ERL_TOP/erts/example/time_compat.erl.

- -- cgit v1.2.3