On 3/26/2012 7:32 PM, Victor Stinner wrote:

I started to write the PEP 418 to clarify the notions of monotonic and steady clocks.

""" time.steady This clock advances at a steady rate relative to real time. It may be adjusted. """ Please do not call this "steady". If the clock can be adjusted, then it is not "steady" by any acceptable definition. I cannot fathom the utility of this function other than as a function that provides an automatic fallback from "time.monotonic()". More importantly: this definition of "steady" is in conflict with the C++0x definition of "steady" that is where you sourced this named from![1] """ time.steady(strict=False) falls back to another clock if no monotonic clock is not available or does not work, but it does never fail. """ As I say above, that is so far away from what "steady" implies that this is a misnomer. What you are describing is a best-effort clock, which sounds a lot more like the C++0x "high resolution" clock. """ time.steady(strict=True) raises OSError if monotonic clock fails or NotImplementedError if the system does not provide a monotonic clock """ What is the utility of "strict=True"? If I wanted that mode of operation, then why would I not just try to use "time.monotonic()" directly? At worst, it generates an "AttributeError" (although that is not clear from your PEP). What is the use case for "strict=True" that is not covered by your "time.monotonic()"? If you want to define new clocks, then I wish you would use the same definitions that C++0x is using. That is: system_clock = wall clock time monotonic_clock = always goes forward but can be adjusted steady_clock = always goes forward and cannot be adjusted high_resolution_clock = steady_clock || system_clock Straying from that is only going to create confusion. Besides that, the one use case for "time.steady()" that you give (benchmarking) is better served by a clock that follows the C++0x definition. As well, certain kinds of scheduling/timeouts would be better implemented with the C++0x definition for "steady" rather than the "monotonic" one and vice-versa. Rather, it seems you have a particular use-case in mind and have settled on calling that a "steady" clock despite how it belies its name. [1] http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3128.html#time.cloc... """ Objects of class steady_clock represent clocks for which values of time_point advance at a steady rate relative to real time. That is, the clock may not be adjusted. """ -- Scott Dial scott@scottdial.com

So does anyone care to dig into the libstd++/boost/windoze implementation to see how they each did steady_clock?

Cheers, that clears things up.

On Tue, Mar 27, 2012 at 3:51 PM, Jeffrey Yasskin wrote:

FWIW, I'm not sure you're the right person to drive time PEPs. You don't seem to have come into it with much knowledge of time, and it's taken several repetitions for you to take corrections into account in both this discussion and the Decimal/datetime representation PEP.

The main things required to be a PEP champion are passion and a willingness to listen to expert feedback and change course in response. If someone lacks the former, they will lose steam and their PEP will eventually be abandoned. If they don't listen to expert feedback, then their PEP will ultimately be rejected (sometimes a PEP will be rejected anyway as a poor fit for the language *despite* being responsive to feedback, but that's no slight to the PEP author). Victor has shown himself to be quite capable of handling those aspects of the PEP process, and the topics he has recently applied himself to are ones where it is worthwhile having a good answer in the standard library for Python 3.3. Cheers, Nick. -- Nick Coghlan   |   ncoghlan@gmail.com   |   Brisbane, Australia

On Mar 26, 2012, at 10:26 PM, Zooko Wilcox-O'Hearn wrote:

Note that the C++ standard deprecated monotonic_clock once they realized that there is absolutely no point in having a clock that jumps forward but not back, and that none of the operating systems implement such a thing -- instead they all implement a clock which doesn't jump in either direction.

This is why I don't like the C++ terminology, because it seems to me that the C++ standard makes incorrect assertions about platform behavior, and apparently they standardized it without actually checking on platform capabilities. The clock does jump forward when the system suspends. At least some existing implementations of steady_clock in C++ already have this problem, and I think they all might. I don't think they can fully fix it without kernel changes, either. On linux, see discussion of a possible CLOCK_BOOTTIME in the future. The only current way I know of to figure out how long the system has been asleep is to look at the wall clock and compare, and we've already gone over the problems with relying on the wall clock. Plus, libstdc++ gives you no portable way to get informed about system power management events, so you can't fix it even if you know about this problem, natch. Time with respect to power management state changes is something that the PEP should address fully, for each platform. On the other hand, hopefully you aren't controlling your python-based CNC laser welder from a laptop that you are closing the lid on while the beam is in operation. Not that the PEP shouldn't address it, but maybe it should just address it to say "you're on your own" and refer to a few platform-specific resources for correcting this type of discrepancy. (https://developer.apple.com/library/mac/#qa/qa1340/_index.html, http://msdn.microsoft.com/en-us/library/aa394362.aspx, http://upower.freedesktop.org/docs/UPower.html#UPower::Sleeping). -glyph

Reading this discussion, my conclusion is that not only us are confused, but everyone is. I think therefore, that the way forward is to only expose underlying API functions, and pretty much have no intelligence at all. At a higher level, we have two different "desires" here. You may want a monotonic clock, or you may not care. You may want high resolution, or you might not care. Which one is more important is something only you know. Therefore, we must have, at the minimum, a function that returns the highest resolution monotonic clock possible, as well as a function that returns the highest resolution system/wall clock possible. We also need ways to figure out what the resolution is of these clocks. In addition to that, you may have the requirement that the monotonic clock also should not be able to jump forward, but if I understand things correctly, most current OS's will not guarantee this. You may also have the requirement that the clock not only does not jump forward, but that it doesn't go faster or slower. Some clock implementations will speed up or slow down the monotonic clock, without jumps, to sync up with the wall clock. It seems only Unix provides a monotonic clock (CLOCK_MONOTONIC_RAW) that does not get adjusted at all. Now between all these requirements, only you know which one is more important? Do you primarily want a raw monotonic clock, and secondarily high resolution, or is the resolution more important than it being monotonic? (Because if you need a high resolution, you are usually measuring small timeframes, and the clock is more unlikely to be adjusted, for example). Since there is no obvious "A is better than B that is better than C" we first of all have to expose the underlying API's somehow, to allow people to make their own decisions. Secondly, since apparently not only python-dev, but many others as well, are a bit confused on this complex issue, I'm not sure we can provide any high-level functions that makes a best choice. As such the proposed time.monotonic() to get the monotonic clock on the various systems makes a lot of sense to me. It should get the highest resolution available on the system. Get GetTickCount64() of available on Windows, else GetTickCount(). The function could have a raw=False parameter to select between clock_gettime(CLOCK_MONOTONIC) and clock_gettime(CLOCK_MONOTONIC_RAW) on Unix, and it would get mach_absolute_time() on OS X. If no monotonic clock is available, it should raise an error.The same if you pass in raw=True and there is no monotonic clock that has no adjustments available. In the same vein, time.time() should provide the highest resolution system clock/wall clock available. We also need functions or attributes to get the resolution of these clocks. But a time.steady() that tries to get a "best case" doesn't make sense at this time, as apparently nobody knows what a best case is, or what it should be called, except that it should apparently not be called steady(). Since monotonic() raises an error if there is no monotonic clock available, implementing your own fallback is trivial in any case. //Lennart

Nick Coghlan wrote:

The 3.3 time module would then be left with three interfaces:

time.time() # Highest resolution timer available time.monotonic() # I'm not yet convinced we need the "raw" parameter but don't much mind either way time.try_monotonic() # Monotonic is preferred, but non-monotonic presents a tolerable risk

+1 ~Ethan~

I started to write the PEP 418 to clarify the notions of monotonic and steady clocks.

I replaced time.steady() by time.try_monotonic(). I misunderstood "may not" in the C++ doc: I understood it as "it may be adjusted by NTP", whereas it means "it cannot be adjusted". Sorry for the confusion. I added a time.hires() clock because time.monotonic() and time.try_monotonic() are not the best clocks for profiling or benchmarking. For example, on Windows, time.hires() uses QueryPerformanceCounter() whereas time.monotonic() and time.try_monotonic() uses GetTickCount[64](). I added the pseudo-code of each function. I hope that it is easier to understand than a long text. Victor

What is the utility of "strict=True"? If I wanted that mode of operation, then why would I not just try to use "time.monotonic()" directly?

I mentioned the strict=True API in the PEP just to list all propositions, but the PEP only proposes time.monotonic() and time.try_monotonic(), no the flags API.

At worst, it generates an "AttributeError" (although that is not clear from your PEP).

I tried to mention when a function is always available or not always available. Is it better in the last version of the PEP?

 system_clock = wall clock time  monotonic_clock = always goes forward but can be adjusted  steady_clock = always goes forward and cannot be adjusted  high_resolution_clock = steady_clock || system_clock

I tried to follow these names in the PEP. I don't propose steady_clock because I don't see exactly which clocks would be used to implement it, nor if we need to provide monotonic *and* steady clocks. What do you think?

Straying from that is only going to create confusion. Besides that, the one use case for "time.steady()" that you give (benchmarking) is better served by a clock that follows the C++0x definition.

I added a time.hires() clock to the PEP for the benchmarking/profiling use case. This function is not always available and so a program has to fallback manually to another clock. I don't think that it is an issue: Python programs already have to choose between time.clock() and time.time() depending on the OS (e.g. timeit module and pybench program).

As well, certain kinds of scheduling/timeouts would be better implemented with the C++0x definition for "steady" rather than the "monotonic" one and vice-versa.

Sorry, I don't understand. Which kind of scheduling/timeouts? The PEP is still a draft (work-in-progress). Victor

2012/3/27 Jeffrey Yasskin :

FWIW, I'm not sure you're the right person to drive time PEPs.

I don't want to drive the PEP. Anyone is invited to contribute, as I wrote in my first message. I'm completing/rewriting the PEP with all comments. Victor

That's simple clear and explicit: try_monotic() tries to use the monotic clock if it can, but falls back to time.time() rather than failing entirely if no monotonic clock is available.

I renamed time.steady() to time.try_monotonic() in the PEP. It's a temporary name until we decide what to do with this function. I also changed it to fallback to time.hires() if time.monotonic() is not available or failed. Victor

I renamed time.steady() to time.try_monotonic() in the PEP. It's a temporary name until we decide what to do with this function.

How about get rid of it? Also monotonic should either not exist if it's not available, or always guarantee a (artificially) monotonic value. Finding out that something is already known to not work shouldn't require a call and a faked OSError.

Matt, we need the fallback behaviour in the stdlib so we can gracefully degrade the stdlib's *own* timeout handling back to the 3.2 status quo when there is no monotic clock available. It is *not* acceptable for the Python 3.3 stdlib to only work on platforms that provide a monotonic clock. Since duplicating that logic in every module that handles timeouts would be silly, it makes sense to provide an obvious way to do it in the time module. -- Sent from my phone, thus the relative brevity :)

On Mar 28, 2012 8:38 AM, "Victor Stinner" wrote:

Scott wrote:

<< The Boost implementation can be summarized as:

system_clock:

mac = gettimeofday posix = clock_gettime(CLOCK_REALTIME) win = GetSystemTimeAsFileTime

steady_clock:

mac = mach_absolute_time posix = clock_gettime(CLOCK_MONOTONIC) win = QueryPerformanceCounter

high_resolution_clock:

* = { steady_clock, if available system_clock, otherwise } >>

I read again the doc of the QElapsedTimer class of the Qt library. So Qt

and Boost agree to say that QueryPerformanceCounter() *is* monotonic.

I was confused because of a bug found in 2006 in Windows XP on multicore

processors. QueryPerformanceCounter() gave a different value on each core. The bug was fixed in Windows and is known as KB896256 (I already added a link to the bug in the PEP).

...

...

I added a time.hires() clock to the PEP for the benchmarking/profiling use case (...)

It is this always-having-to-manually-fallback-depending-on-os that I was hoping your new functionality would avoid. Is time.try_monotonic() suitable for this usecase?

If QueryPerformanceCounter() is monotonic, the API can be simplified to:

* time.time() = system clock * time.monotonic() = monotonic clock * time.hires() = monotonic clock or fallback to system clock

time.hires() definition is exactly what I was trying to implement with

"time.steady(strict=True)" / "time.try_monotonic()".

--

Scott> monotonic_clock = always goes forward but can be adjusted Scott> steady_clock = always goes forward and cannot be adjusted

I don't know if the monotonic clock should be called time.monotonic() or

time.steady(). The clock speed can be adjusted by NTP, at least on Linux < 2.6.28. Monotonic. It's still monotonic if it is adjusted forward, and that's okay.

I don't know if other clocks used by my time.monotonic() proposition can

be adjusted or not.

If I understand correctly, time.steady() cannot be implemented using

CLOCK_MONOTONIC on Linux because CLOCK_MONOTONIC can be adjusted?

Does it really matter if a monotonic speed is adjusted?

Victor _______________________________________________ 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/anacrolix%40gmail.com

On 3/27/2012 8:36 PM, Victor Stinner wrote:

Scott wrote: Scott> monotonic_clock = always goes forward but can be adjusted Scott> steady_clock = always goes forward and cannot be adjusted

I don't know if the monotonic clock should be called time.monotonic() or time.steady(). The clock speed can be adjusted by NTP, at least on Linux < 2.6.28.

I don't know if other clocks used by my time.monotonic() proposition can be adjusted or not.

If I understand correctly, time.steady() cannot be implemented using CLOCK_MONOTONIC on Linux because CLOCK_MONOTONIC can be adjusted?

Does it really matter if a monotonic speed is adjusted?

You are right that CLOCK_MONOTONIC can be adjusted, so the Boost implementation is wrong. I'm not sure that CLOCK_MONOTONIC_RAW is right either due to suspend -- there doesn't appear to be a POSIX or Linux clock that is defined that meets the "steady" definition. I am not familiar enough with Windows or Mac to know for certain whether the Boost implementation has the correct behaviors either. With that in mind, it's certainly better that we just provide time.monotonic() for now. If platform support becomes available, then we can expose that as it becomes available in the future. In other words, at this time, I don't think "time.steady()" can be implemented faithfully for any platform so lets just not have it at all. In that case, I don't think time.try_monotonic() is really needed because we can emulate "time.monotonic()" in software if the platform is deficient. I can't imagine a scenario where you would ask for a monotonic clock and would rather have an error than have Python fill in the gap with an emulation. -- Scott Dial scott@scottdial.com

...

 * time.time() = system clock  * time.monotonic() = monotonic clock  * time.hires() = monotonic clock or fallback to system clock

time.hires() definition is exactly what I was trying to implement with "time.steady(strict=True)" / "time.try_monotonic()".

Please don't call the fallback version "hires" as it suggests it may be higher resolution than time.time() and that's completely the wrong idea.

Why would it be a wrong idea? On Windows, time.monotonic() frequency is at least 1 MHz (can be GHz if it uses your CPU TSC) whereas time.time() is only updated each millisecond at the best case (each 15 ms by default if I remember correctly). On UNIX, CLOCK_MONOTONIC has the same theorical resolution than CLOCK_REALTIME (1 nanosecond thanks to the timespec structure) and I expect the same accuracy. On Mac, I don't know if mach_absolute_time() is more or as accurate than time.time(). time.hires() uses time.monotonic() if available, so if time.monotonic() has an higher resolution than time.time(), time.hires() can also be called a high-resolution clock. In practice, time.monotonic() is available on all modern platforms.

If we're simplifying the idea to only promising a monotonic clock (i.e. will never go backwards within a given process, but may produce the same value for an indefinite period, and may jump forwards by arbitrarily large amounts),

I don't know any monotonic clock jumping "forwards by arbitrarily large amounts". Linux can change CLOCK_MONOTONIC speed, but NTP doesn't "jump".

then we're back to being able to enforce monotonicity even if the underlying clock jumps backwards due to system clock adjustments.

Do you know a monotonic clock that goes backward? If yes, Python might workaround the clock bug directly in time.monotonic(). But I would prefer to *not* workaround OS bugs. Victor

On 3/28/2012 4:48 AM, Victor Stinner wrote:

...

...

Scott> monotonic_clock = always goes forward but can be adjusted Scott> steady_clock = always goes forward and cannot be adjusted

I don't know if the monotonic clock should be called time.monotonic() or time.steady(). The clock speed can be adjusted by NTP, at least on Linux < 2.6.28. (...)

You are right that CLOCK_MONOTONIC can be adjusted, so the Boost implementation is wrong. I'm not sure that CLOCK_MONOTONIC_RAW is right either due to suspend -- there doesn't appear to be a POSIX or Linux clock that is defined that meets the "steady" definition.

The term "adjusted" should be clarified. A clock can be adjusted by setting its counter (e.g. setting the system date and time) or by changing temporary its frequency (to go faster or slower). Linux only adjusts CLOCK_MONOTONIC frequency but the clock is monotonic because it always goes forward. The monotonic property can be described as:

t1=time.monotonic() t2=time.monotonic() assert t2 >= t1

I agree. The point I was making is that implication of "steady" is that (t2-t1) is the same (given that t2 and t1 occur in time at the same relative moments), which is a guarantee that I don't see any platform providing currently. Any clock that can be "adjusted" in any manner is not going to meet the "steady" criterion.

...

In that case, I don't think time.try_monotonic() is really needed because we can emulate "time.monotonic()" in software if the platform is deficient.

As I wrote, I don't think that Python should workaround OS bugs. If the OS monotonic clock is not monotonic, the OS should be fixed.

I sympathize with this, but if the idea is that the Python stdlib should use time.monotonic() for scheduling, then it needs to always be available. Otherwise, we are not going to use it ourselves, and what sort of example is that to set?

...

I can't imagine a scenario where you would ask for a monotonic clock and would rather have an error than have Python fill in the gap with an emulation.

Sorry, I don't understand what you mean with "fill in the gap with an emulation". You would like to implement a monotonic clock based on the system clock?

If "time.monotonic()" is only sometimes available, then I don't see the added clock being anything more than an amusement. (In this case, I'd rather just use clock_gettime() and friends directly, because I have to be platform aware anyways.) What developers want is a timer that is useful for scheduling things to happen after predictable interval in the future, so we should give them that to the best of our ability. -- Scott Dial scott@scottdial.com

