iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

PEP 418: more grammar fixes

This commit is contained in:
Georg Brandl 2012-03-31 08:53:07 +02:00
parent 2534727122
commit 7638f18993
1 changed files with 54 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
pep-0418.txt
View File

@ -23,20 +23,22 @@ Rationale
Use cases: Use cases:
* Display the current time to a human (e.g. display a calendar or draw * Display the current time to a human (e.g. display a calendar or draw
a wall clock): use system clock. time.time() or a wall clock): use system clock, i.e. time.time() or
datetime.datetime.now() datetime.datetime.now().
* Benchmark, profiling, timeout: time.highres() * Benchmark, profiling, timeout: time.highres().
* Event scheduler: time.monotonic(), or time.monotonic(fallback=False) * Event scheduler: time.monotonic(), or time.monotonic(fallback=False).
Functions Functions
========= =========
* time.time(): system clock, "wall clock" To fulfill the use cases, the functions' properties are:
* time.highres(): clock with the best accuracy
* time.time(): system clock, "wall clock".
* time.highres(): clock with the best accuracy.
* time.monotonic(fallback=True): monotonic clock. If no monotonic * time.monotonic(fallback=True): monotonic clock. If no monotonic
clock is available, falls back to system clock by default, or raises clock is available, falls back to system clock by default, or raises
an OSError if *fallback* is False. time.monotonic(fallback=True) an OSError if *fallback* is False. time.monotonic(fallback=True)
cannot go backward. cannot go backward.
@ -45,7 +47,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 system administrator or automatically by a NTP daemon. It can jump
backward and forward. It is not monotonic. backward and forward. It is not monotonic.
It is available on all platforms and cannot fail. It is available on all platforms and cannot fail.
@ -90,10 +92,10 @@ By default, it falls back to the system clock if no monotonic clock is
available or if the monotonic clock failed, and so it cannot fail. If available or if the monotonic clock failed, and so it cannot fail. If
fallback is False, it raises OSError if the monotonic clock failed and fallback is False, it raises OSError if the monotonic clock failed and
NotImplementedError if the platform does not provide a monotonic clock NotImplementedError if the platform does not provide a monotonic clock
(ex: GNU/Hurd). (e.g. on GNU/Hurd).
The elapsed time may or may not include time the system spends in The elapsed time may or may not include time the system spends in
sleep or hibernation, it depends on the operating system. sleep or hibernation; this depends on the operating system.
Pseudo-code [#pseudo]_:: Pseudo-code [#pseudo]_::
@ -165,17 +167,17 @@ Pseudo-code [#pseudo]_::
raise NotImplementedError("you platform does not provide any monotonic clock") raise NotImplementedError("you platform does not provide any monotonic clock")
return time.time() return time.time()
On Windows, QueryPerformanceCounter() is not used even if it has a On Windows, QueryPerformanceCounter() is not used even though it has a
better resolution than GetTickCount(). It is not reliable and has too better resolution than GetTickCount(). It is not reliable and has too
much issues. many issues.
.. note:: .. note::
time.monotonic() detects GetTickCount() integer overflow (32 bits, time.monotonic() detects GetTickCount() integer overflow (32 bits,
roll-over after 49.7 days): it increases a delta by 2\ :sup:`32` 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 each time than an overflow is detected. The delta is stored in the
process local state and so time.monotonic() value may be different process-local state and so the value of time.monotonic() may be
in two Python processes. different in two Python processes.
time.highres() time.highres()
@ -250,11 +252,11 @@ adjusted and cannot be set.
mach_timebase_info() gives a fraction to convert the clock value to a mach_timebase_info() gives a fraction to convert the clock value to a
number of nanoseconds. According to the documentation (`Technical Q&A number of nanoseconds. According to the documentation (`Technical Q&A
QA1398 <https://developer.apple.com/library/mac/#qa/qa1398/>`_), QA1398 <https://developer.apple.com/library/mac/#qa/qa1398/>`_),
mach_timebase_info() is always equals to one and does never fail, even mach_timebase_info() is always equal to one and never fails, even
if the function may fail according to its prototype. if the function may fail according to its prototype.
mach_absolute_time() stops during a sleep on PowerPC CPU, but not on mach_absolute_time() stops during a sleep on a PowerPC CPU, but not on
Intel CPU: `Different behaviour of mach_absolute_time() on i386 / ppc an Intel CPU: `Different behaviour of mach_absolute_time() on i386/ppc
<http://lists.apple.com/archives/PerfOptimization-dev/2006/Jul/msg00024.html>`_. <http://lists.apple.com/archives/PerfOptimization-dev/2006/Jul/msg00024.html>`_.
mach_absolute_time() has a resolution of 1 nanosecond. mach_absolute_time() has a resolution of 1 nanosecond.
@ -262,8 +264,8 @@ mach_absolute_time() has a resolution of 1 nanosecond.
CLOCK_MONOTONIC, CLOCK_MONOTONIC_RAW CLOCK_MONOTONIC, CLOCK_MONOTONIC_RAW
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
CLOCK_MONOTONIC and CLOCK_MONOTONIC_RAW represents monotonic time CLOCK_MONOTONIC and CLOCK_MONOTONIC_RAW represent monotonic time since
since some unspecified starting point. They cannot be set. some unspecified starting point. They cannot be set.
Documentation: refer to the manual page of your operating system. Documentation: refer to the manual page of your operating system.
Examples: Examples:
@ -291,22 +293,23 @@ CLOCK_MONOTONIC, but provides access to a raw hardware-based time that
is not subject to NTP adjustments. CLOCK_MONOTONIC_RAW requires Linux is not subject to NTP adjustments. CLOCK_MONOTONIC_RAW requires Linux
2.6.28 or later. 2.6.28 or later.
On Linux, NTP may adjust CLOCK_MONOTONIC rate, but not jump backward. On Linux, NTP may adjust the CLOCK_MONOTONIC rate, but it cannot jump
If available, CLOCK_MONOTONIC_RAW should be used instead of backward. If available, CLOCK_MONOTONIC_RAW should be used instead of
CLOCK_MONOTONIC to avoid the NTP adjustment. CLOCK_MONOTONIC to avoid the NTP adjustment.
CLOCK_MONOTONIC stops while the machine is suspended. 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, whereas the standard C library supports it. For example, clock, even if the standard C library supports it. For example,
CLOCK_MONOTONIC_RAW requires a kernel version 2.6.28 or later. 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. Linux.
.. note:: .. note::
clock_gettime() requires to link the program to the rt (real-time)
library. clock_gettime() requires to link the program against the rt
(real-time) library.
Windows: QueryPerformanceCounter Windows: QueryPerformanceCounter
@ -315,7 +318,7 @@ Windows: QueryPerformanceCounter
High-resolution performance counter. It is monotonic. High-resolution performance counter. It is monotonic.
QueryPerformanceFrequency() gives its frequency. QueryPerformanceFrequency() gives its frequency.
It has much higher resolution, but has lower long term accuracy than It has a much higher resolution, but has lower long term accuracy than
GetTickCount() and timeGetTime() clocks. For example, it will drift GetTickCount() and timeGetTime() clocks. For example, it will drift
compared to the low precision clocks. compared to the low precision clocks.
@ -330,9 +333,9 @@ Hardware clocks used by QueryPerformanceCounter:
* Windows XP: RDTSC instruction of Intel processors, the clock * Windows XP: RDTSC instruction of Intel processors, the clock
frequency is the frequency of the processor (between 200 MHz and 3 frequency is the frequency of the processor (between 200 MHz and 3
GHz, usually greater than 1 GHz nowadays) GHz, usually greater than 1 GHz nowadays).
* Windows 2000: ACPI power management timer, frequency = 3,549,545 * Windows 2000: ACPI power management timer, frequency = 3,549,545 Hz.
Hz. It can be forced through the "/usepmtimer" flag in boot.ini It can be forced through the "/usepmtimer" flag in boot.ini.
.. * Windows 95/98: 8245 PIT chipset, frequency = 1,193,181 Hz .. * Windows 95/98: 8245 PIT chipset, frequency = 1,193,181 Hz
@ -344,12 +347,12 @@ counter.
QueryPerformanceCounter() cannot be adjusted: QueryPerformanceCounter() cannot be adjusted:
`SetSystemTimeAdjustment() `SetSystemTimeAdjustment()
<http://msdn.microsoft.com/en-us/library/windows/desktop/ms724943(v=vs.85).aspx>`_ <http://msdn.microsoft.com/en-us/library/windows/desktop/ms724943(v=vs.85).aspx>`_
does only adjust the system time. only adjusts the system time.
Bugs: Bugs:
* The performance counter value may unexpectedly leap forward because * The performance counter value may unexpectedly leap forward because
of a hardware bug, see the `KB274323`_. of a hardware bug, see `KB274323`_.
* On VirtualBox, QueryPerformanceCounter() does not increment the high * On VirtualBox, QueryPerformanceCounter() does not increment the high
part every time the low part overflows, see `Monotonic timers part every time the low part overflows, see `Monotonic timers
<http://code-factor.blogspot.fr/2009/11/monotonic-timers.html>`_ <http://code-factor.blogspot.fr/2009/11/monotonic-timers.html>`_
@ -375,13 +378,13 @@ not adjusted by SetSystemTimeAdjustment(). MSDN documentation:
`GetTickCount64() `GetTickCount64()
<http://msdn.microsoft.com/en-us/library/windows/desktop/ms724411(v=vs.85).aspx>`_. <http://msdn.microsoft.com/en-us/library/windows/desktop/ms724411(v=vs.85).aspx>`_.
The elapsed time retrieved by GetTickCount or GetTickCount64 includes The elapsed time retrieved by GetTickCount() or GetTickCount64()
time the system spends in sleep or hibernation. includes time the system spends in sleep or hibernation.
GetTickCount64() was added to Windows Vista and Windows Server 2008. GetTickCount64() was added to Windows Vista and Windows Server 2008.
The clock resolution is 1 millisecond. Its accuracy is usually around The clock resolution is 1 millisecond. Its accuracy is usually around
15 ms. It is possible to improve the accuracy using the `undocumented 15 ms. It is possible to improve the accuracy using the `undocumented
NtSetTimerResolution() function NtSetTimerResolution() function
<http://undocumented.ntinternals.net/UserMode/Undocumented%20Functions/Time/NtSetTimerResolution.html>`_. <http://undocumented.ntinternals.net/UserMode/Undocumented%20Functions/Time/NtSetTimerResolution.html>`_.
There are applications using this undocumented function, example: There are applications using this undocumented function, example:
@ -392,7 +395,7 @@ Windows: timeGetTime
^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^
The timeGetTime function retrieves the system time, in milliseconds. The timeGetTime function retrieves the system time, in milliseconds.
The system time is the time elapsed since Windows was started. Read The system time is the time elapsed since Windows was started. Read
the `timeGetTime() documentation the `timeGetTime() documentation
<http://msdn.microsoft.com/en-us/library/windows/desktop/dd757629(v=vs.85).aspx>`_. <http://msdn.microsoft.com/en-us/library/windows/desktop/dd757629(v=vs.85).aspx>`_.
@ -408,15 +411,16 @@ timeGetTime() up to 1 millisecond, but it negatively affects power
consumption. consumption.
.. note:: .. note::
timeGetTime() and timeBeginPeriod() are part the Windows multimedia timeGetTime() and timeBeginPeriod() are part the Windows multimedia
library and so require to link the program with winmm or to load library and so require to link the program against winmm or to
dynamically the library. dynamically load the library.
Solaris: CLOCK_HIGHRES Solaris: CLOCK_HIGHRES
^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^
The Solaris OS has an CLOCK_HIGHRES timer that attempts to use an The Solaris OS has a CLOCK_HIGHRES timer that attempts to use an
optimal hardware source, and may give close to nanosecond resolution. optimal hardware source, and may give close to nanosecond resolution.
CLOCK_HIGHRES is the nonadjustable, high-resolution clock. For timers CLOCK_HIGHRES is the nonadjustable, high-resolution clock. For timers
created with a clockid_t value of CLOCK_HIGHRES, the system will created with a clockid_t value of CLOCK_HIGHRES, the system will
@ -468,7 +472,7 @@ and time().
The system time resolution can be read using The system time resolution can be read using
GetSystemTimeAdjustment(). The accuracy is usually between 1 GetSystemTimeAdjustment(). The accuracy is usually between 1
millisecond and 15 milliseconds. Resolution: millisecond and 15 milliseconds. Resolution:
* GetSystemTimeAsFileTime(): 100 nanoseconds * GetSystemTimeAsFileTime(): 100 nanoseconds
* ftime(): 1 millisecond * ftime(): 1 millisecond
@ -508,7 +512,7 @@ Process
* clock(): * clock():
* Windows: The elapsed wall-clock time since the start of the * Windows: The elapsed wall-clock time since the start of the
process (elapsed time in seconds times CLOCKS_PER_SEC). It can process (elapsed time in seconds times CLOCKS_PER_SEC). It can
fail. fail.
* UNIX: returns an approximation of processor time used by the * UNIX: returns an approximation of processor time used by the
program. program.
@ -519,10 +523,11 @@ Process
Resolution: Resolution:
* clock() rate is CLOCKS_PER_SEC. It was called CLK_TCK in Microsoft * clock() rate is CLOCKS_PER_SEC. It was called CLK_TCK in Microsoft
C before 6.0. On Linux 3, clock() has a resolution of 1 microsecond C before 6.0. On Linux 3, clock() has a resolution of 1
microsecond.
* The clock resolution can be read using clock_getres(). * The clock resolution can be read using clock_getres().
clock_getres(CLOCK_REALTIME) is 1 nanosecond on Linux clock_getres(CLOCK_REALTIME) is 1 nanosecond on Linux.
* GetProcessTimes(): call GetSystemTimeAdjustment() * GetProcessTimes(): call GetSystemTimeAdjustment().
Thread Thread
^^^^^^ ^^^^^^
@ -553,14 +558,16 @@ QueryUnbiasedInterruptTime() is not monotonic.
QueryUnbiasedInterruptTime() was introduced in Windows 7. QueryUnbiasedInterruptTime() was introduced in Windows 7.
Linux timers Linux timers
------------ ------------
There were 4 implementations of the time in the Linux kernel: UTIME There were 4 implementations of the time in the Linux kernel: UTIME
(1996), timer wheel (1997), HRT (2001) and hrtimers (2007). The later (1996), timer wheel (1997), HRT (2001) and hrtimers (2007). The
is the result of the "high-res-timers" project started by George latter is the result of the "high-res-timers" project started by
Anzinger in 2001, contributed by Thomas Gleixner and Douglas Niehaus. George Anzinger in 2001, with contributions by Thomas Gleixner and
hrtimers implementation was merged into Linux 2.6.21 released in 2007. Douglas Niehaus. hrtimers implementation was merged into Linux
2.6.21, released in 2007.
hrtimers supports various clock sources. It sets a priority to each hrtimers supports various clock sources. It sets a priority to each
source to decide which one will be used. source to decide which one will be used.
@ -642,7 +649,7 @@ sure that the values returned are indeed monotonic.
* Virtual machines provide less reliable clocks. * Virtual machines provide less reliable clocks.
* QueryPerformanceCounter() has known bugs (only one is not fixed yet) * QueryPerformanceCounter() has known bugs (only one is not fixed yet)
Python may only workaround a specific known operating system bug: Python may only work around a specific known operating system bug:
`KB274323`_ contains a code example to workaround the bug (use `KB274323`_ contains a code example to workaround the bug (use
GetTickCount() to detect QueryPerformanceCounter() leap). GetTickCount() to detect QueryPerformanceCounter() leap).