[Python-checkins] peps: PEP 418: editing.
georg.brandl
python-checkins at python.org
Thu Apr 12 19:12:31 CEST 2012
http://hg.python.org/peps/rev/6a28c78fef65
changeset: 4233:6a28c78fef65
user: Georg Brandl <georg at python.org>
date: Thu Apr 12 19:12:48 2012 +0200
summary:
PEP 418: editing.
files:
pep-0418.txt | 704 ++++++++++++++++++++------------------
1 files changed, 367 insertions(+), 337 deletions(-)
diff --git a/pep-0418.txt b/pep-0418.txt
--- a/pep-0418.txt
+++ b/pep-0418.txt
@@ -13,50 +13,54 @@
Abstract
========
-Add time.get_clock_info(name), time.monotonic(), time.perf_counter() and
-time.process_time() functions to Python 3.3.
+This PEP proposes to add ``time.get_clock_info(name)``,
+``time.monotonic()``, ``time.perf_counter()`` and
+``time.process_time()`` functions to Python 3.3.
Rationale
=========
-If a program uses the system clock to schedule events or to implement a
-timeout, it will not run events at the right moment or stop the timeout too
-early or too late when the system clock is set manually or adjusted
-automatically by NTP. A monotonic clock should be used instead to not be
-affected by system clock updates.
+If a program uses the system clock to schedule events or to implement
+a timeout, it will not run events at the right moment or stop the
+timeout too early or too late when the system clock is set manually or
+adjusted automatically by NTP. A monotonic clock should be used
+instead to not be affected by system clock updates.
-To measure the performance of a function, time.clock() can be used but it
-is very different on Windows and on Unix. On Windows, time.clock() includes
-time elapsed during sleep, whereas it does not on Unix. time.clock() precision
-is very good on Windows, but very bad on Unix. A new time.perf_counter() should
-be used instead to always get the most precise performance counter with a
+To measure the performance of a function, ``time.clock()`` can be used
+but it is very different on Windows and on Unix. On Windows,
+``time.clock()`` includes time elapsed during sleep, whereas it does
+not on Unix. ``time.clock()`` precision is very good on Windows, but
+very bad on Unix. The new ``time.perf_counter()`` function can be
+used instead to always get the most precise performance counter with a
portable behaviour.
-To measure CPU time, Python does not provide directly a portable function.
-time.clock() can be used on Unix, but it has a bad precision.
-resource.getrusage() can also be used on Unix, but it requires to get fields of
-a structure and compute the sum of time spend in kernel space and user space.
-A new time.process_time() function is portable counter, always measure CPU time
-(don't include time elapsed during sleep), and has the best available
+To measure CPU time, Python does not provide directly a portable
+function. ``time.clock()`` can be used on Unix, but it has a bad
+precision. ``resource.getrusage()`` can also be used on Unix, but it
+requires to get fields of a structure and compute the sum of time
+spent in kernel space and user space. The new ``time.process_time()``
+function acts as a portable counter that always measures CPU time
+(doesn't include time elapsed during sleep) and has the best available
precision.
-Each operating system implements clocks and performance counters differently,
-and it is useful to know exactly which function is used and some properties of
-the clock like its resolution and its precision. A new time.get_clock_info()
-function gives access to all available information of each Python time
-function.
+Each operating system implements clocks and performance counters
+differently, and it is useful to know exactly which function is used
+and some properties of the clock like its resolution and its
+precision. The new ``time.get_clock_info()`` function gives access to
+all available information of each Python time function.
New functions:
- * time.monotonic(): timeout and scheduling, not affected by system clock
- updates
- * time.perf_counter(): benchmarking, most precise clock for short period
- * time.process_time(): profiling, CPU time of the process
+* ``time.monotonic()``: timeout and scheduling, not affected by system
+ clock updates
+* ``time.perf_counter()``: benchmarking, most precise clock for short
+ period
+* ``time.process_time()``: profiling, CPU time of the process
-time.clock() is deprecated by this PEP because it is not portable:
-time.perf_counter() or time.process_time() should be used instead, depending
-on your requirements.
+``time.clock()`` is deprecated by this PEP because it is not portable:
+``time.perf_counter()`` or ``time.process_time()`` should be used
+instead, depending on your requirements.
Python functions
@@ -68,36 +72,38 @@
time.get_clock_info(name)
^^^^^^^^^^^^^^^^^^^^^^^^^
-Get information on the specified clock. Supported clocks:
+Get information on the specified clock. Supported clocks:
- * "clock": time.clock()
- * "monotonic": time.monotonic()
- * "perf_counter": time.perf_counter()
- * "process_time": time.process_time()
- * "time": time.time()
+* "clock": time.clock()
+* "monotonic": time.monotonic()
+* "perf_counter": time.perf_counter()
+* "process_time": time.process_time()
+* "time": time.time()
Return a dictionary with the following keys:
- * Mandatory keys:
+* Mandatory keys:
- * "function" (str): name of the underlying operating system function.
- Examples: "QueryPerformanceCounter()", "clock_gettime(CLOCK_REALTIME)".
- * "resolution" (float): resolution in seconds of the clock
- * "is_monotonic" (bool): True if the clock cannot go backward
+ * "function" (str): name of the underlying operating system
+ function. Examples: "QueryPerformanceCounter()",
+ "clock_gettime(CLOCK_REALTIME)".
+ * "resolution" (float): resolution in seconds of the clock
+ * "is_monotonic" (bool): True if the clock cannot go backward
- * Optional keys:
+* Optional keys:
- * "precision" (float): precision in seconds of the clock
- * "is_adjusted" (bool): True if the clock can be adjusted (e.g. by a NTP
- daemon)
+ * "precision" (float): precision in seconds of the clock
+ * "is_adjusted" (bool): True if the clock can be adjusted (e.g. by a
+ NTP daemon)
time.monotonic()
^^^^^^^^^^^^^^^^
-Monotonic clock, cannot go backward. It is not affected by system clock
-updates. The reference point of the returned value is undefined so only the
-difference between consecutive calls is valid.
+Monotonic clock, cannot go backward. It is not affected by system
+clock updates. The reference point of the returned value is
+undefined, so that only the difference between the results of
+consecutive calls is valid.
Availability: Windows, Mac OS X, Unix.
@@ -139,25 +145,28 @@
and hasattr(time, 'CLOCK_HIGHRES'))
-On Windows, QueryPerformanceCounter() is not used even though it has a better
-precision than GetTickCount(). It is not reliable and has too many issues.
+On Windows, ``QueryPerformanceCounter()`` is not used even though it
+has a better precision than ``GetTickCount()``. It is not reliable
+and has too many issues.
.. note::
- time.monotonic() detects GetTickCount() integer overflow (32 bits, roll-over
- after 49.7 days): it increases a delta by 2\ :sup:`32` each time than an
- overflow is detected. The delta is stored in the process-local state and so
- the value of time.monotonic() may be different in two Python processes
+ ``time.monotonic()`` detects ``GetTickCount()`` integer overflow
+ (32 bits, roll-over after 49.7 days): it increases a delta by 2\
+ :sup:`32` each time than an overflow is detected. The delta is
+ stored in the process-local state and so the value of
+ ``time.monotonic()`` may be different in two Python processes
running for more than 49 days.
time.perf_counter()
^^^^^^^^^^^^^^^^^^^
-Performance counter used for benchmarking. It is monotonic, cannot go backward.
-It does include time elapsed during sleep. The reference point of the returned
-value is undefined so only the difference between consecutive calls is valid
-and is number of seconds.
+Performance counter used for benchmarking. It is monotonic,
+i.e. cannot go backward. It does include time elapsed during sleep.
+The reference point of the returned value is undefined, so that only
+the difference between the results of consecutive calls is valid and
+is number of seconds.
Pseudo-code::
@@ -192,9 +201,9 @@
^^^^^^^^^^^^^^^^^^^
Process time used for profiling: some of kernel and user-space CPU
-time. It does not include time elapsed during sleep. The reference point of
-the returned value is undefined so only the difference between consecutive
-calls is valid.
+time. It does not include time elapsed during sleep. The reference
+point of the returned value is undefined, so that only the difference
+between the results of consecutive calls is valid.
Pseudo-code::
@@ -225,7 +234,7 @@
time.time()
^^^^^^^^^^^
-The system time is the "wall clock". It can be set manually by the
+The system time is the "wall clock". It can be set manually by the
system administrator or automatically by a NTP daemon. It can jump
backward and forward. It is not monotonic.
@@ -263,11 +272,12 @@
time.sleep()
^^^^^^^^^^^^
-Suspend execution for the given number of seconds. The actual suspension time
-may be less than that requested because any caught signal will terminate the
-time.sleep() following execution of that signal's catching routine. Also, the
-suspension time may be longer than requested by an arbitrary amount because of
-the scheduling of other activity in the system.
+Suspend execution for the given number of seconds. The actual
+suspension time may be less than that requested because any caught
+signal will terminate the ``time.sleep()`` following execution of that
+signal's catching routine. Also, the suspension time may be longer
+than requested by an arbitrary amount because of the scheduling of
+other activity in the system.
Pseudo-code [#pseudo]_::
@@ -312,15 +322,16 @@
time.clock()
^^^^^^^^^^^^
-On Unix, return the current processor time as a floating point number expressed
-in seconds. The precision, and in fact the very definition of the meaning of
-"processor time", depends on that of the C function of the same name, but in any
-case, this is the function to use for benchmarking Python or timing algorithms.
+On Unix, return the current processor time as a floating point number
+expressed in seconds. The precision, and in fact the very definition
+of the meaning of "processor time", depends on that of the C function
+of the same name, but in any case, this is the function to use for
+benchmarking Python or timing algorithms.
-On Windows, this function returns wall-clock seconds elapsed since the first
-call to this function, as a floating point number, based on the Win32 function
-``QueryPerformanceCounter()``. The resolution is typically better than one
-microsecond.
+On Windows, this function returns wall-clock seconds elapsed since the
+first call to this function, as a floating point number, based on the
+Win32 function ``QueryPerformanceCounter()``. The resolution is
+typically better than one microsecond.
Pseudo-code [#pseudo]_::
@@ -351,118 +362,126 @@
========
: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.
+ 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>.
+ 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.
+ 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.
+ 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.
+ 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.
+ 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>.
+ 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.
+ 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).
+ 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.
+ 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.
+ 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.
+ 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.
+ 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.
+ 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>.
+ 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.
+ 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.
+ <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.
+ 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.
+ 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.
+ What the clock on the wall says. This is typically used as a
+ synonym for <real time>; unfortunately, wall time is itself
+ ambiguous.
Hardware clocks
@@ -471,25 +490,28 @@
List of hardware clocks
-----------------------
-* HPET: An High Precision Event Timer (HPET) chip consists of a 64-bit up-counter (main counter)
- counting at least at 10 MHz and a set of up to 256 comparators (at
- least 3). Each HPET can have up to 32 timers. HPET can cause around 3 seconds of drift per day.
-* TSC (Time Stamp Counter): Historically, the TSC increased with every internal
- processor clock cycle, but now the rate is usually constant (even if the
- processor changes frequency) and usually equals the maximum processor
- frequency. Multiple cores having different TSC values. Hibernation of system
- will reset TSC value. The RDTSC instruction can be used to read this counter.
- CPU frequency scaling for power saving.
-* ACPI Power Management Timer: ACPI 24-bit timer with a frequency
- of 3.5 MHz (3,579,545 Hz).
+* HPET: An High Precision Event Timer (HPET) chip consists of a 64-bit
+ up-counter (main counter) counting at least at 10 MHz and a set of
+ up to 256 comparators (at least 3). Each HPET can have up to 32
+ timers. HPET can cause around 3 seconds of drift per day.
+* TSC (Time Stamp Counter): Historically, the TSC increased with every
+ internal processor clock cycle, but now the rate is usually constant
+ (even if the processor changes frequency) and usually equals the
+ maximum processor frequency. Multiple cores having different TSC
+ values. Hibernation of system will reset TSC value. The RDTSC
+ instruction can be used to read this counter. CPU frequency scaling
+ for power saving.
+* ACPI Power Management Timer: ACPI 24-bit timer with a frequency of
+ 3.5 MHz (3,579,545 Hz).
* Cyclone: The Cyclone timer uses a 32-bit counter on IBM Extended
X-Architecture (EXA) chipsets which include computers that use the
IBM "Summit" series chipsets (ex: x440). This is available in IA32
and IA64 architectures.
* PIT (programmable interrupt timer): Intel 8253/8254 chipsets with a
- configurable frequency in range 18.2 Hz - 1.2 MHz. It is a 16-bit counter.
-* RTC (Real-time clock). Most RTCs use a crystal oscillator with a frequency of
- 32,768 Hz
+ configurable frequency in range 18.2 Hz - 1.2 MHz. It is a 16-bit
+ counter.
+* RTC (Real-time clock). Most RTCs use a crystal oscillator with a
+ frequency of 32,768 Hz
Linux clocksource
@@ -516,14 +538,15 @@
architectures. They are at least provided on x86/x86_64, ARM and
PowerPC.
-The /sys/devices/system/clocksource/clocksource0 directory contains two useful files:
+The ``/sys/devices/system/clocksource/clocksource0`` directory
+contains two useful files:
- * available_clocksource: list of available clock sources
- * current_clocksource: clock source currently used. It is possible to change
- the current clocksource by writing the name of a clocksource into this
- file.
+* ``available_clocksource``: list of available clock sources
+* ``current_clocksource``: clock source currently used. It is
+ possible to change the current clocksource by writing the name of a
+ clocksource into this file.
-/proc/timer_list contains the list of all hardware timers.
+``/proc/timer_list`` contains the list of all hardware timers.
Read also the `time(7) manual page
<http://www.kernel.org/doc/man-pages/online/pages/man7/time.7.html>`_:
@@ -533,10 +556,11 @@
FreeBSD timecounter
-------------------
-kern.timecounter.choice list available hardward clocks with their priority.
-The sysctl program can be used to change the timecounter. Example::
+kern.timecounter.choice list available hardware clocks with their
+priority. The sysctl program can be used to change the timecounter.
+Example::
- # dmesg|grep Timecounter
+ # dmesg | grep Timecounter
Timecounter "i8254" frequency 1193182 Hz quality 0
Timecounter "ACPI-safe" frequency 3579545 Hz quality 850
Timecounter "HPET" frequency 100000000 Hz quality 900
@@ -549,29 +573,29 @@
Available clocks:
- * "TSC": Time Stamp Counter of the procesor
- * "HPET": High Precision Event Timer
- * "ACPI-fast": ACPI Power Management timer (fast mode)
- * "ACPI-safe": ACPI Power Management timer (safe mode)
- * "i8254": PIT with Intel 8254 chipset
+* "TSC": Time Stamp Counter of the processor
+* "HPET": High Precision Event Timer
+* "ACPI-fast": ACPI Power Management timer (fast mode)
+* "ACPI-safe": ACPI Power Management timer (safe mode)
+* "i8254": PIT with Intel 8254 chipset
The `commit 222222
-<http://svnweb.freebsd.org/base?view=revision&revision=222222>`_ (May 2011)
-decreased ACPI-fast timecounter quality to 900 and increased HPET timecounter
-quality to 950: "HPET on modern platforms usually have better resolution and
-lower latency than ACPI timer".
+<http://svnweb.freebsd.org/base?view=revision&revision=222222>`_ (May
+2011) decreased ACPI-fast timecounter quality to 900 and increased
+HPET timecounter quality to 950: "HPET on modern platforms usually
+have better resolution and lower latency than ACPI timer".
Read `Timecounters: Efficient and precise timekeeping in SMP kernels
-<http://phk.freebsd.dk/pubs/timecounter.pdf>`_ by Poul-Henning Kamp (2002) for
-the FreeBSD Project.
+<http://phk.freebsd.dk/pubs/timecounter.pdf>`_ by Poul-Henning Kamp
+(2002) for the FreeBSD Project.
-Performances
-------------
+Performance
+-----------
-Reading an hardware clock has a cost. The following table compares the
-performance of different hardware clocks on Linux 3.3 with Intel Core i7-2600
-at 3.40GHz (8 cores).
+Reading an hardware clock has a cost. The following table compares
+the performance of different hardware clocks on Linux 3.3 with Intel
+Core i7-2600 at 3.40GHz (8 cores).
======================== ====== ======= ======
Function TSC ACPI PM HPET
@@ -588,9 +612,9 @@
CLOCK_MONOTONIC 27 ns 723 ns 635 ns
======================== ====== ======= ======
-Each function was called 10,000,000 times and CLOCK_MONOTONIC was used to get
-the time before and after. The benchmark was run 5 times to keep the minimum
-time.
+Each function was called 10,000,000 times and CLOCK_MONOTONIC was used
+to get the time before and after. The benchmark was run 5 times to
+keep the minimum time.
FreeBSD 8.0 in kvm with hardware virtualization:
@@ -615,33 +639,34 @@
CLOCK_MONOTONIC 201 ns 10766 ns 4498 ns 3943 ns
======================== ====== ========= ======= =======
-Each function was called 100,000 times and CLOCK_MONOTONIC was used to get
-the time before and after. The benchmark was run 5 times to keep the minimum
-time.
-
+Each function was called 100,000 times and CLOCK_MONOTONIC was used to
+get the time before and after. The benchmark was run 5 times to keep
+the minimum time.
NTP adjustment
==============
-NTP has diffent methods to adjust a clock:
+NTP has different methods to adjust a clock:
- * "slewing": change the clock frequency to be slightly faster or slower
- (which is done with adjtime()). Since the slew rate is limited to 0.5 ms/s,
- each second of adjustment requires an amortization interval of 2000 s. Thus,
- an adjustment of many seconds can take hours or days to amortize.
- * "stepping": jump by a large amount in a single discrete step (which is done
- with settimeofday())
+* "slewing": change the clock frequency to be slightly faster or
+ slower (which is done with ``adjtime()``). Since the slew rate is
+ limited to 0.5 ms/s, each second of adjustment requires an
+ amortization interval of 2000 s. Thus, an adjustment of many
+ seconds can take hours or days to amortize.
+* "stepping": jump by a large amount in a single discrete step (which
+ is done with ``settimeofday()``)
-By default, the time is slewed if the offset is less than 128 ms, or stepped
-otherwise.
+By default, the time is slewed if the offset is less than 128 ms, or
+stepped otherwise.
-Slewing is generally desirable (i.e. we should use CLOCK_MONOTONIC, not
-CLOCK_MONOTONIC_RAW) if one wishes to measure "real" time (and not a time-like
-object like CPU cycles). This is because the clock on the other end of the NTP
-connection from you is probably better at keeping time: hopefully that thirty
-five thousand dollars of Cesium timekeeping goodness is doing something better
-than your PC's $3 quartz crystal, after all.
+Slewing is generally desirable (i.e. we should use CLOCK_MONOTONIC,
+not CLOCK_MONOTONIC_RAW) if one wishes to measure "real" time (and not
+a time-like object like CPU cycles). This is because the clock on the
+other end of the NTP connection from you is probably better at keeping
+time: hopefully that thirty five thousand dollars of Cesium
+timekeeping goodness is doing something better than your PC's $3
+quartz crystal, after all.
Get more detail in the `documentation of the NTP daemon
<http://doc.ntp.org/4.1.2/ntpd.htm>`_.
@@ -682,10 +707,9 @@
GetTickCount Windows Seven 15.6 ms
========================= ================ ===============
-For CLOCK_MONOTONIC and CLOCK_MONOTONIC_RAW, the precision of this table is the
-result of clock_getres(). It looks like Linux does not implement
-clock_getres() and always return 1 nanosecond.
-
+For CLOCK_MONOTONIC and CLOCK_MONOTONIC_RAW, the precision of this
+table is the result of ``clock_getres()``. It looks like Linux does
+not implement ``clock_getres()`` and always returns 1 nanosecond.
mach_absolute_time
^^^^^^^^^^^^^^^^^^
@@ -697,8 +721,8 @@
mach_timebase_info() gives a fraction to convert the clock value to a
number of nanoseconds. According to the documentation (`Technical Q&A
QA1398 <https://developer.apple.com/library/mac/#qa/qa1398/>`_),
-mach_timebase_info() is always equal to one and never fails, even
-if the function may fail according to its prototype.
+mach_timebase_info() is always equal to one and never fails, even if
+the function may fail according to its prototype.
mach_absolute_time() stops during a sleep on a PowerPC CPU, but not on
an Intel CPU: `Different behaviour of mach_absolute_time() on i386/ppc
@@ -720,7 +744,8 @@
* `Linux clock_gettime() manual page
<http://linux.die.net/man/3/clock_gettime>`_
-CLOCK_MONOTONIC is available at least on the following operating systems:
+CLOCK_MONOTONIC is available at least on the following operating
+systems:
* DragonFly BSD, FreeBSD >= 5.0, OpenBSD, NetBSD
* Linux
@@ -736,30 +761,29 @@
On Linux, NTP may adjust the CLOCK_MONOTONIC rate (slewed), but it cannot
jump backward.
-CLOCK_MONOTONIC_RAW is specific to Linux. It is similar to CLOCK_MONOTONIC, but
-provides access to a raw hardware-based time that is not subject to NTP
-adjustments. CLOCK_MONOTONIC_RAW requires Linux 2.6.28 or later.
+CLOCK_MONOTONIC_RAW is specific to Linux. It is similar to
+CLOCK_MONOTONIC, but provides access to a raw hardware-based time that
+is not subject to NTP adjustments. CLOCK_MONOTONIC_RAW requires Linux
+2.6.28 or later.
CLOCK_MONOTONIC stops while the machine is suspended.
-clock_gettime() fails if the system does not support the specified
+``clock_gettime()`` fails if the system does not support the specified
clock, even if the standard C library supports it. For example,
CLOCK_MONOTONIC_RAW requires a kernel version 2.6.28 or later.
-clock_getres() gives the clock resolution. It is 1 nanosecond on
+``clock_getres()`` gives the clock resolution. It is 1 nanosecond on
Linux.
.. note::
- clock_gettime() requires to link the program against the rt
+ ``clock_gettime()`` requires to link the program against the rt
(real-time) library.
.. note::
- Linux provides also CLOCK_MONOTONIC_COARSE since Linux 2.6.32 which has less
- accurate than CLOCK_MONOTONIC but is faster.
-
-
+ Linux provides also CLOCK_MONOTONIC_COARSE since Linux 2.6.32 which
+ has less accuracy than CLOCK_MONOTONIC but is faster.
Windows: QueryPerformanceCounter
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -767,9 +791,9 @@
High-resolution performance counter. It is monotonic.
QueryPerformanceFrequency() gives its frequency.
-It has a much higher resolution, but has lower long term precision than
-GetTickCount() and timeGetTime() clocks. For example, it will drift
-compared to the low precision clocks.
+It has a much higher resolution, but has lower long term precision
+than GetTickCount() and timeGetTime() clocks. For example, it will
+drift compared to the low precision clocks.
Documentation:
@@ -812,11 +836,11 @@
* Windows XP had a bug (see `KB896256`_): on a multiprocessor
computer, QueryPerformanceCounter() returned a different value for
each processor. The bug was fixed in Windows XP SP2.
-* Issues with processor with variable frequency: the frequency is changed
- depending on the workload to reduce memory consumption.
-* Chromium don't use QueryPerformanceCounter() on Athlon X2 CPUs (model 15)
- because "QueryPerformanceCounter is unreliable" (see base/time_win.cc in
- Chromium source code)
+* Issues with processor with variable frequency: the frequency is
+ changed depending on the workload to reduce memory consumption.
+* Chromium don't use QueryPerformanceCounter() on Athlon X2 CPUs
+ (model 15) because "QueryPerformanceCounter is unreliable" (see
+ base/time_win.cc in Chromium source code)
.. _KB896256: http://support.microsoft.com/?id=896256
.. _KB274323: http://support.microsoft.com/?id=274323
@@ -837,15 +861,15 @@
GetTickCount64() was added to Windows Vista and Windows Server 2008.
-The clock resolution is 1 millisecond. Its precision is usually around
-15 ms. It is possible to improve the precision using the `undocumented
-NtSetTimerResolution() function
+The clock resolution is 1 millisecond. Its precision is usually
+around 15 ms. It is possible to improve the precision using the
+`undocumented NtSetTimerResolution() function
<http://undocumented.ntinternals.net/UserMode/Undocumented%20Functions/Time/NtSetTimerResolution.html>`_.
There are applications using this undocumented function, example:
`Timer Resolution <http://www.lucashale.com/timer-resolution/>`_.
-WaitForSingleObject() use the same timer than GetTickCount() with the same
-resolution.
+WaitForSingleObject() uses the same timer as GetTickCount() with the
+same resolution.
GetTickCount() has an precision of 55 ms on Windows 9x.
@@ -862,16 +886,17 @@
GetTickCount(), timeGetTime() rolls over after 2^32 milliseconds (49.7
days).
-The elapsed time retrieved by timeGetTime() includes time the system spends in
-sleep.
+The elapsed time retrieved by timeGetTime() includes time the system
+spends in sleep.
The default precision of the timeGetTime function can be five
milliseconds or more, depending on the machine.
-timeBeginPeriod() can be used to increase the precision of timeGetTime() up to
-1 millisecond, but it negatively affects power consumption. Calling
-timeBeginPeriod() also affects the granularity of some other timing calls, such
-as CreateWaitableTimer(), WaitForSingleObject() and Sleep().
+timeBeginPeriod() can be used to increase the precision of
+timeGetTime() up to 1 millisecond, but it negatively affects power
+consumption. Calling timeBeginPeriod() also affects the granularity
+of some other timing calls, such as CreateWaitableTimer(),
+WaitForSingleObject() and Sleep().
.. note::
@@ -879,7 +904,6 @@
library and so require to link the program against winmm or to
dynamically load the library.
-
Solaris: CLOCK_HIGHRES
^^^^^^^^^^^^^^^^^^^^^^
@@ -899,9 +923,8 @@
settimeofday(). The hires timer is ideally suited to performance
measurement tasks, where cheap, accurate interval timing is required.
-The linearity of gethrtime() is not preserved accross cpr
-suspend-resume cycle (`Bug 4272663
-<http://wesunsolve.net/bugid/id/4272663>`_).
+The linearity of gethrtime() is not preserved across a suspend-resume
+cycle (`Bug 4272663 <http://wesunsolve.net/bugid/id/4272663>`_).
Read the `gethrtime() manual page of Solaris 11
<http://docs.oracle.com/cd/E23824_01/html/821-1465/gethrtime-3c.html#scrolltoc>`_.
@@ -934,14 +957,14 @@
GetSystemTimeAsFileTime Windows Seven 15.6 ms
========================= ================ ===============
-For CLOCK_REALTIME, the precision of this table is the result of clock_getres().
-It looks like Linux does not implement clock_getres() and always return 1
-nanosecond.
+For CLOCK_REALTIME, the precision of this table is the result of
+clock_getres(). It looks like Linux does not implement clock_getres()
+and always returns 1 nanosecond.
.. note::
- Linux provides also CLOCK_REALTIME_COARSE since Linux 2.6.32 which has less
- accurate than CLOCK_REALTIME but is faster.
+ Linux provides also CLOCK_REALTIME_COARSE since Linux 2.6.32 which
+ has less accurate than CLOCK_REALTIME but is faster.
Windows: GetSystemTimeAsFileTime
@@ -983,8 +1006,8 @@
Process time
------------
-The process time cannot be set. It is not monotonic: the clocks stop while the
-process is idle.
+The process time cannot be set. It is not monotonic: the clocks stop
+while the process is idle.
========================= =============== =============
Name Resolution Include sleep
@@ -1009,10 +1032,11 @@
GetProcessTimes() Windows Seven 15.6 ms
========================= ================ ===============
-The precision of clock() in this table is the result of 1 / CLOCKS_PER_SEC.
-For CLOCK_PROCESS_CPUTIME_ID, the precision of this table is the result of
-clock_getres(). It looks like Linux does not implement clock_getres() and
-always return 1 nanosecond. For GetProcessTimes(), the precision is read using
+The precision of clock() in this table is the result of 1 /
+CLOCKS_PER_SEC. For CLOCK_PROCESS_CPUTIME_ID, the precision of this
+table is the result of clock_getres(). It looks like Linux does not
+implement clock_getres() and always returns 1 nanosecond. For
+GetProcessTimes(), the precision is read using
GetSystemTimeAdjustment().
@@ -1048,8 +1072,8 @@
Thread time
-----------
-The thread time cannot be set. It is not monotonic: the clocks stop while the
-thread is idle.
+The thread time cannot be set. It is not monotonic: the clocks stop
+while the thread is idle.
========================= ===============
Name Resolution
@@ -1068,10 +1092,10 @@
GetThreadTimes() Windows Seven 15.6 ms
========================= ================ ===============
-For CLOCK_THREAD_CPUTIME_ID, the precision of this table is the result of
-clock_getres(). It looks like Linux does not implement clock_getres() and
-always return 1 nanosecond. For GetThreadTimes(), the precision is read using
-GetSystemTimeAdjustment().
+For CLOCK_THREAD_CPUTIME_ID, the precision of this table is the result
+of clock_getres(). It looks like Linux does not implement
+clock_getres() and always return 1 nanosecond. For GetThreadTimes(),
+the precision is read using GetSystemTimeAdjustment().
Functions
^^^^^^^^^
@@ -1110,31 +1134,32 @@
sleep() is not affected by system clock update.
-On Linux, CLOCK_MONOTONIC and CLOCK_MONOTONIC_RAW includes time the system
-spends in sleep; but it does not include time spent in hibernation (ACPI S3
-mode). If the system clock jumps backward, CLOCK_MONOTONIC and
-CLOCK_MONOTONIC_RAW are not affected.
+On Linux, CLOCK_MONOTONIC and CLOCK_MONOTONIC_RAW includes time the
+system spends in sleep; but it does not include time spent in
+hibernation (ACPI S3 mode). If the system clock jumps backward,
+CLOCK_MONOTONIC and CLOCK_MONOTONIC_RAW are not affected.
Linux 2.6.39 and glibc 2.14 introduces a new clock: CLOCK_BOOTTIME.
-CLOCK_BOOTTIME is idential to CLOCK_MONOTONIC, except it also includes any time
-spent in suspend. Read also `Waking systems from suspend
-<http://lwn.net/Articles/429925/>`_ (March, 2011).
+CLOCK_BOOTTIME is idential to CLOCK_MONOTONIC, except that it also
+includes any time spent in suspend. Read also `Waking systems from
+suspend <http://lwn.net/Articles/429925/>`_ (March, 2011).
Other operating systems
-----------------------
-On Windows, GetTickCount() and GetTickCount64() include time the system
-spends in sleep; sleep() is not affected by system clock update.
+On Windows, GetTickCount() and GetTickCount64() include time the
+system spends in sleep; sleep() is not affected by system clock
+update.
-On FreeBSD 8, CLOCK_MONOTONIC include time the system spends in sleep; sleep()
-is not affected by system clock update.
-
-On OpenIndiana, CLOCK_MONOTONIC include time the system spends in sleep;
+On FreeBSD 8, CLOCK_MONOTONIC include time the system spends in sleep;
sleep() is not affected by system clock update.
-On Mac OS X, mach_absolute_time() include time the system spends in sleep;
-sleep() is not affected by system clock update. Sleep is interrupted during
-suspend.
+On OpenIndiana, CLOCK_MONOTONIC include time the system spends in
+sleep; sleep() is not affected by system clock update.
+
+On Mac OS X, mach_absolute_time() include time the system spends in
+sleep; sleep() is not affected by system clock update. Sleep is
+interrupted during suspend.
Sleeping
@@ -1181,18 +1206,18 @@
clock_nanosleep
---------------
-clock_nanosleep(clock_id, flags, nanoseconds, remaining):
-`Linux manpage of clock_nanosleep()
+clock_nanosleep(clock_id, flags, nanoseconds, remaining): `Linux
+manpage of clock_nanosleep()
<http://www.kernel.org/doc/man-pages/online/pages/man2/clock_nanosleep.2.html>`_.
If flags is TIMER_ABSTIME, then request is interpreted as an absolute
time as measured by the clock, clock_id. If request is less than or
-equal to the current value of the clock, then clock_nanosleep() returns
-immediately without suspending the calling thread.
+equal to the current value of the clock, then clock_nanosleep()
+returns immediately without suspending the calling thread.
-POSIX.1 specifies that changing the value of the CLOCK_REALTIME clock via
-clock_settime(2) shall have no effect on a thread that is blocked on a relative
-clock_nanosleep().
+POSIX.1 specifies that changing the value of the CLOCK_REALTIME clock
+via clock_settime(2) shall have no effect on a thread that is blocked
+on a relative clock_nanosleep().
select()
@@ -1200,31 +1225,31 @@
select(nfds, readfds, writefds, exceptfs, timeout).
-Since Linux 2.6.28, select() uses high-resolution timers to handle the timeout.
-A process has a "slack" attribute to configure the precision of the timeout, the
-default slack is 50 microseconds. Before Linux 2.6.28, timeouts for select()
-were handled by the main timing subsystem at a jiffy-level resolution. Read
-also `High- (but not too high-) resolution timeouts
-<http://lwn.net/Articles/296578/>`_ and `Timer slack
-<http://lwn.net/Articles/369549/>`_.
+Since Linux 2.6.28, select() uses high-resolution timers to handle the
+timeout. A process has a "slack" attribute to configure the precision
+of the timeout, the default slack is 50 microseconds. Before Linux
+2.6.28, timeouts for select() were handled by the main timing
+subsystem at a jiffy-level resolution. Read also `High- (but not too
+high-) resolution timeouts <http://lwn.net/Articles/296578/>`_ and
+`Timer slack <http://lwn.net/Articles/369549/>`_.
Other functions
---------------
* poll(), epoll()
- * sigtimedwait(). POSIX: "If the Monotonic Clock option is supported, the
- CLOCK_MONOTONIC clock shall be used to measure the time interval specified
- by the timeout argument."
- * pthread_cond_timedwait(), pthread_condattr_setclock(). "The default value of
- the clock attribute shall refer to the system clock."
- * sem_timedwait(): "If the Timers option is supported, the timeout shall be
- based on the CLOCK_REALTIME clock. If the Timers option is not supported,
- the timeout shall be based on the system clock as returned by the time()
- function. The resolution of the timeout shall be the resolution of the clock
- on which it is based."
- * WaitForSingleObject(): use the same timer than GetTickCount() with the same
- resolution.
+ * sigtimedwait(). POSIX: "If the Monotonic Clock option is supported,
+ the CLOCK_MONOTONIC clock shall be used to measure the time
+ interval specified by the timeout argument."
+ * pthread_cond_timedwait(), pthread_condattr_setclock(). "The default
+ value of the clock attribute shall refer to the system clock."
+ * sem_timedwait(): "If the Timers option is supported, the timeout
+ shall be based on the CLOCK_REALTIME clock. If the Timers option is
+ not supported, the timeout shall be based on the system clock as
+ returned by the time() function. The resolution of the timeout
+ shall be the resolution of the clock on which it is based."
+ * WaitForSingleObject(): use the same timer than GetTickCount() with
+ the same resolution.
Alternatives: API design
@@ -1239,11 +1264,12 @@
* time.seconds()
* time.steady()
* time.timeout_clock()
-* time.wallclock(): it is not the system time aka the "wall clock", but
- a monotonic clock with an unspecified starting point
+* time.wallclock(): it is not the system time aka the "wall clock",
+ but a monotonic clock with an unspecified starting point
-The name "time.try_monotonic()" was also proposed when time.monotonic() was
-falling back to the system clock when no monotonic clock was available.
+The name "time.try_monotonic()" was also proposed when
+time.monotonic() was falling back to the system clock when no
+monotonic clock was available.
time.perf_counter():
@@ -1255,23 +1281,25 @@
Only expose operating system clocks
-----------------------------------
-To not have to define high-level clocks, which is a difficult task, a simpler
-approach is to only expose operating system clocks. time.clock_gettime() and
-related clock identifiers were already added to Python 3.3 for example.
+To not have to define high-level clocks, which is a difficult task, a
+simpler approach is to only expose operating system clocks.
+time.clock_gettime() and related clock identifiers were already added
+to Python 3.3 for example.
Fallback to system clock
------------------------
-If no monotonic clock is available, time.monotonic() falls back to the system
-clock.
+If no monotonic clock is available, time.monotonic() falls back to the
+system clock.
Issues:
- * It is hard to define correctly such function in the documentation: is it
- monotonic? is it steady? is it adjusted?
- * Some user want to decide what to do when no monotonic clock is available:
- use another clock, display an error, or do something else
+* It is hard to define correctly such function in the documentation:
+ is it monotonic? is it steady? is it adjusted?
+* Some user want to decide what to do when no monotonic clock is
+ available: use another clock, display an error, or do something
+ else?
One function choosing the clock from a list of constraints
@@ -1279,38 +1307,39 @@
``time.get_clock(*flags)`` with the following flags:
- * time.MONOTONIC: clock cannot go backard
- * time.STEADY: clock rate is steady and the clock is not adjusted
- * time.HIGHRES: clock with the highest resolutions
+* time.MONOTONIC: clock cannot go backward
+* time.STEADY: clock rate is steady and the clock is not adjusted
+* time.HIGHRES: clock with the highest resolutions
-time.get_clock() returns None if the clock is found and so calls can be chained
-using the or operator. Example::
+time.get_clock() returns None if the clock is found and so calls can
+be chained using the or operator. Example::
- get_time = time.get_clock(time.MONOTONIC) or time.get_clock(time.STEADY) or time.time()
- t = get_time()
+ get_time = time.get_clock(time.MONOTONIC) or time.get_clock(time.STEADY) or time.time()
+ t = get_time()
Example of flags of system clocks:
- * QueryPerformanceCounter: MONOTONIC | HIGHRES
- * GetTickCount: MONOTONIC | STEADY
- * CLOCK_MONOTONIC: MONOTONIC | STEADY (or only MONOTONIC on Linux)
- * CLOCK_MONOTONIC_RAW: MONOTONIC | STEADY
- * gettimeofday(): (no flag)
+* QueryPerformanceCounter: MONOTONIC | HIGHRES
+* GetTickCount: MONOTONIC | STEADY
+* CLOCK_MONOTONIC: MONOTONIC | STEADY (or only MONOTONIC on Linux)
+* CLOCK_MONOTONIC_RAW: MONOTONIC | STEADY
+* gettimeofday(): (no flag)
One function with a flag: time.monotonic(fallback=True)
-------------------------------------------------------
- * time.monotonic(fallback=True) falls back to the system clock if no monotonic
- clock is available or if the monotonic clock failed.
- * time.monotonic(fallback=False) raises OSError if monotonic clock fails and
- NotImplementedError if the system does not provide a monotonic clock
+* time.monotonic(fallback=True) falls back to the system clock if no
+ monotonic clock is available or if the monotonic clock failed.
+* time.monotonic(fallback=False) raises OSError if monotonic clock
+ fails and NotImplementedError if the system does not provide a
+ monotonic clock
-"A keyword argument that gets passed as a constant in the caller is usually
-poor API."
+"A keyword argument that gets passed as a constant in the caller is
+usually poor API."
-Raising NotImplementedError for a function is something uncommon in Python and
-should be avoided.
+Raising NotImplementedError for a function is something uncommon in
+Python and should be avoided.
One function, no flag
@@ -1343,10 +1372,10 @@
Issues of a hacked monotonic function:
- * if the clock is accidentally set forward by an hour and then back
- again, you wouldn't have a useful clock for an hour
- * the cache is not shared between processes so different processes wouldn't
- see the same clock value
+* if the clock is accidentally set forward by an hour and then back
+ again, you wouldn't have a useful clock for an hour
+* the cache is not shared between processes so different processes
+ wouldn't see the same clock value
Footnotes
--
Repository URL: http://hg.python.org/peps
More information about the Python-checkins
mailing list