Georg Brandl wrote:

On 28.03.2012 06:45, Nick Coghlan wrote:

...

On Wed, Mar 28, 2012 at 10:36 AM, Victor Stinner wrote:

...

If QueryPerformanceCounter() is monotonic, the API can be simplified to:

* time.time() = system clock * time.monotonic() = monotonic clock * time.hires() = monotonic clock or fallback to system clock

time.hires() definition is exactly what I was trying to implement with "time.steady(strict=True)" / "time.try_monotonic()". Please don't call the fallback version "hires" as it suggests it may be higher resolution than time.time() and that's completely the wrong idea.

It's also a completely ugly name, since it's quite hard to figure out what it is supposed to stand for in the first place.

Precisely. I always read "hires" as the verb hires (as in "he hires a car to go on holiday") rather than HIgh RESolution. -1 on hires, it's a horrible name. And misleading as well, because on Linux, it isn't any more high res than time.time(). +1 on Nick's suggestion of try_monotonic. It is clear and obvious and doesn't mislead. I don't have an opinion as to what the implementation of try_monotonic should be. Whether it should fall back to time.time, time.clock, or something else, I don't know. But it is a clear and obvious solution for the use-case of "I prefer the monotonic clock, if it is available, otherwise I'll take my chances with a best-effect clock." -- Steven

On 03/28/2012 01:56 PM, R. David Murray wrote:

On Wed, 28 Mar 2012 23:05:59 +1100, Steven D'Aprano wrote:

...

+1 on Nick's suggestion of try_monotonic. It is clear and obvious and doesn't mislead. How about "monotonicest".

(No, this is not really a serious suggestion.)

"monotonish". Thus honoring the Principle Of Least Monotonishment, //arry/

No, that would be time.monotonous(). This is time.monotonic(), the function that can only play a single note at a time. Uh, I mean time.monophonic(). Hmm, this is harder than it looks. On 28 March 2012 14:48, Matt Joiner wrote:

time.monotonic(): The uneventful and colorless function. On Mar 28, 2012 9:30 PM, "Larry Hastings" wrote:

...

On 03/28/2012 01:56 PM, R. David Murray wrote:

...

On Wed, 28 Mar 2012 23:05:59 +1100, Steven D'Aprano wrote:

...

+1 on Nick's suggestion of try_monotonic. It is clear and obvious and doesn't mislead.

How about "monotonicest".

(No, this is not really a serious suggestion.)

"monotonish".

Thus honoring the Principle Of Least Monotonishment,

//arry/ ______________________________**_________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/**mailman/listinfo/python-devhttp://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/**mailman/options/python-dev/** anacrolix%40gmail.comhttp://mail.python.org/mailman/options/python-dev/anacrolix%40gmail.com

_______________________________________________ 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/me%40jonathanfrench.net

On Wed, Mar 28, 2012 at 8:56 PM, Victor Stinner wrote:

...

...

...

In that case, I don't think time.try_monotonic() is really needed because we can emulate "time.monotonic()" in software if the platform is deficient.

As I wrote, I don't think that Python should workaround OS bugs. If the OS monotonic clock is not monotonic, the OS should be fixed.

I sympathize with this, but if the idea is that the Python stdlib should use time.monotonic() for scheduling, then it needs to always be available. Otherwise, we are not going to use it ourselves, and what sort of example is that to set?

There is time.hires() if you need a monotonic clock with a fallback to the system clock.

Completely unintuitive and unnecessary. With the GIL taking care of synchronisation issues, we can easily coerce time.time() into being a monotonic clock by the simple expedient of saving the last returned value: def _make_monotic: try: # Use underlying system monotonic clock if we can return _monotonic except NameError: _tick = time() def monotic(): _new_tick = time() if _new_tick > _tick: _tick = _new_tick return _tick monotonic = _make_monotonic() Monotonicity of the result is thus ensured, even when using time.time() as a fallback. If using the system monotonic clock to get greater precision is acceptable for an application, then forcing monotonicity shouldn't be a problem either. Regards, Nick. -- Nick Coghlan   |   ncoghlan@gmail.com   |   Brisbane, Australia

On Wed, Mar 28, 2012 at 7:17 AM, Nick Coghlan wrote:

On Wed, Mar 28, 2012 at 8:56 PM, Victor Stinner wrote:

...

...

...

...

In that case, I don't think time.try_monotonic() is really needed because we can emulate "time.monotonic()" in software if the platform is deficient.

As I wrote, I don't think that Python should workaround OS bugs. If the OS monotonic clock is not monotonic, the OS should be fixed.

I sympathize with this, but if the idea is that the Python stdlib should use time.monotonic() for scheduling, then it needs to always be available. Otherwise, we are not going to use it ourselves, and what sort of example is that to set?

There is time.hires() if you need a monotonic clock with a fallback to the system clock.

Completely unintuitive and unnecessary. With the GIL taking care of synchronisation issues, we can easily coerce time.time() into being a monotonic clock by the simple expedient of saving the last returned value:

 def _make_monotic:      try:          # Use underlying system monotonic clock if we can          return _monotonic      except NameError:          _tick = time()          def monotic():              _new_tick = time()              if _new_tick > _tick:                  _tick = _new_tick              return _tick

 monotonic = _make_monotonic()

Monotonicity of the result is thus ensured, even when using time.time() as a fallback.

If using the system monotonic clock to get greater precision is acceptable for an application, then forcing monotonicity shouldn't be a problem either.

That's a pretty obvious trick. But why don't the kernels do this if monotonicity is so important? I'm sure there are also downsides, e.g. if the clock is accidentally set forward by an hour and then back again, you wouldn't have a useful clock for an hour. And the cache is not shared between processes so different processes wouldn't see the same clock value (I presume that most of these clocks have state in the kernel that isn't bound to any particular process -- AFAIK only clock() does that, and only on Unixy systems). -- --Guido van Rossum (python.org/~guido)

On Wed, Mar 28, 2012 at 7:36 AM, Nick Coghlan wrote:

On Wed, Mar 28, 2012 at 6:40 PM, Victor Stinner wrote:

...

...

If we're simplifying the idea to only promising a monotonic clock (i.e. will never go backwards within a given process, but may produce the same value for an indefinite period, and may jump forwards by arbitrarily large amounts),

I don't know any monotonic clock jumping "forwards by arbitrarily large amounts". Linux can change CLOCK_MONOTONIC speed, but NTP doesn't "jump".

If I understood Glyph's explanation correctly, then if your application is running in a VM and the VM is getting its clock data from the underlying hypervisor, then suspending and resuming the VM may result in forward jumping of the monotonic clocks in the guest OS. I believe suspending and hibernating may cause similar problems for even a non-virtualised OS that is getting its time data from a real-time clock chip that keeps running even when the main CPU goes to sleep. (If I *misunderstood* Glyph's explanation, then he may have only been talking about the latter case)

