path: root/erts/doc/src/time_correction.xml

<?xml version="1.0" encoding="utf8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>1999</year><year>2013</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      The contents of this file are subject to the Erlang Public License,
      Version 1.1, (the "License"); you may not use this file except in
      compliance with the License. You should have received a copy of the
      Erlang Public License along with this software. If not, it can be
      retrieved online at http://www.erlang.org/.

      Software distributed under the License is distributed on an "AS IS"
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
      the License for the specific language governing rights and limitations
      under the License.

    </legalnotice>

    <title>Time and time correction in Erlang</title>
    <prepared>Patrik Nyblom</prepared>
    <responsible></responsible>
    <docno></docno>
    <approved></approved>
    <checked></checked>
    <date>2013-08-28</date>
    <rev>PA1</rev>
    <file>time_correction.xml</file>
  </header>
  <p>Time is vital to an Erlang program and, more importantly, <em>correct</em>
  time is vital to an Erlang program. As Erlang is a language with
  soft real time properties and we have the possibility to express
  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
  how time functions behave.</p>

  <p>In the beginning, Erlang was constructed assuming 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
  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.</p>

  <p>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
  less potent time-keeper than an atomic clock is used.</p>

  <p>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
  about the time.</p>

  <p>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.</p>

  <p>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
  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 may have
  microsecond resolution or much less, but generally it has a drift
  that is not to be ignored.</p>

  <p>So we have this monotonic ticking and we have the wall clock
  time. Two unreliable times that together can give us an estimate of
  an actual wall clock time that does not jump around and that
  monotonically moves forward. If the tick counter has a high
  resolution, this is fairly easy to do, if the counter has a low
  resolution, it's more expensive, but still doable down to
  frequencies of 50-60 Hz (of the tick counter).</p>

  <p>So the corrected time is the nearest approximation of an atomic
  clock that is available on the computer. We want it to have the
  following properties:</p>
  <taglist>
    <tag>Monotonic</tag>
    <item>The clock should not move backwards</item>
    <tag>Intervals should be near the truth</tag>
    <item>We want the actual time (as measured by an atomic clock or
    an astronomer) that passes between two time stamps, T1 and T2, to be as
    near to T2 - T1 as possible.</item>
    <tag>Tight coupling to the wall clock</tag>
    <item>We want a timer that is to be fired when the wall clock
    reaches a time in the future, to fire as near to that point in
    time as possible</item>
  </taglist>
  <p>To meet all the criteria, we have to utilize both times in such a
  way that Erlangs "corrected time" moves slightly slower or slightly
  faster than the wall clock to get in sync with it. The word
  "slightly" means a maximum of 1% difference to the wall clock time,
  meaning that a sudden change in the wall clock of one minute, takes
  100 minutes to fix, by letting all "corrected time" move 1% slower
  or faster.</p>

  <p>Needless to say, correcting for a faulty handling of daylight
  saving time may be disturbing to a user comparing wall clock
  time to for example calendar:now_to_local_time(erlang:now()). But
  calendar:now_to_local_time/1 is not supposed to be used for presenting wall
  clock time to the user.</p>

  <p>Time correction is not perfect, but it saves you from the havoc
  of clocks jumping around, which would make timers in your program
  fire far to late or far to early and could bring your whole system
  to it's knees (or worse) just because someone detected a small error
  in the wall clock time of the server where your program runs. So
  while it might be confusing, it is still a really good feature of
  Erlang and you should not throw it away using time functions which
  may give you higher benchmark results, not unless you really know
  what you're doing.</p>

  <section>
    <title>What does time correction mean in my system?</title>
    <p>Time correction means that Erlang estimates a time from current
    and previous settings of the wall clock, and it uses a fairly
    exact tick counter to detect when the wall clock time has jumped
    for some reason, slowly adjusting to the new value.</p>

    <p>In practice, this means that the difference between two calls
    to time corrected functions, like erlang:now(), might differ up to
    one percent from the corresponding calls to non time corrected
    functions (like os:timestamp()). Furthermore, if comparing
    calendar:local_time/0 to calendar:now_to_local_time(erlang:now()),
    you might temporarily see a difference, depending on how well kept your
    system is.</p>

    <p>It is important to understand that it is (to the program)
    always unknown if it is the wall clock time that moves in the
    wrong pace or the Erlang corrected time. The only way to determine
    that, is to have an external source of universally correct time. If
    some such source is available, the wall clock time can be kept
    nearly perfect at all times, and no significant difference will be
    detected between erlang:now/0's pace and the wall clock's.</p>

    <p>Still, the time correction will mean that your system keeps
    it's real time characteristics very well, even when the wall clock
    is unreliable.</p>
  </section>
  <section>
    <title>Where does Erlang use corrected time?</title>
    <p>For all functionality where real time characteristics are
    desirable, time correction is used. This basically means:</p>
    <taglist>
      <tag>erlang:now/0</tag>
      <item>The infamous erlang:now/0 function uses time correction so
      that differences between two "now-timestamps" will correspond to
      other timeouts in the system. erlang:now/0 also holds other
      properties, discussed later.</item>
      <tag>receive ... after</tag>
      <item>Timeouts on receive uses time correction to determine a
      stable timeout interval.</item>
      <tag>The timer module</tag>
      <item>As the timer module uses other built in functions which
      deliver corrected time, the timer module itself works with
      corrected time.</item>
      <tag>erlang:start_timer/3 and erlang:send_after/3</tag>
      <item>The timer BIF's work with corrected time, so that they
      will not fire prematurely or too late due to changes in the wall
      clock time.</item>
    </taglist>

    <p>All other functionality in the system where erlang:now/0 or any
    other time corrected functionality is used, will of course
    automatically benefit from it, as long as it's not "optimized" to
    use some other time stamp function (like os:timestamp/0).</p>

    <p>Modules like calendar and functions like erlang:localtime/0 use
    the wall clock time as it is currently set on the system. They
    will not use corrected time. However, if you use a now-value and
    convert it to local time, you will get a corrected local time
    value, which may or may not be what you want. Typically older code
    tend to use erlang:now/0 as a wall clock time, which is usually
    correct (at least when testing), but might surprise you when
    compared to other times in the system.</p>
  </section>
  <section>
    <title>What is erlang:now/0 really?</title>
    <p>erlang:now/0 is a function designed to serve multiple purposes
    (or a multi-headed beast if you're a VM designer). It is expected
    to hold the following properties:</p>
    <taglist>
      <tag>Monotonic</tag>
      <item>erlang:now() never jumps backwards - it always moves
      forward</item>
      <tag>Interval correct</tag>
      <item>The interval between two erlang:now() calls is expected to
      correspond to the correct time in real life (as defined by an
      atomic clock, or better)</item>
      <tag>Absolute correctness</tag>
      <item>The erlang:now/0 value should be possible to convert to an
      absolute and correct date-time, corresponding to the real world
      date and time (the wall clock)</item>
      <tag>System correspondence</tag>
      <item>The erlang:now/0 value converted to a date-time is
      expected to correspond to times given by other programs on the
      system (or by functions like os:timestamp/0)</item>
      <tag>Unique</tag>
      <item>No two calls to erlang:now on one Erlang node should
      return the same value</item>
    </taglist>
    <p>All these requirements are possible to uphold at the same
    time if (and only if):</p>
    <taglist>
      <tag>The wall clock time of the system is perfect</tag>
      <item>The system (Operating System) time needs to be perfectly
      in sync with the actual time as defined by an atomic clock or
      a better time source. A good installation using NTP, and that is
      up to date before Erlang starts, will have properties that for
      most users and programs will be near indistinguishable from the
      perfect time. Note that any larger corrections to the time done
      by hand, or after Erlang has started, will partly (or
      temporarily) invalidate some of the properties, as the time is
      no longer perfect.</item>
      <tag>Less than one call per microsecond to erlang:now/0 is
      done</tag>
      <item>This means that at <em>any</em> microsecond interval in
      time, there can be no more than one call to erlang:now/0 in the
      system. However, for the system not to loose it's properties
      completely, it's enough that it on average is no more than one
      call per microsecond (in one Erlang node).</item>
    </taglist>
    <p>The uniqueness property of erlang:now/0 is the most limiting
    property. It means that erlang:now() maintains a global state and
    that there is a hard-to-check property of the system that needs to
    be maintained. For most applications this is still not a problem,
    but a future system might very well manage to violate the
    frequency limit on the calls globally. The uniqueness property is
    also quite useless, as there are globally unique references that
    provide a much better unique value to programs. However the
    property will need to be maintained unless a really subtle
    backward compatibility issue is to be introduced.</p>
  </section>
  <section>
    <title>Should I use erlang:now/0 or os:timestamp/0</title>
    <p>The simple answer is to use erlang:now/0 for everything where
    you want to keep real time characteristics, but use os:timestamp
    for things like logs, user communication and debugging (typically
    timer:ts uses os:timestamp, as it is a test tool, not a real world
    application API). The benefit of using os:timestamp/0 is that it's
    faster and does not involve any global state (unless the operating
    system has one). The downside is that it will be vulnerable to wall
    clock time changes.</p>
  </section>
  <section>
    <title>Turning off time correction</title>
    <p>If, for some reason, time correction causes trouble and you are
    absolutely confident that the wall clock on the system is nearly
    perfect, you can turn off time correction completely by giving the
    <c>+c</c> option to <c>erl</c>. The probability for this being a
    good idea, is very low.</p>
  </section>
</chapter>