[Python-Dev] (time) PEP 418 glossary V2

[Jim Jewett]

Glossary
========

Absolute Time
-------------

A measurement of time since a specific Epoch_, typically far in the
past.  Civil Time is the most common example.  Typically contrasted
with a `Duration`_, as (now - epoch) is generally much larger than
any duration that can be appropriately measured with the clock in
question.

Accuracy
--------

The amount of deviation of measurements by a given instrument from true
values. See also the wikipedia article on `Accuracy and precision
<http://en.wikipedia.org/wiki/Accuracy_and_precision>`_.

Inaccuracy in clocks may be caused by lack of `Precision`_, by
`Drift`_, or by an incorrect initial setting of the clock (e.g., timing
of threads is inherently inaccurate because perfect synchronization in
resetting counters is quite difficult).

Adjusted
--------

Resetting a clock, presumably to the correct time.  This may be done
either with a `Step`_ or with `Slew`_.  Adjusting a clock normally
makes it more accurate with respect to the `Absolute Time`_.  The cost
is that any durations currently being measured will show a `Bias`_.
(17 ticks is not the same Duration_ as 17 ticks plus an adjustment.)

Bias
----

Lack of accuracy that is systematically in one direction, as opposed to
random errors.  When a clock is `Adjusted`_, durations overlapping the
adjustment will show a Bias.

Civil Time
----------

Time of day; external to the system.  10:45:13am is a Civil time;
A Duration_ like "45 seconds" is not a Civil time.  Provided by
existing functions ``time.localtime()`` and ``time.gmtime()``, which
are not changed by this PEP.

Clock
-----

An instrument for measuring time.  Different clocks have different
characteristics; for example, a clock with nanosecond Precision_ may
start to Drift_ after a few minutes, while a less precise clock
remained accurate for days.

This PEP is primarily concerned with clocks which use a unit of
seconds, rather than years, or arbitrary units such as a Tick_.

Counter
-------

A clock which increments each time a certain event occurs.  A counter
is strictly monotonic in the mathematical sense, but does not meet
the typical definitions of Monotonic_ when used of a computer clock.
It can be used to generate a unique (and ordered) timestamp, but these
timestamps cannot be mapped to `Civil Time`_; Tick_ creation may well
be bursty, with several advances in the same millisecond followed
by several days without any advance.

CPU Time
--------

A measure of how much CPU effort has been spent on a certain task.
CPU seconds are often normalized (so that a variable number can
occur in the same actual second).  CPU seconds can be important
when profiling, but they do not map directly to user response time,
nor are they directly comparable to (real time) seconds.

Drift
-----

The accumulated error against "true" time, as defined externally to the
system.  Drift may be due to imprecision, or to a difference between
the average rate at which clock time advances and that of real time.

Drift does not include intentional adjustments, but clocks providing
`Absolute Time`_ will eventually have to be Adjusted_ to compensate
for drift.

Duration
--------

Elapsed time.  The difference between the starting and ending times.
Also called Relative Time.  Normally contrasted with `Absolute Time`_.

While a defined Epoch_ technically creates an implicit duration, this
duration is normally too large to be of practical use.

Computers can often supply a clock with better Precision_ or higher
Resolution_ if they do not have to guarantee meaningful comparisons to
any times not generated by the clock itself.

Epoch
-----

The reference point of a clock.  For clocks providing `Civil Time`_,
this is often midnight as the day (and year) rolled over to
January 1, 1970.  A Monotonic_ clock will typically have an undefined
epoch (represented as None).

Latency
-------

Delay.  By the time a call to a clock function returns, `Real Time`_
has advanced, possibly by more than the precision of the clock.

Monotonic
---------

This is a particularly tricky term, as there are several subtly
incompatible definitions in use.  C++ followed the mathematical
definition, so that a monotonic clock only promises not to go
backwards.  In practice, that is not sufficient to be useful, and no
Operating System provides such a weak guarantee.  Most discussions
of a "Monotonic *Clock*" will also assume several additional
guarantees, some of which are explicitly required by the POSIX
specification.

Within this PEP (and Python), the intended meaning is closer to
"the characteristics expected of a monotonic clock in practice".
In addition to not moving backward, a Monotonic Clock should also be
Steady_, and should be convertible to a unit of seconds.  The tradeoffs
often include lack of a defined Epoch_ or mapping to `Civil Time`_,
and being more expensive (in `Latency`_, power usage, or duration spent
within calls to the clock itself) to use.  For example, the clock may
represent (a constant multiplied by) ticks of a specific quartz timer
on a specific CPU core, and calls would therefore require
synchronization between cores.

Precision
---------

This is another tricky term, as there are several different meanings
which are relevant.

This PEP (and python) uses the most common meaning from natural
sciences:  "The amount of deviation among measurements of the same
physical value by a single instrument."  Imprecision in clocks may be
caused by a fluctuation of the rate at which clock time advances
relative to `Real Time`_, including intentional clock adjustments
by slewing.

Note that this is different from the typical computer language meaning
of how many digits to show (perhaps better called resolution).

Note that this is also different from at least one time-related meaning
of precision used in at least some sources.  That usage assumes that a
clock is an oscillator with a given frequency, and measures the
precision with which that oscillator tracks its target frequency,
irrespective of how precisely the computer can read the resulting time.

Note that "precision" as reported by the clock itself may use yet
another definition, and may differ between clocks.

Process Time
------------

Time elapsed since the process began.  It is typically measured in
`CPU time`_ rather than `Real Time`_, and typically does not advance
while the process is suspended.

Real Time
---------

Time in the real world.  This differs from `Civil time`_ in that it is
not `Adjusted`_, but they should otherwise advance in lockstep.

It is not related to the "real time" of "Real Time [Operating]
Systems".  It is sometimes called "wall clock time" to avoid that
ambiguity; unfortunately, that introduces different ambiguities.

Resolution
----------

The smallest difference between two physical values that results
in a different measurement by a given instrument.

Note that the above is in the ideal case; computer clocks in particular
are often prone to reporting more resolution than they can actually
distinguish.

Slew
----

A slight change to a clock's speed, usually intended to correct Drift_
with respect to an external authority.  In other words, the Precision_
is (temporarily) intentionally reduced by some `Bias`_, and short
Duration_ measurements become less comparable, in return for providing
a more accurate `Absolute Time`_.

Stability
---------

Persistence of accuracy.  A measure of expected `Drift`_.

Steady
------

A clock with high Stability_ and relatively high Accuracy_ and
`Precision`_.  In practice, it is often used to indicate a Monotonic_
clock.  In theory, "steady" places greater emphasis on the consistency
of the duration between subsequent ticks; in practice it may simply
indicate more familiarity with C++ than with Posix.

Step
----

An instantaneous change in the represented time.  Instead of speeding
or slowing the clock (`Slew`_), a single offset is permanently added.

System Time
-----------

Time as represented by the Operating System.

Thread Time
-----------

Time elapsed since the thread began.  It is typically measured in
`CPU time`_ rather than `Real Time`_, and typically does not advance
while the thread is idle.

Tick
----

A single increment of a `Counter`_.  Generally used to indicate what
the raw hardware provides, before multiplying by a constant to get
seconds.

Wallclock
---------

Also Wall Clock, Wall Time.  What the clock on the wall says.  This is
typically used as a synonym for `Real Time`_; unfortunately, wall time
is itself ambiguous, particularly (but not only) between Real Time and
`Civil Time`_.