Monotonicity is fairly easy to guarantee - you just remember the last value you returned and ensure you never return a lower value than that for the lifetime of the process. The only complication is thread synchronisation, and the GIL (or a dedicated lock for Jython/IronPython) can deal with that. Steadiness, on the other hand, requires a real world time reference and is thus really the domain of specialised hardware like atomic clocks and GPS units rather than software that can be suspended and resumed later without changing its internal state. There's a reason comms station operators pay substantial chunks of money for time & frequency reference devices [1].

This is why I now think we only need one new clock function: time.monotonic(). It will be the system monotonic clock if one is available, otherwise it will be our own equivalent wrapper around time.time() that just caches the last value returned to ensure the result never goes backwards.

As I said, I think the caching idea is bad. We may have to settle for semantics that are less than perfect -- presumably if you are doing benchmarking you just have to throw away a bad result that happened to be affected by a clock anomaly, and if you are using timeouts, retries are already part of life.

With time.monotonic() guaranteed to always be available, there's no need for a separate function that falls back to an unconditioned time.time() result.

I would love to have only one new clock function in 3.3.

Regards, Nick.

[1] For example: http://www.symmetricom.com/products/gps-solutions/gps-time-frequency-receive...

-- --Guido van Rossum (python.org/~guido)

On 2012-03-28, at 10:36 AM, Nick Coghlan wrote:

Monotonicity is fairly easy to guarantee - you just remember the last value you returned and ensure you never return a lower value than that for the lifetime of the process.

As I said in my previous mail - I don't think we should ever do that. Time may jump back and forth, and with your approach it will result in monotonic() being completely unusable. If time jumps back for N minutes, or years, that leads to completely broken expectations for timeouts for N minutes or years correspondingly (and that's just the timeouts case, I'm sure that there are much more critical time-related use-cases.) If monotonic() will utilize such hack, you add nothing usable in stdlib. Every serious framework or library will have to re-implement it using only OS-level functions, and *FAIL* if the OS doesn't support monotonic time. Fail, because such framework can't guarantee that it will work correctly. So I think time module should have only one new function: monotonic(), and this function should be only available if OS provides the underlying functionality. No need for steady(), try_monotonic() and other hacks. Each module can decide if its dependancy on monotonic is critical or not, and if it is not, you can always have: try: from time import monotonic as _time except ImportError: from time import time as _time That's how lots of code is written these days, like using 'epoll' if available, and fallback to 'select' if not. Why don't you try to abstract differences between them in the standard library? So I see no point in adding some loose abstractions to the stdlib now. - Yury

On Thu, Mar 29, 2012 at 12:42 AM, Guido van Rossum wrote:

As I said, I think the caching idea is bad. We may have to settle for semantics that are less than perfect -- presumably if you are doing benchmarking you just have to throw away a bad result that happened to be affected by a clock anomaly, and if you are using timeouts, retries are already part of life.

I agree caching doesn't solve the problems that are solved by an OS level monotonic clock, but falling back to an unmodifided time.time() result instead doesn't solve those problems either. Falling back to time.time() just gives you the status quo: time may jump forwards or backwards by an arbitrary amount between any two calls. Cached monotonicity just changes the anomalous modes to be time jumping forwards, or time standing still for an extended period of time. The only thing the caching provides is that it becomes a reasonable fallback for a function called time.monotonic() - it *is* a monotonic clock that meets the formal contract of the function, it's just nowhere near as good or effective as one the OS can provide. Forward jumping anomalies aren't as harmful, are very hard to detect in the first place and behave the same regardless of the presence of caching, so the interesting case to look at is the difference in failure modes when the system clock jumps backwards. For benchmarking, a caching clock will produce a zero result instead of a negative result. Zeros aren't quite as obviously broken as negative numbers when benchmarking, but they're still sufficiently suspicious that most benchmarking activities will flag them as anomalous. If the jump back was sufficiently small that the subsequent call still produces a higher value than the original call, then behaviour reverts to being identical. For timeouts, setting the clock back means your operation will take longer to time out than you expected. This problem will occur regardless of whether you were using cached monotonicity (such that time stands still) or the system clock (such that time actually goes backwards). In either case, your deadline will never be reached until the backwards jump has been cancelled out by the subsequent passage of time. I want the standard library to be able to replace its time.time() calls with time.monotonic(). The only way we can do that without breaking cross-platform compatibility is if time.monotonic() is guaranteed to exist, even when the platform only provides time.time(). A dumb caching fallback implementation based on time.time() is the easiest way to achieve that withou making a complete mockery of the "monotonic()" name. There is then a *different* use case, which is 3.3+ only code which wants to fail noisily when there's no OS level monotonic support - the application developer really does want to fail *immediately* if there's no OS level monotonic clock available, instead of crossing your fingers and hoping you don't hit a clock adjustment glitch (crossing your fingers has, I'll point out, been the *only* option for all previous versions of Python, so it clearly can't be *that* scary a prospect). So, rather than making time.monotonic() something that the *standard library can't use*, I'd prefer to address that second use case by exposing the OS level monotonic clock as time.os_monotonic() only when it's available. That way, the natural transition for old time.time() based code is to time.monotonic() (with no cross-platform support implications), but time.os_monotonic() also becomes available for the stricter use cases. Regards, Nick. -- Nick Coghlan   |   ncoghlan@gmail.com   |   Brisbane, Australia

On Wed, Mar 28, 2012 at 8:08 AM, Nick Coghlan wrote:

On Thu, Mar 29, 2012 at 12:42 AM, Guido van Rossum wrote:

...

As I said, I think the caching idea is bad. We may have to settle for semantics that are less than perfect -- presumably if you are doing benchmarking you just have to throw away a bad result that happened to be affected by a clock anomaly, and if you are using timeouts, retries are already part of life.

I agree caching doesn't solve the problems that are solved by an OS level monotonic clock, but falling back to an unmodifided time.time() result instead doesn't solve those problems either. Falling back to time.time() just gives you the status quo: time may jump forwards or backwards by an arbitrary amount between any two calls. Cached monotonicity just changes the anomalous modes to be time jumping forwards, or time standing still for an extended period of time. The only thing the caching provides is that it becomes a reasonable fallback for a function called time.monotonic() - it *is* a monotonic clock that meets the formal contract of the function, it's just nowhere near as good or effective as one the OS can provide.

TBH, I don't think like this focus on monotonicity as the most important feature.

Forward jumping anomalies aren't as harmful, are very hard to detect in the first place and behave the same regardless of the presence of caching, so the interesting case to look at is the difference in failure modes when the system clock jumps backwards.

Agreed.

For benchmarking, a caching clock will produce a zero result instead of a negative result. Zeros aren't quite as obviously broken as negative numbers when benchmarking, but they're still sufficiently suspicious that most benchmarking activities will flag them as anomalous. If the jump back was sufficiently small that the subsequent call still produces a higher value than the original call, then behaviour reverts to being identical.

So for benchmarking we don't care about jumps, really, and the caching version is slightly less useful.

For timeouts, setting the clock back means your operation will take longer to time out than you expected. This problem will occur regardless of whether you were using cached monotonicity (such that time stands still) or the system clock (such that time actually goes backwards). In either case, your deadline will never be reached until the backwards jump has been cancelled out by the subsequent passage of time.

Where in the stdlib do we actually calculate timeouts instead of using the timeouts built into the OS (e.g. select())? I think it would be nice if we could somehow use the *same* clock as the OS uses to implement timeouts.

I want the standard library to be able to replace its time.time() calls with time.monotonic().

Where in the stdlib? (I'm aware of threading.py. Any other places?)

The only way we can do that without breaking cross-platform compatibility is if time.monotonic() is guaranteed to exist, even when the platform only provides time.time(). A dumb caching fallback implementation based on time.time() is the easiest way to achieve that withou making a complete mockery of the "monotonic()" name.

Yeah, so maybe it's a bad name. :-)

There is then a *different* use case, which is 3.3+ only code which wants to fail noisily when there's no OS level monotonic support - the application developer really does want to fail *immediately* if there's no OS level monotonic clock available, instead of crossing your fingers and hoping you don't hit a clock adjustment glitch (crossing your fingers has, I'll point out, been the *only* option for all previous versions of Python, so it clearly can't be *that* scary a prospect).

So, rather than making time.monotonic() something that the *standard library can't use*, I'd prefer to address that second use case by exposing the OS level monotonic clock as time.os_monotonic() only when it's available. That way, the natural transition for old time.time() based code is to time.monotonic() (with no cross-platform support implications), but time.os_monotonic() also becomes available for the stricter use cases.

I'd be happier if the fallback function didn't try to guarantee things the underlying clock can't guarantee. I.e. I like the idea of having a function that uses some accurate OS clock if one exists but falls back to time.time() if not; I don't like the idea of that new function trying to interpret the value of time.time() in any way. Applications that need the OS clock's guarantees can call it directly. We could also offer something where you can introspect the properties of the clock (or clocks) so that an app can choose the best clock depending on its needs. To summarize my problem with the caching idea: take a simple timeout loop such as found in several places in threading.py. def wait_for(delta, eps): # Wait for delta seconds, sleeping eps seconds at a time deadline = now() + delta while now() < deadline: sleep(eps) If the now() clock jumps backward after the initial call, we end up waiting too long -- until either the clock jumps forward again or until we've made up the difference. If the now() clock jumps forward after the initial call, we end up waiting less time, which is probably not such a big problem (though it might). But now consider a caching clock, and consider that the system clock made a jump backwards *before* this function is called. The cache prevents us from seeing it, so the initial call to now() returns the highest clock value seen so far. And until the system clock has caught up with that, now() will return the same value over and over -- so WE STILL WAIT TOO LONG. My conclusion: you can't win this game by forcing the clock to return a monotonic value. A better approach might be to compute how many sleep(eps) calls we're expected to make, and to limit the loop to that -- although sleep() doesn't make any guarantees either about sleeping too short or too long. Basically, if you do sleep(1) and find that your clock didn't move (enough), you can't tell the difference between a short sleep and a clock that jumped back. And if your clock moved to much, you still don't know if the problem was with sleep() or with your clock. -- --Guido van Rossum (python.org/~guido)

On Thu, Mar 29, 2012 at 1:47 AM, Guido van Rossum wrote:

Where in the stdlib? (I'm aware of threading.py. Any other places?)

Victor had at least one other example. multiprocessing, maybe? I believe the test suite may still have a few instances as well.

But now consider a caching clock, and consider that the system clock made a jump backwards *before* this function is called. The cache prevents us from seeing it, so the initial call to now() returns the highest clock value seen so far. And until the system clock has caught up with that, now() will return the same value over and over -- so WE STILL WAIT TOO  LONG.

Ouch. OK, I'm convinced the caching fallback is worse than just falling back to time.time() directly, which means the naming problem needs to be handled another way.

My conclusion: you can't win this game by forcing the clock to return a monotonic value. A better approach might be to compute how many sleep(eps) calls we're expected to make, and to limit the loop to that -- although sleep() doesn't make any guarantees either about sleeping too short or too long. Basically, if you do sleep(1) and find that your clock didn't move (enough), you can't tell the difference between a short sleep and a clock that jumped back. And if your clock moved to much, you still don't know if the problem was with sleep() or with your clock.

With your point about the problem with the naive caching mechanism acknowledged, I think we can safely assign time.monotonic() as the name of the OS provided monotonic clock. That means choosing a name for the version that falls back to time() if monotonic() isn't available so it can be safely substituted for time.time() without having to worry about platform compatibility implications. I don't like Victor's current "hires" (because it doesn't hint at the fallback behaviour, may actually be the same res as time.time() and reads like an unrelated English word). My own suggestion of "try_monotic()" would get the job done, but is hardly going to win any API beauty contests. Cheers, Nick. -- Nick Coghlan   |   ncoghlan@gmail.com   |   Brisbane, Australia

On Thu, Mar 29, 2012 at 1:14 AM, Nick Coghlan wrote:

That means choosing a name for the version that falls back to time() if monotonic() isn't available so it can be safely substituted for time.time() without having to worry about platform compatibility implications.

What's wrong with "time.time()" again? As documented in http://docs.python.org/py3k/library/time.html it makes no guarantees, and specifically there is *no* guarantee that it will ever behave *badly*<wink/>. Of course, we'll have to guarantee that, if a badly-behaved clock is available, users can get access to it, so call that time._time().

On Wed, Mar 28, 2012 at 12:56, Victor Stinner wrote:

There is time.hires() if you need a monotonic clock with a fallback to the system clock.

Does this primarily give a high resolution clock, or primarily a monotonic clock? That's not clear from either the name, or the PEP. //Lennart

On 2012-03-28, at 11:35 AM, Nick Coghlan wrote:

So, the primary use case is that we want to replace many of the time.time() calls in the standard library with time.monotonic() calls. To avoid backwards compatibility problems in the cross-platform support, that means time.monotonic() *must be available on every platform that currently provides time.time()*.

OK. I got your point. And also I've just realized what I dislike about the way you want to implement the fallback. The main problem is that I treat the situation when time jumps backward as an exception, because, again, if you have timeouts you may get those timeouts to never be executed. So let's make the "try_monotonic()" function (or whatever name will be chosen) this way (your original code edited): def _make_monotic(): try: # Use underlying system monotonic clock if we can return _monotonic except NameError: _tick = time() def monotic(): nonlocal _time _new_tick = time() if _new_tick <= _tick: raise RuntimeError('time was adjusted backward') _tick = _new_tick return _new_tick return monotonic try_monotonic = _make_monotonic() At least this approach tries to follow some of the python's zen. - Yury

I would love to have only one new clock function in 3.3.

I already added time.clock_gettime() to 3.3 :-) Victor

