I believe PEP 418 (or at least the discussion) would benefit greatly
from a glossary to encourage people to use the same definitions. This
is arguably the Definitions section, but it should move either near
the end or (preferably) ahead of the Functions. It also needs to be
greatly expanded.
Here is my strawman proposal, which does use slightly different
definitions than the current PEP even for some terms that the PEP does
define:
Accuracy:
Is the answer correct? Any clock will eventually <drift>; if a
clock is intended to match <Civil Time>, it will need to be <adjusted>
back to the "true" time.
Adjusted:
Resetting a clock to the correct time. This may be done either
with a <Step> or by <Slewing>.
Civil Time:
Time of day; external to the system. 10:45:13am is a Civil time;
45 seconds is not. Provided by existing function time.localtime() and
time.gmtime(). Not changed by this PEP.
Clock:
An instrument for measuring time. Different clocks have different
characteristics; for example, a clock with <nanonsecond> <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.
Clock_Monotonic:
The characteristics expected of a monotonic clock in practice. In
addition to being <monotonic>, the <clock> should also be <steady> and
have relatively high <precision>, 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.
The original motivation for this PEP was to provide a cross-platform
name for requesting a clock_monotonic clock.
Counter:
A clock which increments each time a certain event occurs. A
counter is <strictly monotonic>, but not <clock_monotonic>. 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. time.clock() is
deprecated because it returns <real time> seconds on Windows, but CPU
seconds on unix, which prevents a consistent cross-platform
interpretation.
Duration:
Elapsed time. The difference between the starting and ending
times. A defined <epoch> creates an implicit (and usually large)
duration. More precision can generally be provided for a relatively
small <duration>.
Drift:
The accumulated error against "true" time, as defined externally
to the system.
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. For a <clock_monotonic> clock, the epoch may be
undefined (represented as None).
Latency:
Delay. By the time a clock call returns, the <real time> has
advanced, possibly by more than the precision of the clock.
Microsecond:
1/1,000,000 of a second. Fast enough for most -- but not all --
profiling uses.
Millisecond:
1/1,000 of a second. More than adequate for most end-to-end UI
measurements, but often too coarse for profiling individual functions.
Monotonic:
Moving in at most one direction; for clocks, that direction is
forward. A (nearly useless) clock that always returns exactly the
same time is technically monotonic. In practice, most uses of
"monotonic" with respect to clocks actually refer to a stronger set of
guarantees, as described under <clock_monotonic>
Nanosecond
1/1,000,000,000 of a second. The smallest unit of resolution --
and smaller than the actual precision -- available in current
mainstream operating systems.
Precision:
Significant Digits. What is the smallest duration that the clock
can distinguish? This differs from <resolution> in that a difference
greater than the minimum precision is actually meaningful.
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:
Represented Digits. Note that many clocks will have a resolution
greater than their actual <precision>.
Slew:
A temporary slight change to a clock's speed, usually intended to
correct <drift> with respect to an external authority.
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
<clock_monotonic> clock, but places greater emphasis on the
consistency of the duration between subsequent ticks.
Step:
An instantaneous change in the represented time. Instead of
speeding or slowing the clock (<slew>), a single offset is permanently
added.
Strictly Monotonic:
Monotonic, and not repeating any values. A strictly monotonic
clock is useful as a counter. Very few clocks promise this
explicitly, but <clock_monotonic> clocks typically have a precision
high enough (and are expensive enough to call) that the same value
will not be returned twice in practice.
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.
Tic, Tick:
The smallest increment of a clock. There may or may not be a
constant k such such that k*ticks == 1 second.
time.clock():
Existing function; deprecated because of platform inconsistencies.
On Windows, it measures <real time>, and on unix it measures <CPU
time>.
time.monotonic_clock():
Proposed addition to the time module, providing a <steady> or
<clock_monotonic> clock which measures in <real time> seconds with
high precision and stability.
time.time():
Existing function to provide <civil time>. Users should be
prepared for arbitrarily large steps or slew in either direction. Not
affected by this PEP.
Unit:
What a clock measures in. Other than counters, most clocks are
normalized to either <real time> seconds or <CPU time> seconds.
Wall Clock Time, Wallclock, Walltime:
What the clock on the wall says. This is typically used as a
synonym for <real time>; unfortunately, wall time is itself ambiguous.
(Does it mean the physical wall, external to the system? Does it
mean <civil time> and imply jumps for daylight savings time?)
-jJ
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
