[Python-Dev] PEP 418 glossary

Stephen J. Turnbull stephen at xemacs.org
Wed Apr 11 11:30:47 CEST 2012

A few comments, YMMV.

On Wed, Apr 11, 2012 at 3:49 PM, Jim Jewett <jimjjewett at gmail.com> wrote:

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

Accuracy is not a Boolean.  Accuracy is the lack of difference from
some standard.

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

Whose practice?  In C++, "monotonic" was defined as "mathematically
monotonic", and rather than talk about "what's expected of a monotonic
clock in practice," they chose to use a different term ("steady") for
the clocks that (come closer to) DTRT.

I think it would be best to use a different name.

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

Epoch is independent of duration.  Rather, epoch can be combined with
duration to provide a clock that measures <civil time>.

> 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>

Again, even in a glossary you need to be vague about 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.

I think you have this backwards.  Precision is the number of
significant digits reported.  Resolution is the smallest duration that
is 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.

I don't see that anything needs to be temporary about it.  Also, the
gloss should say something about making the correction smoothly, and
refer to "<Step>".

Something like: A slight change to a clock's speed to smoothly correct
drift.  Contrast with <Step>.

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

Does anybody who matters actually spell this "tic"?  "Tic" is a
perfectly good English word that means a twitch or other unconscious,
instantaneous behavior.  I think this is sufficiently ambiguous (a
clock with a tic presumably is one that is unreliable!) that the
spelling should be deprecated in documentation (people can spell
program identifiers however they like, of course).

> 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?)

More information about the Python-Dev mailing list