Does this primarily give a high resolution clock, or primarily a monotonic clock? That's not clear from either the name, or the PEP.

I expect a better resolution from time.monotonic() than time.time(). I don't have exact numbers right now, but I began to document each OS clock in the PEP. Victor

On Wed, Mar 28, 2012 at 2:36 PM, Scott Dial wrote:

On 3/28/2012 10:29 AM, Guido van Rossum wrote:

...

On Wed, Mar 28, 2012 at 7:17 AM, Nick Coghlan wrote:

...

Completely unintuitive and unnecessary. With the GIL taking care of synchronisation issues, we can easily coerce time.time() into being a monotonic clock by the simple expedient of saving the last returned value:

That's a pretty obvious trick. But why don't the kernels do this if monotonicity is so important? I'm sure there are also downsides, e.g. if the clock is accidentally set forward by an hour and then back again, you wouldn't have a useful clock for an hour. And the cache is not shared between processes so different processes wouldn't see the same clock value (I presume that most of these clocks have state in the kernel that isn't bound to any particular process -- AFAIK only clock() does that, and only on Unixy systems).

What makes you think that isn't already true?

What does "that" refer to in this sentence?

I don't know what platforms that CPython compiles for that *won't* have one of the aforementioned functions available that provide a *real* monotonic clock. Surely, any platform that doesn't didn't recognize the need for it, or they would just provide a monotonic clock. That is to say, if you are a POSIX compliant system, then there is no reason to break gettimeofday() and friends when you can just implement CLOCK_MONOTONIC proper (even if it's just a trick like Nick's).

I think the PEP should enumerate what platforms that CPython supports that will not benefit from a real monotonic clock. I think the number of platforms will be such a minority that the emulation makes sense. Practicality beats purity, and all.

-- Scott Dial scott@scottdial.com

-- --Guido van Rossum (python.org/~guido)

Could you (with help from others who contributed) try to compile a table showing, for each platform (Windows/Mac/Linux/BSD) which clocks (or variations) we are considering, and for each of those:

- a link for the reference documentation - what their typical accuracy is (barring jumps) - what they do when the "civil" time is made to jump (forward or back) by the user - how they are affected by small tweaks to the civil time by NTP - what they do if the system is suspended and resumed - whether they can be shared between processes running on the same machine - whether they may fail or be unsupported under some circumstances

I have a feeling that if I saw such a table it would be much easier to decide.

I assume much of this has already been said at one point in this thread, but it's impossible to have an overview at the moment.

I don't know where I can get all these information, but I'm completing the PEP each time that I find a new information. It's difficult to get the accuracy of a clock and how it handles system suspend. I'm intereted if anyone has such information. Victor

