PEP 418: Integrate Jim Jewett's Glossary

pep-0418.txt

@@ -2,7 +2,7 @@ PEP: 418
 Title: Add a monotonic time functions
 Version: $Revision$
 Last-Modified: $Date$
-Author: Victor Stinner <victor.stinner@gmail.com>
+Author: Jim Jewett <jimjjewett@gmail.com>, Victor Stinner <victor.stinner@gmail.com>
 Status: Draft
 Type: Standards Track
 Content-Type: text/x-rst
@@ -247,8 +247,123 @@ Return a dictionary with the following keys:
      daemon)
 
 
-Definitions
-===========
+Glossary
+========
+
+: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.
+
+: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.
+
+: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.
+
+:Monotonic:
+   The characteristics expected of a monotonic clock in practice.  Moving in at
+   most one direction; for clocks, that direction is forward. The <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:
+   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 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.
+
+: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.
+
+:Wallclock:
+   What the clock on the wall says.  This is typically used as a synonym for
+   <real time>; unfortunately, wall time is itself ambiguous.
+
 
 Resolution
 ----------