Title: time.monotonic(): Docs imply comparing call N and call N+M is invalid for M>1
Type: Stage: resolved
Components: Documentation Versions: Python 3.10, Python 3.9, Python 3.8
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Alex.Willmer, docs@python, miss-islington, terry.reedy
Priority: normal Keywords: patch

Created on 2021-03-04 22:21 by Alex.Willmer, last changed 2021-03-06 01:53 by terry.reedy. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 24757 merged Alex.Willmer, 2021-03-04 22:54
PR 24768 merged miss-islington, 2021-03-06 01:22
PR 24769 merged miss-islington, 2021-03-06 01:23
Messages (5)
msg388133 - (view) Author: Alex Willmer (Alex.Willmer) * Date: 2021-03-04 22:21
I believe the documentation for time.monotonic() and time.perf_counter() could be misleading. Taken literally they could imply that given

delta = 0.1
a = time.monotonic()
b = time.monotonic()
c = time.monotonic()

the comparisons `b - a < delta`, and `c - b < delta` are valid; but `c - a < delta` is not valid.

I believe that `c - a < delta` is a valid comparison, and that what the documentation means to say is "only the difference between the results of *subsequent* calls is valid."

The exact wording (present since the functions were added in

> The reference point of the returned value is undefined, so that only
> the difference between the results of consecutive calls is valid.

If there is agreement I'll submit a PR.
msg388135 - (view) Author: Alex Willmer (Alex.Willmer) * Date: 2021-03-04 22:34
Discussion from #python IRC

[21:51] <moreati> Given `a=time.monotonic(); b=time.monotonic(); c=time.monotonic()` is `c-a < delta` a valid comparison? Until this evening I thought so, but I've just read and the wording it uses is "only the difference between the results of consecutive calls is valid" implying `b-a < delta` is valid, or `c-b < delta`; but not `c-a < delta`. Am I understanding the wording correctly?
[21:52] <moreati> IOW is it literally only call n, and n+1. or n, and n+m?
[21:53] <SnoopJ> moreati, I think "consecutive" is incorrect there, based on the rest of that sentence.
[21:57] <jarthur> moreati SnoopJ yes, I agree, the consecutive wording has tripped me up when I first started using monotonic. I think there's an understated transitive property that allows a to c comparisons just fine.
[21:58] <SnoopJ> jarthur, yea, it would be deeply weird if `b-a` and `c-b` were meaningful deltas, but `c-a` was not
[21:59] <moreati> re time.monotonic() the only reason I could of for the literal interpretation of the wording is an overflow, or integer wraparound corner case
[22:00] <SnoopJ> weirdly, the CPython doc uses the same language
[22:02] <jarthur> I actually ended up looking at the monotonic code a while back, and at least back then the wraparound case is really hard to reach, maybe possible on Windows if you haven't called it in a while. Either way, there was nothing in the Linux/glibc or Windows calls used that would have made the wraparound/overflow case apply to skipped evaluation of a middle observation more than it would consecutive observations.
[22:06] <SnoopJ> moreati, looks like this language was added when the function was, and I guess maybe nobody's ever raised this complaint about the wording:
[22:07] <SnoopJ> nice catch :)
[22:22] <moreati> FTR
[22:28] <SnoopJ> moreati, I would recommend just submitting the PR, since it's docs.
[22:28] <moreati> ok
[22:28] <SnoopJ> but I think the best wording would be something like "only the difference between two calls of this function is meaningful"
[22:30] <moreati> agreed, subsequent is a $5 word in a 50c requirement. May I quote our conversation in the ticket? Ditto jarthur
[22:30] <SnoopJ> absolutely
[22:30] <jarthur> yep
[22:30] <moreati> ty
[22:30] <SnoopJ> but yea, just open a PR, that way you need a single pass from someone with authority here rather than two ;)
[22:31] <grym> >Never use a long word where a short one will do.
msg388180 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2021-03-06 01:22
New changeset ff5f05934db241dfafc604989b2de3487b09ca82 by Alex Willmer in branch 'master':
bpo-43407: Clarify comparisons of time.monotonic() et al results (GH-24757)
msg388182 - (view) Author: miss-islington (miss-islington) Date: 2021-03-06 01:34
New changeset e12a9e2f62bea8ddc755e373f17adfbb2740b0b1 by Miss Islington (bot) in branch '3.8':
bpo-43407: Clarify comparisons of time.monotonic() et al results (GH-24757)
msg388185 - (view) Author: miss-islington (miss-islington) Date: 2021-03-06 01:48
New changeset 65f3a0d20c8198443c5c6cb44410114fe8c4bf4e by Miss Islington (bot) in branch '3.9':
bpo-43407: Clarify comparisons of time.monotonic() et al results (GH-24757)
Date User Action Args
2021-03-06 01:53:35terry.reedysetstatus: open -> closed
stage: patch review -> resolved
resolution: fixed
versions: + Python 3.10, - Python 3.6, Python 3.7
2021-03-06 01:48:41miss-islingtonsetmessages: + msg388185
2021-03-06 01:34:34miss-islingtonsetmessages: + msg388182
2021-03-06 01:23:22miss-islingtonsetpull_requests: + pull_request23537
2021-03-06 01:22:33terry.reedysetnosy: + terry.reedy
messages: + msg388180
2021-03-06 01:22:32miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request23536
2021-03-04 22:54:32Alex.Willmersetkeywords: + patch
stage: patch review
pull_requests: + pull_request23528
2021-03-04 22:34:08Alex.Willmersetmessages: + msg388135
2021-03-04 22:21:10Alex.Willmercreate