The overview of the different monotonic clocks was interesting, because only one of them is adjusted by NTP, and that's the unix CLOCK_MONOTONIC. Hence we don't need a raw=False flag, which I previously suggested, we only need to not use CLOCK_MONOTONIC (which the PEP psuedo-code indeed also does not do, so that's all good). That means I think the PEP is fine now, if we rename highres(). time.time() already gets the highest resolution clock it can. Hence a highres() is confusing as the name implies that it returns a higher resolution clock than time.time(). And the name does not in any way indicate that the returned clock might be monotonic. try_monotonic() seems the obvious choice, since that's what it actually does. //Lennart

On Fri, 30 Mar 2012 12:40:25 -0700, Guido van Rossum wrote:

But for the other, I'm still at a loss, and that name is the most important one. We can't call it steady because it isn't always. highres or hires sounds awkward; try_monotonic or try_steady are even more awkward. I looked in an online thesaurus and here's a list of what it gave:

Big Ben, alarm, chroniker, chronograph, chronometer, digital watch, hourglass, metronome, pendulum, stopwatch, sundial, tattler, tick-tock, ticker, timekeeper, timemarker, timepiece, timer, turnip, watch

I wonder if something with tick would work? (Even though it returns a float. :-)

If all else fails, I'd go with turnip.

We could call it "alice"[*]: sometimes it goes fast, sometimes it goes slow, sometimes it even goes backward, but it does try to tell you when you are late. --David [*] 'whiterabbit' would be more descriptive, but that's longer than turnip.

Guido van Rossum wrote:

But for the other, I'm still at a loss, and that name is the most important one. We can't call it steady because it isn't always. highres or hires sounds awkward; try_monotonic or try_steady are even more awkward. I looked in an online thesaurus and here's a list of what it gave:

"hires" is a real English word, the present tense verb for engaging the service or labour of someone or something in return for payment, as in "he hires a gardener to mow the lawn". Can we please eliminate it from consideration? It is driving me slowly crazy every time I see it used as an abbreviation for high resolution.

Big Ben, alarm, chroniker, chronograph, chronometer, digital watch, hourglass, metronome, pendulum, stopwatch, sundial, tattler, tick-tock, ticker, timekeeper, timemarker, timepiece, timer, turnip, watch

I wonder if something with tick would work? (Even though it returns a float. :-)

If all else fails, I'd go with turnip.

I can't tell if you are being serious or not. For the record, "turnip" in this sense is archaic slang for a thick pocket watch. -- Steven

On Sat, Mar 31, 2012 at 02:26, Steven D'Aprano wrote:

Guido van Rossum wrote:

...

If all else fails, I'd go with turnip.

I can't tell if you are being serious or not.

For the record, "turnip" in this sense is archaic slang for a thick pocket watch.

If I understand this correctly, the most common use for this function is when to time things. It will give you the best source available for timers, but it doesn't guarantee that it is steady or monotonic or high resolution or anything. It is also not the time, as it's not reliable as a wall-clock. So, how about time.timer()? //Lennart

On Sat, Mar 31, 2012 at 11:50, Nadeem Vawda wrote:

Out of the big synonym list Guido posted, I rather like time.stopwatch() - it makes it more explicit that the purpose of the function is to measure intervals, rather identifying absolute points in time.

I guess it's the least bad. //Lennart

I've just finished sketching out a skeleton here:

 https://bitbucket.org/cameron_simpson/css/src/fb476fcdcfce/lib/python/cs/clo...

get_clock() returns None if no clock has the requested flags, whereas I expected an exception (LookupError or NotImplementError?). get_clock() doesn't remember if a clock works or not (if it raises an OSError) and does not fallback to the next clock on error. See "pseudo-codes" in the PEP 418. The idea of flags attached to each clock is interesting, but I don't like the need of different list of clocks. Should I use MONTONIC_CLOCKS or HIRES_CLOCKS when I would like a monotonic and high-resolution clock? It would be simpler to have only one global and *private* list. If you have only one list of clocks, how do sort the list to get QueryPerformanceCounter when the user asks for highres and GetTickCount when the user asks for monotonic? The "if clock.flags & flags == flags:" test in get_clock() is maybe not enough. I suppose that we would have the following flags for Windows functions: QueryPerformanceCounter.flags = T_HIRES GetTickCount.flags = T_MONOTONIC | T_STEADY (or maybe QueryPerformanceCounter.flags = T_HIRES | T_MONOTONIC ?) monotonic_clock() should maybe try to get a clock using the following list of conditions: - T_MONOTONIC | T_STEADY - T_MONOTONIC | T_HIGHRES - T_MONOTONIC The T_HIGHRES flag in unclear, even in the PEP. According to the PEP, any monotonic clock is considered as a "high-resolution" clock. Do you agree? So we would have: GetTickCount.flags = T_MONOTONIC | T_STEADY | T_HIGHRES Even if GetTickCount has only an accuracy of 15 ms :-/ Can list please give the list of flags of each clocks listed in the PEP? Only clocks used for time.time, time.monotonic and time.highres (not process and thread clocks nor QueryUnbiasedInterruptTime).

     # get a clock object - often a singleton under the hood      T = get_clock(T_MONOTONIC|T_HIRES) or get_clock(T_STEADY|T_HIRES)      # what kind of clock did I get?      print T.flags      # get the current time      now = T.now

The API looks much more complex than the API proposed in PEP 418 just to get the time. You have to call a function to get a function, and then call the function, instead of just calling a function directly. Instead of returning an object with a now() method, I would prefer to get directly the function getting time, and another function to get "metadata" of the clock.

This removes policy from the library functions and makes it both simple and obvious in the user's calling code, and also makes it possible for the user to inspect the clock and find out what quality/flavour of clock they got.

I'm not sure that users understand correctly differences between all these clocks and are able to use your API correctly. How should I combinese these 3 flags (T_HIRES, T_MONOTONIC and T_STEADY)? Can I use any combinaison? Which flags are "portable"? Or should I always use an explicit fallback to ensure getting a clock on any platform? Could you please update your code according to my remarks? I will try to integrate it into the PEP. A PEP should list all alternatives! Victor

On 02Apr2012 13:37, Victor Stinner wrote: | > I've just finished sketching out a skeleton here: | >  https://bitbucket.org/cameron_simpson/css/src/fb476fcdcfce/lib/python/cs/clo... | | get_clock() returns None if no clock has the requested flags, whereas | I expected an exception (LookupError or NotImplementError?). That is deliberate. People can easily write fallback like this: clock = get_clock(T_MONOTONIC|T_HIRES) or get_clock(T_MONOTONIC) With exceptions one gets a complicated try/except/else chain that is much harder to read. With a second fallback the try/except gets even worse. If one wants an exception it is easy to follow up with: if not clock: raise RunTimeError("no suitable clocks on offer on this platform") | get_clock() doesn't remember if a clock works or not (if it raises an | OSError) and does not fallback to the next clock on error. See | "pseudo-codes" in the PEP 418. I presume the available clocks are all deduced from the platform. Your pseudo code checks for OSError at fetch-the-clock time. I expect that to occur once when the module is loaded, purely to populate the table of avaiable platform clocks. If you are concerned about clocks being available/unavailable at different times (unplugging the GPS peripheral? just guessing here) that will have to raise OSError during the now() call (assuming the clock even exposes the failure; IMO it should when now() is called). | The idea of flags attached to each clock is interesting, but I don't | like the need of different list of clocks. There's no need, just quality of implementation for the monotonic()/hires() convenience calls, which express the (hoped to be common) policy of what clock to offer for each. We've just had pages upon pages of discussion about what clock to offer for the rather bald monotonic() (et al) calls. The ordering of the MONTONIC_CLOCKS list would express the result of that discussion, in that the "better" clocks come first. | Should I use | MONTONIC_CLOCKS or HIRES_CLOCKS when I would like a monotonic and | high-resolution clock? Note that you don't need to provide a clock list at all; get_clock(0 will use ALL_CLOCKS by default, and hires() and monotonic() should each have their own default list. I'll put in montonic() and montonic_clock(clocklist=MONOTONIC_CLOCKS) into the skeleton to make this clear; I see I've omitted them. Regarding the choice itself: as the _caller_ (not the library author), you must decide what you want most. You're already planning offering monotonic() and hires() calls without my proposal! Taking your query "Should I use MONTONIC_CLOCKS or HIRES_CLOCKS when I would like a monotonic and high-resolution clock" is _already_ a problem. Of course you must call monotonic() or hires() first under the current scheme, and must answer this question anyway. Do you prefer hires? Use it first! No preference? Then the question does not matter. If I, as the caller, have a preference then it is obvious what to use. If I do not have a preference then I can just call get_clock() with both flags and then arbitrarily fall back to hires() or monotonic() if that does not work. | It would be simpler to have only one global and | *private* list. No. No no no no no! The whole point is to let the user be _able_ to control the choices to a fair degree without platform special knowledge. The lists are deliberately _optional_ parameters and anyway hidden in the hires() and monotonic() convenince functions; the user does not need to care about them. But the picky user may! The lists align exactly one to one with the feature flags, so there is no special knowledge present here that is not already implicit in publishing the feature flags. | If you have only one list of clocks, how do sort the list to get | QueryPerformanceCounter when the user asks for highres and | GetTickCount when the user asks for monotonic? This is exactly why there are supposed to be different lists. You have just argued against your objection above. | The "if clock.flags & | flags == flags:" test in get_clock() is maybe not enough. I suppose | that we would have the following flags for Windows functions: | | QueryPerformanceCounter.flags = T_HIRES | GetTickCount.flags = T_MONOTONIC | T_STEADY | | (or maybe QueryPerformanceCounter.flags = T_HIRES | T_MONOTONIC ?) Obviously these depend on the clock characteristics. Is QueryPerformanceCounter monotonic? | monotonic_clock() should maybe try to get a clock using the following | list of conditions: | - T_MONOTONIC | T_STEADY | - T_MONOTONIC | T_HIGHRES | - T_MONOTONIC Sure, seems reasonable. That is library internal policy _for the convenince monotonic() function()_. | The T_HIGHRES flag in unclear, even in the PEP. According to the PEP, | any monotonic clock is considered as a "high-resolution" clock. Do you | agree? Not particularly. I easily can imagine a clock with one second resolution hich was monotonic. I would not expect it to have the T_HIRES flag. Example: a synthetic monotonic clock based on a V7 UNIX time() call. But, if it _happens_ that all the monotonic clocks are also hires, so be it. That would be an empirical outcome, not policy. | So we would have: | | GetTickCount.flags = T_MONOTONIC | T_STEADY | T_HIGHRES | | Even if GetTickCount has only an accuracy of 15 ms :-/ T_HIGHRES is a quality call, surely? If 15ms is too sloppy for a "high resolution, the is should _not_ have the T_HIRES flag. | Can list please give the list of flags of each clocks listed in the | PEP? Only clocks used for time.time, time.monotonic and time.highres | (not process and thread clocks nor QueryUnbiasedInterruptTime). | | >      # get a clock object - often a singleton under the hood | >      T = get_clock(T_MONOTONIC|T_HIRES) or get_clock(T_STEADY|T_HIRES) | >      # what kind of clock did I get? | >      print T.flags | >      # get the current time | >      now = T.now | | The API looks much more complex than the API proposed in PEP 418 just | to get the time. You have to call a function to get a function, and | then call the function, instead of just calling a function directly. One could have a flat interface as in the PEP, but then the results are not inspectable; the user cannot find out what specific clock, or even kind of clock, was used for the result returned. Unless you want to subclass float for the return values. You could return instances of a float with meta information pointing at the clock used to provide it. I'm -0.5 on that idea. Another advantage of returning a clock object is that it avoids the difficulty of switching implementations behind the user's back, an issue raised in the discussion and rightly rejected as a bad occurence. If the user is handed a clock object, _they_ keep the "current clock in use" state by by having the object reference. | Instead of returning an object with a now() method, I would prefer to | get directly the function getting time, and another function to get | "metadata" of the clock. Then they're disconnected. How do I know the get-metadata call accesses the clock I just used? Only by having library internal global state. I agree some people probably want the flat "get me the time" call, and have no real objection to such existing. But I strongly object to not giving the user control over what they use, and the current API offers no control. | > This removes policy from the library functions and makes it both simple | > and obvious in the user's calling code, and also makes it possible for | > the user to inspect the clock and find out what quality/flavour of clock | > they got. | | I'm not sure that users understand correctly differences between all | these clocks and are able to use your API correctly. How should I | combinese these 3 flags (T_HIRES, T_MONOTONIC and T_STEADY)? Can I use | any combinaison? Of course. Just as with web searches, too many flags may get you an empty result on some platforms, hence the need to fall back. But the _nature_ of the fallback should be in the user's hands. The hires() et al calls can of course offer convenient presupplied fallback according to the preconceptions of the library authors, hopefully well tuned to common users' needs. But if should not be the only mode offered, because you don't know the user's needs. | Which flags are "portable"? Or should I always use an explicit | fallback to ensure getting a clock on any platform? All the flag are portable, but if the platform doesn't supply a clock with the requested flags, even if there's only one flag, the correct result is "None" for the clock offered. Note you can supply no flags! You can always fall all the way back to 0 for the flags; in the skeleton provided that will get you UNIXClock, which is a wrapper for the existing time.time(). In fact, I'll make the flags parameter also optional for get_clock(), defaulting to 0, to make that easy. That becomes your totally portable call:-) | Could you please update your code according to my remarks? I will try | to integrate it into the PEP. A PEP should list all alternatives! Surely. The only updates I can see are to provide the flat interface (instead of via clock-object indirection) and the missing hires_clock() and monotonic_clock() convenience methods. I'll do that. Followup post shortly with new code URL. Would you propose other specific additions? Cheers, -- Cameron Simpson DoD#743 http://www.cskk.ezoshosting.com/cs/ Whatever is not nailed down is mine. What I can pry loose is not nailed down. - Collis P. Huntingdon

On 03Apr2012 07:38, I wrote: | On 02Apr2012 13:37, Victor Stinner wrote: | | Could you please update your code according to my remarks? I will try | | to integrate it into the PEP. A PEP should list all alternatives! New code here: https://bitbucket.org/cameron_simpson/css/src/91848af8663b/lib/python/cs/clo... Diff: https://bitbucket.org/cameron_simpson/css/changeset/91848af8663b Changelog: updates based on suggestions from Victor Stinner: "flat" API calls to get time directly, make now() a method instead of a property, default flags for get_clock(), adjust hr_clock() to hires_clock(0 for consistency. Cheers, -- Cameron Simpson DoD#743 http://www.cskk.ezoshosting.com/cs/ Q: How does a hacker fix a function which doesn't work for all of the elements in its domain? A: He changes the domain. - Rich Wareham

On 02Apr2012 10:44, Glenn Linderman wrote: | On 4/2/2012 4:37 AM, Victor Stinner wrote: | > The API looks much more complex than the API proposed in PEP 418 just | > to get the time. You have to call a function to get a function, and | > then call the function, instead of just calling a function directly. | > | > Instead of returning an object with a now() method, I would prefer to | > get directly the function getting time, and another function to get | > "metadata" of the clock. | | If there are more than two clocks, with different characteristics, no | API is going to be both simple to use and fast to call. | | If there are more than two clocks, with different characteristics, then | having an API to get the right API to call to get a time seems very | natural to me. It is, though Victor's point about offering the very easy to use API is valid. The new code has the "flat" monotonic() et al calls as well. | One thing I don't like about the idea of fallback being buried under | some API is that the efficiency of that API on each call must be less | than the efficiency of directly calling an API to get a single clock's | time. For frequently called high resolution clocks, this is more | burdensome than infrequently called clocks.... yet those seem to be the | ones for which fallbacks are proposed, because of potential unavailability. I hadn't thought about that, but it isn't actually a big deal. The overhead isn't zero, but in order to always use the _same_ clock to return hires() (for example) the library has to cache the clock lookup anyway. Current clockutils.py skeleton here: https://bitbucket.org/cameron_simpson/css/src/91848af8663b/lib/python/cs/clo... does so. | The only thing I'm not so sure about: can the properties be described by | flags? Might it not be better to have an API that allows specification | of minimum resolution, in terms of fractional seconds? Perhaps other | properties suffice as flags, but perhaps not resolution. It sounds nice, but there are some difficulties. Firstly, the (currently just 3) flags were chosen to map to the three features sought (in various cobinations) for clocks. Once you start requesting precision (a totally reasonable desire, BTW) you also want to request degree of slew (since "steady" is a tunabe term) and so forth. And what for clocks that have variable precision (I'm imaging here a clock which really is a float, and for large times (in the far future) can't return the sane resolution because of the size of a float. The concern is valid though. I could imagine beefing up the clock object metadata with .epoch (can be None!), precision (function of float width versus clock return value epislon), epsilon (your fraction of a second parameter). Of course, for some clocks any of these might be None. Then the truly concerned user iterates over the available clocks with the desired coarse flags, inspecting each closely for precision or whatever. Easy enough to tweak get_clock() to take an optional all_clocks=False parameter to return all matching clocks in an iterable instead of (the first match or None). Or the user could reach directly for one of the clock lists. cheers, -- Cameron Simpson DoD#743 http://www.cskk.ezoshosting.com/cs/ Craft, n. A fool's substitute for brains. - The Devil's Dictionary

On 03Apr2012 07:38, I wrote: | On 02Apr2012 13:37, Victor Stinner wrote: | | Should I use | | MONTONIC_CLOCKS or HIRES_CLOCKS when I would like a monotonic and | | high-resolution clock? | | Note that you don't need to provide a clock list at all; get_clock(0 | will use ALL_CLOCKS by default, and hires() and monotonic() should each | have their own default list. [...] | | It would be simpler to have only one global and | | *private* list. [...] | The whole point is to let the user be _able_ to control the choices to a | fair degree without platform special knowledge. On some reflection I may lean a little more Victor's way here: I am still very much of the opinion that there should be multiple clock lists so that hires() can offer the better hires clocks first and so forth. However, perhaps I misunderstood and he was asking if he needed to name a list to get a hires clock etc. This intent is not to need to, via the convenience functions. Accordingly, maybe the list names needn't be published, and may complicate the published interface even though they're one to one with the flags. It would certainly up the ante slightly f we added more flags some time later. (For example, I think any synthetic clocks such as the caching example in the skeleton should probably have a SYNTHETIC flag. You might never ask for it, but you should be able to check for it. (I personally suspect some of the OS clocks are themselves synthetic, but no matter...) The flip side of this of course is that if the list names are private then the get_clock() and hires() etc functions almost mandatorially need the optional all_clocks=False parameter mooted in a sibling post; the really picky user needs a way to iterate over the available clocks to make a fine grained decision. On example would be to ask for monotonic clocks but omit synthetic ones (there's a synthetic clock in the skeleton though I don't partiularly expect one in reality - that really is better in a broader "*utils" module; I also do NOT want to get into complicated parameters to say these flags but not _those_ flags and so forth for other metadata. And again, an external module offering synthetic clocks could easily want to be able to fetch the existing and augument the list with its own, then use that with the get_clock() interfaces. So in short I think: - there should be, internally at least, multiple lists for quality of returned result - there should be a way to iterate over the available clocks, probably via an all_clocks paramater instead of a public list name Cheers, -- Cameron Simpson DoD#743 http://www.cskk.ezoshosting.com/cs/ There is hopeful symbolism in the fact that flags do not wave in a vacuum. - Arthur C. Clarke

I like the aim of letting the user control what clock it get, but I find this API pretty horrible:

 clock = get_clock(T_MONOTONIC|T_HIRES) or get_clock(T_MONOTONIC)

Just my 2 groszy. //Lennart

On 03/04/2012 07:03, Cameron Simpson wrote:

On 03Apr2012 07:51, Lennart Regebro wrote: | I like the aim of letting the user control what clock it get, but I | find this API pretty horrible: | |> clock = get_clock(T_MONOTONIC|T_HIRES) or get_clock(T_MONOTONIC)

FWIW, the leading "T_" is now gone, so it would now read:

clock = get_clock(MONOTONIC|HIRES) or get_clock(MONOTONIC)

If the symbol names are not the horribleness, can you qualify what API you would like more?

I reckon the API is ok given that you don't have to supply the flags, correct? A small point but I'm with (I think) Terry Reedy and Steven D'Aprano in that hires is an English word, could you please substitute highres and HIGHRES, thanks. -- Cheers. Mark Lawrence.

On Tue, Apr 3, 2012 at 08:03, Cameron Simpson wrote:

 clock = get_clock(MONOTONIC|HIRES) or get_clock(MONOTONIC)

If the symbol names are not the horribleness, can you qualify what API you would like more?

Well, get_clock(monotonic=True, highres=True) would be a vast improvement over get_clock(MONOTONIC|HIRES). I also think it should raise an error if not found. The clarity and easy of use of the API is much more important than how much you can do in one line. //Lennart

On 03Apr2012 09:07, Ethan Furman wrote: | Lennart Regebro wrote: | > On Tue, Apr 3, 2012 at 08:03, Cameron Simpson wrote: | >> clock = get_clock(MONOTONIC|HIRES) or get_clock(MONOTONIC) | >> | >> If the symbol names are not the horribleness, can you qualify what API | >> you would like more? | > | > Well, get_clock(monotonic=True, highres=True) would be a vast | > improvement over get_clock(MONOTONIC|HIRES). | | Allowing get_clock(True, True)? Ick. My nomination would be | get_clock(MONOTONIC, HIGHRES) -- easier on the eyes with no |. get_clock already has two arguments - you can optionally hand it a clock list - that's used by monotonic_clock() and hires_clock(). Have a quick glance at: https://bitbucket.org/cameron_simpson/css/src/tip/lib/python/cs/clockutils.p... (I finally found out how to point at the latest revision on BitBucket; it's not obvious from the web interface itself.) | > I also think it should | > raise an error if not found. The clarity and easy of use of the API is | > much more important than how much you can do in one line. How much you can do _clearly_ in one line is a useful metric. | What's unclear about returning None if no clocks match? The return of None is very deliberate. I _want_ user specified fallback to be concise and easy. The example: clock = get_clock(MONOTONIC|HIRES) or get_clock(MONOTONIC) seems to satisfy both these criteria to my eye. Raising an exception makes user fallback a royal PITA, with a horrible try/except cascade needed. Exceptions are all very well when there is just one thing to do: parse this or fail, divide this by that or fail. If fact they're the very image of "do this one thing or FAIL". They are not such a good match for do this thing or that thing or this other thing. When you want a simple linear cascade of choices, Python's short circuiting "or" operator is a very useful thing. Having an obsession with exceptions is IMO unhealthy. Cheers, -- Cameron Simpson DoD#743 http://www.cskk.ezoshosting.com/cs/ Because of its special customs, crossposting between alt.peeves and normal newsgroups is discouraged. - Cameron Spitzer

On 03Apr2012 15:08, Ethan Furman wrote: | Cameron Simpson wrote: | > get_clock already has two arguments - you can optionally hand it a clock | > list - that's used by monotonic_clock() and hires_clock(). | | def get_clock(*flags, *, clocklist=None): I presume that bare "*," is a typo. Both my python2 and python3 commands reject it. [...] | wanted = 0 | for flag in flags: | wanted |= flag [...] I could do this. I think I'm -0 on it, because it doesn't seem more expressive to my eye than the straight make-a-bitmask "|" form. Other opinions? | Would need to make *flags change to the other *_clock functions. Yep. | > The return of None is very deliberate. I _want_ user specified fallback | > to be concise and easy. The example: | > clock = get_clock(MONOTONIC|HIRES) or get_clock(MONOTONIC) | | Which would become: | clock = get_clock(MONOTONIC, HIGHRES) or get_clock(MONOTONIC) | | +1 to returning None | | > Exceptions are all very well when there is just one thing to do: parse | > this or fail, divide this by that or fail. If fact they're the very | > image of "do this one thing or FAIL". They are not such a good match for do | > this thing or that thing or this other thing. Another thought that occurred in the shower was that get_clock() et al are inquiry functions, and returning None is very sensible there. monotonic() et al are direct use functions, which should raise an exception if unavailable so that code like: t0 = monotonic() ....... t1 = monotonic() does not become littered with checks for special values like None. I consider this additional reason to return None from get_clock(). Cheers, -- Cameron Simpson DoD#743 http://www.cskk.ezoshosting.com/cs/ DON'T DRINK SOAP! DILUTE DILUTE! OK! - on the label of Dr. Bronner's Castile Soap

On Wed, Apr 4, 2012 at 9:38 AM, Cameron Simpson wrote:

I could do this. I think I'm -0 on it, because it doesn't seem more expressive to my eye than the straight make-a-bitmask "|" form. Other opinions?

Yes. I've been mostly staying out of the PEP 418 clock discussion (there are enough oars in there already), but numeric flags are unnecessarily hard to debug. Use strings as your constants unless there's a compelling reason not to. Seeing "('MONOTONIC', 'HIGHRES')" in a debugger or exception message is a lot more informative than seeing "3". Regards, Nick. -- Nick Coghlan   |   ncoghlan@gmail.com   |   Brisbane, Australia

Lennart Regebro wrote:

...

Well, get_clock(monotonic=True, highres=True) would be a vast improvement over get_clock(MONOTONIC|HIRES).

I don't like this keyword API because you have to use a magically marker (True). Why True? What happens if I call get_clock(monotonic=False) or get_clock(monotonic="yes")? Victor

On 04/04/2012 01:04, Greg Ewing wrote:

Cameron Simpson wrote:

...

People have been saying "hires" throughout the threads I think, but I for one would be slightly happier with "highres".

hirez?

IMHO still too easy to read as hires. Or is it? Bah I'm going to bed and will think about it, night all. -- Cheers. Mark Lawrence.

On 04Apr2012 01:45, Victor Stinner wrote: | > | get_clock() returns None if no clock has the requested flags, whereas | > | I expected an exception (LookupError or NotImplementError?). | > | > That is deliberate. People can easily write fallback like this: | > | >  clock = get_clock(T_MONOTONIC|T_HIRES) or get_clock(T_MONOTONIC) | | Why not passing a a list of set of flags? Example: | | haypo_steady = get_clock(MONOTONIC|STEADY, STEADY, MONOTONIC, REALTIME) | # try to get a monotonic and steady clock, | # or fallback to a steady clock, | # or fallback to a monotonic clock, | # or fallback to the system clock That's interesting. Ethan Furman suggested multiple arguments to be combined, whereas yours bundles multiple search criteria in one call. While it uses a bitmask as mine does, this may get cumbersome if we went with Nick's "use strings!" suggestion. | haypo_perf_counter = get_clock(HIGHRES, MONOTONIC|STEADY, STEADY, | MONOTONIC, REALTIME) | # try to get a high-resolution clock | # or fallback to a monotonic and steady clock, | # or fallback to a steady clock, | # or fallback to a monotonic clock, | # or fallback to the system clock | | On Windows, haypo_steady should give GetTickCount (MONOTONIC|STEADY) | and haypo_perf_counter should give QueryPerformanceCounter | (MONOTONIC|HIGHRES). Sounds ok to me. I am not familiar with the Windows counters and am happy to take your word for it. | Hum, I'm not sure that haypo_highres uses the same clocks than | time.perf_counter() in the PEP. | | > If one wants an exception it is easy to follow up with: | >  if not clock: | >    raise RunTimeError("no suitable clocks on offer on this platform") | | And if don't read the doc carefuly and forget the test, you can a | "NoneType object is not callable" error. Excellent! An exception either way! Win win! | > | get_clock() doesn't remember if a clock works or not (if it raises an | > | OSError) and does not fallback to the next clock on error. See | > | "pseudo-codes" in the PEP 418. | > | > I presume the available clocks are all deduced from the platform. Your | > pseudo code checks for OSError at fetch-the-clock time. I expect that | > to occur once when the module is loaded, purely to populate the table | > of avaiable platform clocks. | | It's better to avoid unnecessary system calls at startup (when the | time module is loaded), but you may defer the creation of the clock | list, or at least of the flags of each clock. Yes indeed. I think this should be deferred until use. | > Note that you don't need to provide a clock list at all; get_clock(0 | > will use ALL_CLOCKS by default, and hires() and monotonic() should each | > have their own default list. | | A list of clocks and a function are maybe redundant. Why not only | providing a function? Only because the function currently only returns one clock. The picky user may want to peruse all the clocks inspecting other metadata (precision etc) than the coarse flag requirements. There should be a way to enumerate the available clock implementation; in my other recent post I suggest either lists (as current), a get_clocks() function, or a mode parameter to get_clock() such as _all_clocks, defaulting to False. | > Regarding the choice itself: as the _caller_ (not the library author), | > you must decide what you want most. You're already planning offering | > monotonic() and hires() calls without my proposal! | | My PEP starts with use cases: it proposes one clock per use case. | There is no "If you need a monotonic, steady and high-resolution clock | ..." use case. Yes. but this is my exact objection to the "just provide hires() and steady() and/or monotonic()" API; the discussion to date is littered with "I can't imagine wanting to do X" style remarks. We should not be trying to enumerate the user case space exhaustively. I'm entirely in favour of your list of use cases and the approach of providing hires() et al to cover the thought-common use cases. But I feel we really _must_ provide a way for the user with a not-thought-of use case to make an arbitrary decision. get_clock() provides a simple cut at the "gimme a suitable clock" approach, with the lists or other "get me an enumeration of the available clocks" mechanism for totally ad hoc perusal if the need arises. This is also my perhaps unstated concern with Guido's "the more I think about it, the more I believe these functions should have very loose guarantees, and instead just cater to common use cases -- availability of a timer with minimal fuss is usually more important than the guarantees" http://www.mail-archive.com/python-dev@python.org/msg66173.html The easy to use hires() etc must make very loose guarentees or they will be useless too often. That looseness is fine in some ways - it provides availability on many platforms (all?) and discourages the user from hoping for too much and thus writing fragile code. But it also PREVENTS the user from obtaining a really good clock if it is available (where "good" means their partiuclar weirdo feature requirements). So I think there should be both - the easy and simple calls, and a mecahnism for providing all clocks for the user to chose with arbitrary criteria and fallback. | The "highres" name was confusing, I just replaced it with | time.perf_counter() (thanks Antoine for the name!). | time.perf_counter() should be used for benchmarking and profiling. I've been wondering; do we distinguish between clocks and counters. In my mind a clock or timer has a very linear relationship with "real time", the wall clock. A counter, by comparison, may measure CPU cycles or kernel timeslice ticks or python opcode counts or any number of other time-like resource consumption things. I've been presuming we're concerned here with "clocks" and not counters. | > Taking your query "Should | > I use MONTONIC_CLOCKS or HIRES_CLOCKS when I would like a monotonic and | > high-resolution clock" is _already_ a problem. Of course you must call | > monotonic() or hires() first under the current scheme, and must answer this | > question anyway. Do you prefer hires? Use it first! No preference? Then the | > question does not matter. | | I mean having to choose the flags *and* the list of clocks is hard. I | would prefer to only have to choose flags or only the list of clocks. | The example was maybe not the best one. Yah; I think I made a followup post where I realised you may have meant this. The use of default arguments is meant to make it easy to use flags and/or lists or even neither (which for get_clock() at least would always get you a clock because a wrapper for time.time() is always provided). In my mind, usually just flags of course. | > | If you have only one list of clocks, how do sort the list to get | > | QueryPerformanceCounter when the user asks for highres and | > | GetTickCount when the user asks for monotonic? | > | > This is exactly why there are supposed to be different lists. | > You have just argued against your objection above. | | You can solve this issue with only one list of clocks if you use the | right set of flags. No you can't, not in general. If there are multiple clocks honouring those flags you only ever get the first one in the list. The point of the MONOTONIC_CLOCKS list etc is that the lists may be differently ordered to provide quality of clock within that domain. Suppose I ask for steady_clock(MONOTONIC); I would probably prefer a more-steady clock over a more-precise/hires clock. And converse desires when asking for hires_clock(). So different list orders, at least in principle. If it turns out empirically that this isn't the case then all the names can in fact refer to the same list. But offering only one list _name_ prevents offering these nuances when other platforms/clocks come in the future. | > | So we would have: | > | | > | GetTickCount.flags = T_MONOTONIC | T_STEADY | T_HIGHRES | > | | > | Even if GetTickCount has only an accuracy of 15 ms :-/ | > | > T_HIGHRES is a quality call, surely? If 15ms is too sloppy for a "high | > resolution, the is should _not_ have the T_HIRES flag. | | So what is the minimum resolution and/or accuracy of the HIGHRES flag? No idea. But you must in principle have one in mind to offer the hires() call at all in the PEP, or be prepared to merely offer the most hires clock available regardless. In this latter case you would always mark that clock as having the HIRES flag and the problem is solved. It would be good to have metadata to indicate how hires a partiulcar clock is. | > | Could you please update your code according to my remarks? I will try | > | to integrate it into the PEP. A PEP should list all alternatives! | > | > Surely. | > | > The only updates I can see are to provide the flat interface | > (instead of via clock-object indirection) and the missing hires_clock() | > and monotonic_clock() convenience methods. | | A full implementation would help to decide which API is the best one. | "Full" implementation: | | - define all convinience function | - define all list of clocks Ok. My current code is here, BTW: https://bitbucket.org/cameron_simpson/css/src/tip/lib/python/cs/clockutils.p... (Finally found a revision independent URL on bitbucket.) | - define flags of all clocks listed in the PEP 418: clocks used in | the pseudo-code of time.steady and time.perf_counter, and maybe also | time.time I'll make one. It will take a little while. Will post again when ready. At present the code compiles and runs (albeit with no platform specific clocks:-) This table may require fictitious code. Should still compile I guess... Cheers, -- Cameron Simpson DoD#743 http://www.cskk.ezoshosting.com/cs/ The right to be heard does not include the right to be taken seriously. - Hubert Horatio Humphrey

2012/4/4 Antoine Pitrou :

On Wed, 4 Apr 2012 02:02:12 +0200 Victor Stinner wrote:

...

...

Lennart Regebro wrote:

...

Well, get_clock(monotonic=True, highres=True) would be a vast improvement over get_clock(MONOTONIC|HIRES).

I don't like this keyword API because you have to use a magically marker (True). Why True? What happens if I call get_clock(monotonic=False) or get_clock(monotonic="yes")?

Since when are booleans magical? Has this thread gone totally insane?

It depends if the option supports other values. But as I understood, the keyword value must always be True. Victor

On Wed, Apr 4, 2012 at 13:04, Victor Stinner wrote:

It depends if the option supports other values. But as I understood, the keyword value must always be True.

Or False, obviously. Which would also be default. //Lennart

Lennart Regebro wrote:

On Tue, Apr 3, 2012 at 18:07, Ethan Furman wrote:

...

What's unclear about returning None if no clocks match?

Nothing, but having to check error values on return functions are not what you typically do in Python. Usually, Python functions that fail raise an error. Please don't force Python users to write pseudo-C code in Python.

You mean like the dict.get() function? --> repr({}.get('missing')) 'None' Plus, failure mode is based on intent: if the intent is "Give a clock no matter what", then yes, an exception when that's not possible is the way to go. But if the intent is "Give me a clock that matches this criteria" then returning None is perfectly reasonable. ~Ethan~

Am 04.04.2012 18:18, schrieb Ethan Furman:

Lennart Regebro wrote:

...

On Tue, Apr 3, 2012 at 18:07, Ethan Furman wrote:

...

What's unclear about returning None if no clocks match?

Nothing, but having to check error values on return functions are not what you typically do in Python. Usually, Python functions that fail raise an error. Please don't force Python users to write pseudo-C code in Python.

You mean like the dict.get() function?

--> repr({}.get('missing')) 'None'

Strawman: this is not a failure. Georg

Georg Brandl wrote:

Am 04.04.2012 18:18, schrieb Ethan Furman:

...

Lennart Regebro wrote:

...

On Tue, Apr 3, 2012 at 18:07, Ethan Furman wrote:

...

What's unclear about returning None if no clocks match? Nothing, but having to check error values on return functions are not what you typically do in Python. Usually, Python functions that fail raise an error. Please don't force Python users to write pseudo-C code in Python. You mean like the dict.get() function?

--> repr({}.get('missing')) 'None'

Strawman: this is not a failure.

Also not a very good example -- if 'missing' was there with a value of None the two situations could not be distinguished with the one call. At any rate, the point is that there is nothing inherently wrong nor unPythonic about a function returning None instead of raising an exception. ~Ethan~

Oleg Broytman wrote:

On Wed, Apr 04, 2012 at 11:03:02AM -0700, Ethan Furman wrote:

...

Oleg Broytman wrote:

...

. Pythonic equivalent of "get_clock(THIS) or get_clok(THAT)" is

for flag in (THIS, THAT): try: clock = get_clock(flag) except: pass else: break else: raise ValueError('Cannot get clock, tried THIS and THAT')

Wow -- you'd rather write nine lines of code instead of three?

clock = get_clock(THIS) or get_clock(THAT) if clock is None: raise ValueError('Cannot get clock, tried THIS and THAT')

Yes - to force people to write the last two lines. Without forcing most programmers will skip them.

Forced? I do not use Python to be forced to use one style of programming over another. And it's not like returning None will allow some clock calls to work but not others -- as soon as they try to use it, it will raise an exception. ~Ethan~

Oleg Broytman wrote:

On Wed, Apr 04, 2012 at 11:03:02AM -0700, Ethan Furman wrote:

...

Oleg Broytman wrote:

...

. Pythonic equivalent of "get_clock(THIS) or get_clok(THAT)" is

for flag in (THIS, THAT): try: clock = get_clock(flag) except: pass else: break else: raise ValueError('Cannot get clock, tried THIS and THAT')

Wow -- you'd rather write nine lines of code instead of three?

clock = get_clock(THIS) or get_clock(THAT) if clock is None: raise ValueError('Cannot get clock, tried THIS and THAT')

Yes - to force people to write the last two lines. Without forcing most programmers will skip them.

You're not my real Dad! You can't tell me what to do! *wink* This level of paternalism is unnecessary. It's not your job to "force" programmers to do anything. If people skip the test for None, they will get an exception as soon as they try to use None as an exception, and then they will fix their broken code. Although I don't like the get_clock() API, I don't think this argument against it is a good one. Exceptions are the *usual* error-handling mechanism in Python, but they are not the *only* mechanism, there are others, and it is perfectly okay to use non-exception based failures when appropriate. This is one such example. "Return None on failure" is how re.match() and re.search() work, and it is a good design for when you have multiple fallbacks on failure. result = re.match(spam, s) or re.match(ham, s) or re.match(eggs, s) if result is None: raise ValueError('could not find spam, ham or eggs') This is a *much* better design than nested tries: try: result = re.match(spam, s) except ValueError: try: result = re.match(ham, s) except ValueError: try: result = re.match(eggs, s) except ValueError: raise ValueError('could not find spam, ham or eggs') Wow. Now *that* is ugly code. There's nothing elegant or Pythonic about being forced to write that out of a misplaced sense of purity. -- Steven

2012/4/4 Lennart Regebro :

On Wed, Apr 4, 2012 at 13:04, Victor Stinner wrote:

...

It depends if the option supports other values. But as I understood, the keyword value must always be True.

Or False, obviously. Which would also be default.

Ok for the default, but what happens if the caller sets an option to False? Does get_clock(monotonic=False) return a non-monotonic clock? (I guess no, but it may be confusing.) Victor

On Thu, Apr 5, 2012 at 01:10, Victor Stinner wrote:

2012/4/4 Lennart Regebro :

...

On Wed, Apr 4, 2012 at 13:04, Victor Stinner wrote:

...

It depends if the option supports other values. But as I understood, the keyword value must always be True.

Or False, obviously. Which would also be default.

Ok for the default, but what happens if the caller sets an option to False? Does get_clock(monotonic=False) return a non-monotonic clock? (I guess no, but it may be confusing.)

Good point, but the same does for using flags. If you don't pass in the MONOTONIC flag, what happens? Only reading the documentation will tell you. As such this, if anything, is an indication that the get_clock() API isn't ideal in any incarnation. //Lennart

On Thu, Apr 05, 2012 at 10:06:38PM +0900, Stephen J. Turnbull wrote:

On Thu, Apr 5, 2012 at 8:05 AM, Oleg Broytman wrote:

...

  Well, I am partially retreat. "Errors should never pass silently. Unless explicitly silenced." get_clock(FLAG, on_error=None) could return None.

I still don't see what's erroneous about returning None when asked for an object that is documented to possibly not exist, ever, in some implementations. Isn't that precisely why None exists?

Why doesn't open() return None for a non-existing file? or socket.gethostbyname() for a non-existing name? Oleg. -- Oleg Broytman http://phdru.name/ phd@phdru.name Programmers don't die, they just GOSUB without RETURN.

On Thu, Apr 05, 2012 at 11:45:06PM +0900, Stephen J. Turnbull wrote:

On Thu, Apr 5, 2012 at 10:34 PM, Oleg Broytman wrote:

...

  Why doesn't open() return None for a non-existing file? or socket.gethostbyname() for a non-existing name?

That's not an answer to my question, because those calls have very important use cases where the user knows the object exists (and in fact in some cases open() will create it for him), so that failure to exist is indeed a (user) error (such as a misspelling). I find it hard to imagine use cases where "file = open(thisfile) or open(thatfile)" makes sense. Not even for the case where thisfile == 'script.pyc' and thatfile == 'script.py'.

Counterexamples - any configuration file: a program looks for its config at $HOME and not finding it there looks in /etc. So config = open('~/.someprogram.config') or open('/etc/someprogram/config') would make sense. The absence of any of these files is not an error at all - the program just starts with default configuration. So if the resulting config in the code above would be None - it's still would be ok. But Python doesn't allow that. Some configuration files are constructed by combining a number of user-defined and system-defined files. E.g., the mailcap database. It should be something like combined_database = [db for db in ( open('/etc/mailcap'), open('/usr/etc/mailcap'), open('/usr/local/etc/mailcap'), open('~/.mailcap'), ) if db] But no way - open() raises IOError, not return None. And I think it is the right way. Those who want to write the code similar to the examples above - explicitly suppress exceptions by writing wrappers.

The point of the proposed get_clock(), OTOH, is to ask if an object with certain characteristics exists, and the fact that it returns the clock rather than True if found is a matter of practical convenience. Precisely because "clock = get_clock(best) or get_clock(better) or get_clock(acceptable)" does make sense.

Oleg. -- Oleg Broytman http://phdru.name/ phd@phdru.name Programmers don't die, they just GOSUB without RETURN.

On Thu, Apr 05, 2012 at 07:22:17PM +0400, Oleg Broytman wrote:

On Thu, Apr 05, 2012 at 11:45:06PM +0900, Stephen J. Turnbull wrote:

...

find it hard to imagine use cases where "file = open(thisfile) or open(thatfile)" makes sense. Not even for the case where thisfile == 'script.pyc' and thatfile == 'script.py'.

Counterexamples - any configuration file: a program looks for its config at $HOME and not finding it there looks in /etc. So config = open('~/.someprogram.config') or open('/etc/someprogram/config') would make sense.

A counterexample with gethostbyname - a list of proxies. It's not an error if some or even all proxies in the list are down - one just connect to the first that's up. So a chain like proxy_addr = gethostbyname(FIRST) or gethostbyname(SECOND) would make sense. Oleg. -- Oleg Broytman http://phdru.name/ phd@phdru.name Programmers don't die, they just GOSUB without RETURN.

Oleg Broytman wrote:

On Wed, Apr 04, 2012 at 12:52:00PM -0700, Ethan Furman wrote:

...

Forced? I do not use Python to be forced to use one style of programming over another.

Then it's strange you are using Python with its strict syntax (case-sensitivity, forced indents), ubiquitous exceptions, limited syntax of lambdas and absence of code blocks (read - forced functions), etc.

I come from assembly -- 'a' and 'A' are *not* the same. indents -- I already used them; finding a language that gave them the same importance I did was incredible. exceptions -- Python uses them, true, but I don't have to in my own code (I do, but that's besides the point). lambdas -- they work just fine for my needs. etc.

...

And it's not like returning None will allow some clock calls to work but not others -- as soon as they try to use it, it will raise an exception.

There is a philosophical distinction between EAFP and LBYL. I am mostly proponent of LBYL. Well, I am partially retreat. "Errors should never pass silently. Unless explicitly silenced." get_clock(FLAG, on_error=None) could return None.

It's only an error if it's documented that way and, more importantly, thought of that way. The re module is a good example: if it can't find what you're looking for it returns None -- it does *not* raise a NotFound exception. I see get_clock() the same way: I need a clock that does xyz... None? Okay, there isn't one. ~Ethan~

Oleg Broytman wrote:

On Thu, Apr 05, 2012 at 11:56:00AM -0700, Ethan Furman wrote:

...

It's only an error if it's documented that way and, more importantly, thought of that way. The re module is a good example: if it can't find what you're looking for it returns None -- it does *not* raise a NotFound exception.

But open() raises IOError. ''.find('a') returns -1 but ''.index('a') raises ValueError. So we can argue in circles both ways, there are too many arguments pro and contra. Python is just too inconsistent to be consistently argued over. ;-)

Indeed -- I think we have reached an agreement! Now if you'll just agree that returning None in this case is better... ;) ~Ethan~

On 06Apr2012 00:15, Oleg Broytman wrote: | So we can argue in circles both ways, there are too many arguments | pro and contra. Python is just too inconsistent to be consistently | argued over. ;-) Bah! I think these threads demonstrate that we can consistently argue over Python for weeks per topic, sometimes months and years. -- Cameron Simpson DoD#743 http://www.cskk.ezoshosting.com/cs/ Sam Jones on the Nine Types of User: Frying Pan/Fire Tactician - "It didn't work with the data set we had, so I fed in my aunt's recipe for key lime pie." Advantages: Will usually fix error. Disadvantages: 'Fix' is defined VERY loosely here. Symptoms: A tendancy to delete lines that get errors instead of fixing them. Real Case: One user complained that their program executed, but didn't do anything. The scon looked at it for twenty minutes before realizing that they'd commented out EVERY LINE. The user said, "Well, that was the only way I could get it to compile."

