As from Erlang/OTP 18 (ERTS 7.0) the time functionality
has been extended. This includes a
The
By using the new API, you
automatically get scalability and performance improvements. This
also enables you to use the
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 predecessor.
In a strictly monotonically increasing sequence of values, all values that have a predecessor are larger than its predecessor.
Universal Time. UT1 is based on the rotation of the earth and conceptually means solar time at 0° longitude.
Coordinated Universal Time. UTC almost aligns with
Time since
The shortest time interval that can be distinguished when reading time values.
The shortest time interval that can be distinguished
repeatedly and reliably when reading time values. Precision
is limited by the
The correctness of time values.
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 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 OS.
This time does not leap and has a relatively steady
frequency although not completely correct. However, it is not
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. Erlang monotonic time increases since
some unspecified point in time. To retrieve it, call
The
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,
regardless of it is a
To retrieve the 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 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.
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. 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 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
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 off by a minute. Then they set it to the correct time, but most probably not in a smooth way.
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 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 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
makes use of both
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
To enable or disable time correction, pass command-line argument
If time correction is disabled, Erlang monotonic time can 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 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 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 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
behaved until ERTS 7.0.
Ensure that your Erlang code that can execute during a time
warp is
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 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, 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 backward compatibility mode as from its introduction.
On an embedded system it is not uncommon that the system
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 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 use time warp safe code only, it is much better
to use the
Using the single time warp mode, the time offset is handled in two phases:
This phase starts when the runtime system starts. A preliminary time offset based on 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 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 affects the monotonic clock the same way as
when the
This phase begins when the user finalizes the time
offset by calling
During finalization, the time offset is adjusted and
fixed so that current Erlang system time aligns with the
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 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
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 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 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.
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 these requirements are fulfilled, time correction is enabled, and 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.
To use this mode, ensure that
all Erlang code that will execute in both phases is
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 as the Erlang runtime system have better performance, scale better, and behave better on almost all platforms. Also, the accuracy and precision of time measurements are better. Only Erlang runtime systems executing on ancient platforms benefit from another configuration.
The time offset can change at any time without limitations. That is, Erlang system time can perform time warps both 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 makes time measurements using Erlang monotonic time more accurate and precise.
If time correction is disabled, Erlang monotonic time 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.
To use this mode, ensure that all
Erlang code that will execute on the runtime system is
The old time API is based on
To be backward compatible,
Some of the new BIFs on some systems, perhaps surprisingly, 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 also consists of extensions of the following existing BIFs:
Erlang monotonic time as such is new as from ERTS 7.0. It is introduced to detach time measurements, such as elapsed time from calendar time. In many use cases there is a need to measure elapsed time or specify a time relative to another point in time without the need to know the involved times in UTC or any other globally defined time scale. By introducing a time scale with a local definition of where it starts, time that do not concern calendar time can be managed on that time scale. Erlang monotonic time uses such a time scale with a locally defined start.
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, 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. 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 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 changed and make it harder for the Erlang applications to react to the change in a sensible way.
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 the
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,
Previously
Use
Use
If you want the same format as returned by
Take time stamps with
Take time stamps with
An easier way to do this is to use
Determine the order of events by saving a time stamp
with
Determine the order of events by saving the integer
returned by
Determine the order of events by saving a time stamp
with
Determine the order of events by saving a tuple containing
Time = erlang:monotonic_time(),
UMI = erlang:unique_integer([monotonic]),
EventTag = {Time, UMI}
These tuples are strictly monotonically ordered on the 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 two-tuples). Using the monotonic time in the tuples, you can calculate time between events.
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 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 three-tuples).
Use the values returned from
Use the value returned from
Seed random number generation using
Seed random number generation using a combination of
To sum up this section: Do not use
It can be required that your code must run on a variety
of OTP installations of different OTP releases. If so, you
cannot use the new API out of the box, as it will
not be available on releases before OTP 18. The solution
is not to avoid using the new API, as your
code would then 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