From a50c470e3d1af4660c09d993495dea56c50ad306 Mon Sep 17 00:00:00 2001
From: xsipewe As of OTP 18 (ERTS version 7.0) the time functionality of
- Erlang has been extended. This both includes a
+ As of OTP 18 ( The By using the new API, you
automatically get scalability and performance improvements. This
- will also enable you to use the
- In order to make it easier to understand this document we first
- define some terminology. This is a mixture of our own terminology
+ To make it easier to understand this section, some terms
+ are defined. This is a mix of our own terminology
(Erlang/OS system time, Erlang/OS monotonic time, time warp)
and globally accepted terminology. In a monotonically increasing sequence of values, all values
- that have a predecessor are either larger than, or equal to its
+ that have a predecessor are either larger than or equal to its
predecessor. Universal Time. Based on the rotation of the earth. Conceptually
- mean solar time at 0° longitude. Universal Time. UT1 is based on the rotation of the earth
+ and conceptually means solar time at 0° longitude. Coordinated Universal Time. UTC almost align with
- Coordinated Universal Time. UTC almost aligns with
+ Time since
The shortest time interval that can be be distinguished
+ The shortest time interval that can be distinguished
repeatedly and reliably when reading time values. Precision
is limited by the
A time warp is a leap forwards or backwards in time. That is, the difference of time values taken before and after the - time warp will not correspond to the actual elapsed time.
+ time warp does not correspond to the actual elapsed time.The operating systems view of
-
To get information about the Erlang runtime
+ system's source of OS system time, call
A monotonically increasing time provided by the operating
- system. This time does not leap and have a relatively steady
+ system. This time does not leap and has 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
+ uncommon that OS monotonic time stops if the system is
+ suspended. This time typically increases since some
unspecified point in time that is not connected to
-
To get information about the Erlang
+ runtime system's source of OS monotonic time, call
The Erlang runtime systems view of
-
This time may or may not be an accurate view of POSIX time,
+ and may
or may not align with
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 runtime system. Erlang monotonic time increases since
+ some unspecified point in time. To retrieve it, call
The
Internally in the runtime system the Erlang monotonic + monotonic time heavily depends on the following:
+ +On a system without OS monotonic time, Erlang monotonic + time guarantees monotonicity, but cannot give + other guarantees. The frequency adjustments made to + Erlang monotonic time depend on the time warp mode used.
+ +Internally in the runtime system, Erlang monotonic
time is the "time engine" that is used for more or less
- everything that has anything to do with time. All timers
+ everything that has anything to do with time. All timers,
regardless of it is a
To retrieve current time offset, call
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 - time in our programs, the Virtual Machine and the language has to be - very careful about what is considered a correct point in time and in + soft real-time properties and we can express + time in our programs, the Virtual Machine and the language must be + careful about what is considered a correct time and in how time functions behave.
-In the beginning, Erlang was constructed assuming that the wall +
When Erlang was designed, it was assumed that the wall clock time in the system showed a monotonic time moving forward at - exactly the same pace as the definition of time. That more or less - meant that an atomic clock (or better) was expected to be attached + exactly the same pace as the definition of time. This more or less meant + that an atomic clock (or better time source) was expected to be attached to your hardware and that the hardware was then expected to be - locked away from any human (or unearthly) tinkering for all - eternity. While this might be a compelling thought, it's simply - never the case.
- -A "normal" modern computer can not keep time. Not on itself and - not unless you actually have a chip level atomic clock wired to - it. Time, as perceived by your computer, will normally need to be - corrected. Hence the NTP protocol that together with the ntpd - process will do it's best to keep your computers time in sync with - the "real" time in the universe. Between NTP corrections, usually a + locked away from any human tinkering forever. While this can be a + compelling thought, it is simply never the case.
+ +A "normal" modern computer cannot keep time, not on itself and
+ not unless you have a chip-level atomic clock wired to it. Time,
+ as perceived by your computer, must normally be corrected. Hence
+ the Network Time Protocol (NTP) protocol, together with the
But NTP is not fail safe. The NTP server can be unavailable, the - ntp.conf can be wrongly configured or your computer may from time to - time be disconnected from the internet. Furthermore you can have a - user (or even system administrator) on your system that thinks the - right way to handle daylight saving time is to adjust the clock one - hour two times a year (a tip, that is not the right way to do - it...). To further complicate things, this user fetched your - software from the internet and has never ever thought about what's - the correct time as perceived by a computer. The user simply does - not care about keeping the wall clock in sync with the rest of the - universe. The user expects your program to have omnipotent knowledge +
However, NTP is not fail-safe. The NTP server can be unavailable,
+
Most programmers also expect time to be reliable, at least until - they realize that the wall clock time on their workstation is of by - a minute. Then they simply set it to the correct time, maybe or - maybe not in a smooth way. Most probably not in a smooth way.
+ they realize that the wall clock time on their workstation is off by + a minute. Then they set it to the correct time, but most probably + not in a smooth way. -The amount of problems that arise when you expect the wall clock - time on the system to always be correct may be immense. Therefore Erlang +
The number of problems that arise when you always expect the wall clock + time on the system to be correct can be immense. Erlang therefore introduced the "corrected estimate of time", or the "time - correction" many years ago. The time correction relies on the fact + correction", many years ago. The time correction relies on the fact that most operating systems have some kind of monotonic clock, - either a real time extension or some built in "tick counter" that is - independent of the wall clock settings. This counter may have - microsecond resolution or much less, but generally it has a drift - that is not to be ignored.
- + either a real-time extension or some built-in "tick counter" that is + independent of the wall clock settings. This counter can have + microsecond resolution or much less, but it has a drift that cannot + be ignored.If time correction is enabled, the Erlang runtime system
- will make use of both
+ makes use of both
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
-
By default time correction is enabled if support for
+ it exists on the specific platform. Support for it includes
+ both OS monotonic time, provided by the OS, and an
+ implementation in the Erlang runtime system using
+ OS monotonic time. To check if your system has support
+ for OS monotonic time, call
+
Time correction is enabled or disabled by passing the +
To enable or disable time correction, pass command-line argument
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 + may warp forwards or stop, or even freeze for extended + periods of time. There are then 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, + Previously a performance penalty was associated with time + correction, but nowadays it is usually the other way around. + If time correction is disabled, you probably get bad scalability, bad performance, and bad time measurements.
Time warp safe code is code that is able to handle +
Time warp safe code can handle
a
All uses of
Current
To set the time warp mode, pass command-line argument
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
+ and does not change later. This is the default behavior, but
+ not because it is the best mode (which it is not). It is
default only because this is how the runtime system
- always has behaved up until ERTS version 7.0, and you have to
- ensure that your Erlang code that may execute during a time
+ behaved until
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 +
As the time offset is not allowed to change, time + correction must adjust the frequency of the Erlang + monotonic clock to align Erlang system time with OS + system time smoothly. A significant 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 + error can be as large 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.
+If time correction is not enabled, Erlang monotonic + time freezes when OS system time leaps backwards. + The freeze of monotonic time continues until + OS system time catches up. The freeze can continue for + a long time. When OS system time leaps forwards, + Erlang monotonic time also leaps forward.
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
+ has no power supply, not even a battery, when it is
+ shut off. The system clock on such a system is typically
+ way off when the system boots. If
If you for some reason need to use Erlang code that - is not + OS system time has been corrected, Erlang system time + can be wrong for a long time, centuries or even longer.
+ +If you need to use Erlang code that is not
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
Using the single time warp mode, the time offset is handled in two phases:
@@ -438,158 +452,150 @@The preliminary phase starts when the runtime +
This 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.
+ current OS system time is determined. This offset is from + now on to be fixed during the whole preliminary phase.If time correction is enabled, adjustments to the - Erlang monotonic clock will be made to keep its - frequency as correct as possible, but no - adjustments will be made trying to align Erlang system - time and OS system time. That is, during the preliminary - Erlang system time and OS system time might diverge - from each other, and no attempt to prevent this will - be made.
+ Erlang monotonic clock are made to keep its + frequency as correct as possible. However, no + adjustments are made trying to align Erlang system + time and OS system time. That is, during the preliminary phase + Erlang system time and OS system time can diverge + from each other, and no attempt is made to prevent this.If time correction is disabled, changes in OS system
- time will effect the monotonic clock the same way as
+ time affects the monotonic clock the same way as
when the
The final phase begin when the user finalize the time +
This phase begins when the user finalizes the time
offset by calling
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
- change during the finalization, 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.
+ fixated so that current Erlang system time aligns with
+ current OS system time. As the time offset can
+ change during the finalization, Erlang system time
+ can do a time warp at this point. The time offset is
+ from now on fixed until the runtime system terminates.
If time correction has been enabled, the time
- correction will from now on also make adjustments
- in order to align Erlang system time with OS system
- time. When the system is in the final phase it behaves
+ correction from now on also makes adjustments
+ to align Erlang system time with OS system
+ time. When the system is in the final phase, it behaves
exactly as in the
In order for this to work properly there are two - requirements that the user needs to ensure are - satisfied:
+In order for this to work properly, the user must ensure + that the following two requirements are satisfied:
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 + This implies that the user must ensure that 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, + POSIX time before starting the Erlang runtime system.
+ +If you are not sure that 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.
The OS system time needs to be correct when the - the user finalizes the time offset.
OS system time must be correct when + 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 + may behave very bad.
+ +Assuming that these requirements are fulfilled, + time correction is enabled, and that OS system time + is adjusted using a time adjustment protocol such as NTP, + only small adjustments of Erlang monotonic + time are needed to keep system times + aligned after finalization. As long as the system is not + suspended, the largest adjustments needed are 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
+ To use this mode, ensure that
+ all Erlang code that will execute in both phases are
Code that only execute in the final phase does not have
+ Code executing only in the final phase does not have
to be able to cope with the time warp.
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.
+Multi-time warp mode in combination with time + correction is the preferred configuration. This as + the Erlang runtime system have better performance, scale + better, and behave better on almost all platforms. In + addition, the accuracy and precision of time measurements + are better. Only Erlang runtime systems executing on + ancient platforms 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 + forwards and backwards at any time. As we align + Erlang system time with 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.
+ correct as possible. This makes time measurements using + 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 + leaps forward if OS system time leaps forward. If + OS system time leaps backwards, Erlang monotonic time + stops briefly, but it does not freeze for extended periods + of time. This as the time offset is changed 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
+ To use this mode, ensure that all
+ Erlang code that will execute on the runtime system is
The old time API is based on
In order to be backwards compatible
To be backwards compatible,
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.
+ return negative integer values on a newly started runtime + system. This is not a bug, but a memory use optimization. + +The new API consists of the following new BIFs:
-The new API consists of a number of new BIFs:
and a number of extensions of existing BIFs:
+ +The new API also consists of extensions of the following existing BIFs:
+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 +
Erlang monotonic time as such is new as of
The introduction of Erlang monotonic time gives us - the possibility to adjust the two Erlang times (Erlang +
The introduction of Erlang monotonic time allows
+ us 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
+ doing this, the 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
-
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 + that would be a bad choice. As we can + express and measure time that is not connected to + calendar 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 + immediately. This as the Erlang applications + executing on the system can react on the change in + system time as soon as possible. This is also more or + less exactly how most operating systems handle this (OS monotonic time and OS system time). By adjusting - system time smoothly we would just hide the fact that + 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 +
To be able to react to a change in Erlang
+ system time, you must 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
-
{'CHANGE', MonitorReference, time_offset, clock_service, NewTimeOffset}
Besides reporting time
Besides reporting time,
Previously
- use
- use
+ Use
If you want the same format as returned by
- take timestamps with
- take timestamps with
+ Take timestamps with
Another easier way of doing this is to use + +
An easier way to do this is to use
- determine the order of events by saving a timestamp
- with
- determine the order of events by saving the integer
+ Determine the order of events by saving the integer
returned by
- determine the order of events by saving a timestamp
- with
- determine the order of events by saving a tuple
- containing
+ Determine the order of events by saving a tuple containing
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 + on current runtime system instance according to + creation time. 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 + +
If you are interested in Erlang system time at the
+ time when the event occurred, you can also save the time
offset before or after saving the events using
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 + can change, and you want 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).
- use the values returned from
- use the value returned from
+ Use the value returned from
- seed random number generation using
- seed random number generation using a combination of
+ Seed random number generation using a combination of
To sum this section up: Don't use
To sum up this section: Do not use
Your code may be required to be able to run on a variety
+
It can be required that your code must 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
+ cannot use the new API out of the box, as 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
+ is not to avoid using the new API, as your
+ code then would not benefit from the scalability
+ and accuracy improvements made. Instead, use the
new API when available, and fall back on
Fortunately most of the new API can easily be + implemented using existing primitives, except for:
+ +By wrapping the API with functions that fall back on
+