Le 06/04/2012 00:17, Cameron Simpson a écrit :

This is where the bitmap approach can be less confusing - the docstring says "The returned clock shall have all the requested flags". It is at least very predictable.

By the way, I removed ("deferred") the time.highres() function from the PEP, and I try to avoid the term "steady" because no OS clock respect the definition of "steady" (especially in corner cases as system suspend/resume). So which flags do you want to support? (only "monotonic"?) Basically, get_clock("monotonic") should give time.monotonic() whereas get_clock() gives time.time()? Victor

On 06Apr2012 08:51, I wrote: | On 06Apr2012 00:27, Victor Stinner wrote: | | By the way, I removed ("deferred") the time.highres() function from the | | PEP, | | Chuckle; was not the whole PEP for a high res clock? Gah. I see it was for montonic, not high res. Sorry. [...] | I can think of definitions of "steady" that I personally would accept, | and they'd accept that suspend/resume would be concealed (I guess I | would usually want - purely myself here - a clock representing system | run time; I'd go for time.time() for wall clock). | | | So which flags do you want to support? (only "monotonic"?) | | I'd stay with my current list, with metadata in the clock objects | indicating what _flavour_ of "steady" or "high res" they present. On reflection, since I have historically presumed time.time() on UNIX mapped to "man 2 time", I clearly think that time.time() is wall clock time, and may jump when the sysadmin notices it is incorrect (of course this is often mediated by NTP, which in turn is usually mediated by some ntpd using adjtime(), which slews instead of jumping). But it might jump. (I'm intending to jump a wayard VM today, in fact:-) So guess I expect time.time() to be only usually steady. And usually monotonic. So having neither flag. Do I want a WALLCLOCK flag? Meaning a clock that is supposed to be real world time (did I see REALTIME in one of your examples?), and may be almost arbirarily corrected to be made real world if it is wrong. Maybe. +0 on that I think. Basicly I'm distinguishing here between a clock used for timestamps, for example in log entries, and a clock used for measuring elapsed system run time, for example in benchmarking. I would want to log entries to match what a clock on the wall should say. So I think I'm _still_ for the three original flags I suggested (monotonic, high res, steady) and expect time.time() to not necessarily meet any of them. But to meet a hypothetical WALLCLOCK flag. Regarding UNIX time(2) (or POSIX time(3)), POSIX says: The time() function shall return the value of time in seconds since the Epoch. and the epoch is a date. So UNIX time() should be a wall clock. Python "help(time.time)" says: Return the current time in seconds since the Epoch. So I think it should also be a wall clock by that same reasoning. Cheers, -- Cameron Simpson DoD#743 http://www.cskk.ezoshosting.com/cs/ Uh, this is only temporary...unless it works. - Red Green

Cameron Simpson wrote:

On 05Apr2012 08:50, Steven D'Aprano wrote: | Although I don't like the get_clock() API, I don't think this argument against | it is a good one.

Just to divert briefly; you said in another post you didn't like the API and (also/because?) it didn't help discoverability.

My core objective was to allow users to query for clocks, and ideally enumerate and inspect all clocks. Without the caller having platform specific knowledge.

Clocks *are* platform specific -- not just in their availability, but also in the fine details of their semantics and behaviour. I don't think we can or should try to gloss over this. If people are making decisions about timers without knowledge of what their platform supports, they're probably making poor decisions. Even the venerable time.time() and time.clock() differ between Linux and Windows.

Allowing for the sake of discussion that this is desirable, what would you propose as an API instead of get_clock() (and its friend, get_clocks() for enumeration, that I should stuff into the code).

The old ways are the best. We don't have math.get_trig() and math.get_trigs() functions for querying trigonometric functions, we just expose the functions directly. I think the way to enumerate and inspect all clocks is with the tried and true Python introspection tools that people use on all other functions: * use dir(time) to see a list of names available in the module * use help(time) to read their help * read the Fine Manual to find out more * use try... except... to detect the existence of a clock There's nothing special about clocks that needs anything more than this. get_clock() looks like a factory function, but it actually isn't. It just selects from a small number of pre-existing clocks. We should just expose those pre-existing clocks directly. I don't see any advantage in adding that extra level of indirection or the addition of all this complexity: * a function get_clock() to select a clock * a function get_clocks() to enumerate all the clocks * another function for querying the properties of a clock All those functions accomplish is to increase the complexity of the API, the documentation and the implementation. It's one more special case for the user to learn: "To find out what functions are available, use dir(module), except for clocks, where you have to use time.get_clocks()." Blah. Another problem with get_clock() -- it will be an attractive nuisance for the sort of person who cares about symmetry and completeness. You will have a steady trickle of "feature requests" from users who are surprised that not every combination of features is supported. Out of the eight or sixteen or thirty-two potential clocks that get_clock() tempts the user with, only three or five will actually exist. The only advantage of get_clock is that you don't need to know the *name* of a platform clock in order to use it, you can describe it with a series of flags or enums. But in practice, that's not an advantage, that's actually a disadvantage. Consider: "Which clock should I use for such-and-such a task, foo or bar?" versus "Which clock should I use for such-and-such a task, get_clock(spam, eggs, cheese) or get_clock(ham, eggs, truffles)?" The mere mechanics of talking about these clocks will suffer because they aren't named. -- Steven

On Fri, Apr 06, 2012 at 11:57:20AM +0900, "Stephen J. Turnbull" wrote:

What I want to know is why you're willing to assert that absence of a clock of a particular configuration is an Exception, when that absence clearly documented to be a common case?

An error or not an error depends on how people will use the API. I usually don't like error codes -- people tend to ignore them or check lazily. If some library would do (get_clock(THIS) or get_clock(THAT)).clock() I want to get a clearly defined and documented clock-related error, not some vague "AttributeError: 'NoneType' object has no attribute 'clock'". Oleg. -- Oleg Broytman http://phdru.name/ phd@phdru.name Programmers don't die, they just GOSUB without RETURN.

On Fri, Apr 6, 2012 at 00:17, Cameron Simpson wrote:

Gah! ALL functions are like that! How often do we see questions about max() or split() etc that a close reading of the docs obviate?

My point exactly. //Lennart

I don't know who started this, but the PEP 418 threads have altogether too much snarkiness and not enough content. It's bad enough that we're bikeshedding so intensely; we don't need clever comebacks in triplicate to every out-of-context argument. --Guido On Fri, Apr 6, 2012 at 2:26 PM, Ethan Furman wrote:

Lennart Regebro wrote:

...

On Fri, Apr 6, 2012 at 00:17, Cameron Simpson wrote:

...

Good point, but the same does for using flags. If you don't pass in

the MONOTONIC flag, what happens? Only reading the documentation will tell you. As such this, if anything, is an indication that the

get_clock() API isn't ideal in any incarnation.

...

Gah! ALL functions are like that! How often do we see questions about max() or split() etc that a close reading of the docs obviate?

My point exactly.

Huh?  Your point is that all APIs are less than ideal because you have to read the docs to know for certain how they work?

~Ethan~

_______________________________________________ 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/guido%40python.org

-- --Guido van Rossum (python.org/~guido)

On 4/6/2012 4:11 PM, Cameron Simpson wrote:

Another alternative is the public lists-of-clocks.

After watching this thread with amusement and frustration, amusement because it is so big, and so many people have so many different opinions, frustration, because it seems that few of the clocks that are available are anywhere near ideal for any particular stated characteristic, and because none of the APIs presented provide a way for the user to specify the details of the characteristics of the desired clock, I think this idea of a list-of-clocks sounds better and better. Hopefully, for each system, the characteristics of each clock can be discovered, and fully characterized in available metadata for the clock... tick rate, or list of tick rates maximum variation of tick rate precision maximum "helicopter drop" jump delta monotonicity frequency of rollover or None base epoch value or None behavior during system sleep, hibernate, suspend, shutdown, battery failure, flood, wartime events, and acts of God. These last two may have values that are long prose texts full of political or religious rhetoric, such as the content of this thread :) any other characteristics I forgot to mention Of course, it is not clear that all of these characteristics can be determined based on OS/Version; hardware vendors may have different implementations. There should be a way to add new clock objects to the list, given a set of characteristics, and an API to retrieve them, at least by installing a submodule that provides access to an additional clock.

Victor et al, Just an update note: I've started marking up clocks with attributes; not yet complete and I still need to make a small C extension to present the system clocks to Python space (which means learning to do that, too). But you can glance over the start on it here: https://bitbucket.org/cameron_simpson/css/src/tip/lib/python/cs/clockutils.p... Several feature flags and some properties for qualifying clocks. Still needed stuff includes: C access to clocks, .accuracy being actual clock precision versus the resolution of the units in the underlying OS call, a __repr__ and/or __str__ to decode feature bitmaps into useful strings, .is_*() __getattr__ method to resolve against flags by name or maybe has_flag(str), etc. On 07Apr2012 01:16, Victor Stinner wrote: | > | This is the original reason for the original defect (issue 10278) | > | unix' clock() doesn't actually provide a clock in this sense, | > | it provides a resource usage metric. | > | > Yeah:-( Its help says "Return the CPU time or real time since [...]". | > Two very different things, as demonstrated. I suppose neither goes | > backwards, but this seems like a classic example of the "useless | > monotonic clock" against which Greg Ewing railed. | > | > And why? For one thing, because one can't inspect its metadata to find | > out what it does. | | Should I add another key to the result of | time.get_clock_info('clock')? How can we define "clock on Windows" | (almost monotonic and steady clock) vs "clock on UNIX" (CPU time) with | a flag or a value? For clocks I'm going with two feature flags: WALLCLOCK and RUNTIME. The former indicates a clock that tries to stay in synch with real world time, and would still advance when the system is suspended or idle; it would almost certainly need to "step" over a suspend. The latter means system run time; it accrues only while the system is up. Neither is CPU usage (so a time.sleep(10) would add 10 seconds to both). I think resource usage is not a "clock". We could characterise such timers and counters with a lot of the same metrics we like to use with clocks, but I do not think they should be returned by a system purporting to return clocks or clock values. On 07Apr2012 14:22, I wrote: | On 06Apr2012 17:30, Glenn Linderman wrote: | | Hopefully, for each system, the characteristics of each clock can be | | discovered, and fully characterized in available metadata for the clock... | | Victor has asked me to do that for my skeleton, based on the tables he | has assembled. I'll see what i can do there... I've started on this, see above. Victor Stinner wrote: | | - define flags of all clocks listed in the PEP 418: clocks used in | | the pseudo-code of time.steady and time.perf_counter, and maybe also | | time.time | | I'll make one. It will take a little while. Will post again when ready. So, new code to glance over as evidence of good faith, if not speed:-( Cheers, -- Cameron Simpson DoD#743 http://www.cskk.ezoshosting.com/cs/ Life is uncertain. Eat dessert first. - Jim Blandy