select.2: s/minimum/maximum/
I think the misunderstanding stems from the fact that we do not give the same meaning to the expressions "maximum waiting time" and "waiting time". And excuse me for putting it bluntly, but I still think I am right about the meaning I give to these expressions.
I will try to explain what those expressions are supposed to mean. A "timeout" is a "_maximum_ time" spent in a operation, at which point the operation is to be cancelled. During the select(2) call the time is spent waiting, hence the time spent in the select(2) call is a "waiting time", whether or not the call returns because of a timeout or because an FD is ready. The timeout in the case of the select(2) call is a "waiting timeout", and a synonym for it would be "maximum waiting time".
Hence using the phrase "minimum waiting time" to describe the timeout is antonymous, because one cannot guess that the minimum here refers to the rounding of the time and not to the use of it; by reading that phrase one understands that timeout is a duration that has to elapse before which the call to select(2) is allowed to return.
I think what you understand by "waiting time" is what I would call (as certainly many others) a "maximum waiting time" or simply timeout, hence the misunderstanding. If you do not want to write about a maximum waiting time (to avoid a confusion about the rounding that occurs for example), at least modify the wording so that the above mentioned misunderstanding cannot happen; for example substituting "waiting timeout" for "waiting time" everywere would be sufficient.
Quoted 10 lines
Date: Fri, 23 Aug 2013 10:51:12 +0200
From: "Michael Kerrisk (man-pages)" <[email protected]>
To: "G.raud" <[email protected]>
Cc: linux-man <[email protected]>
Subject: Re: select.2: s/minimum/maximum/Quoted 4 lines
Quoted 4 lines
Date: Thu, 22 Aug 2013 09:22:32 +0200
From: "Michael Kerrisk (man-pages)" <[email protected]>
Subject: Re: select.2: s/minimum/maximum/
Quoted 5 lines
Quoted 2 lines
The text that you cite and that is not correct is extracted from the present manpage.
Your original report was rather briefly worded, and my "This" referred to your subject line, not the text you cited.
I considered that such could be the case and I answered accordingly.
Quoted 9 lines
Quoted 4 lines
The corrected text should be:
" The timeout argument specifies the maximum interval that
select()should block waiting for a file descriptor to become ready. "Again, this is NOT correct. According to that statement, an implementation that did not block at all would also be conformant, since 0 is always less than or equal to whatever value is specified in 'timeout'.
As I explained above by "maximum waiting time" I mean timeout, not maximum timeout.
Quoted 4 lines
This point was the subject of changes in several man pages (poll(2),
epoll_pwait(2), select(2), sigtimedwait(2)) back in May 2012, after someone (I can't remember who) reported the point about one of those pages.
I looked at those manpages and, for the same reason, they have explanations regarding the timeout that are at best clumsy when not wrong IMO.
Quoted 6 lines
Quoted 3 lines
which is close to the POSIX description and is correct in that "specify" does not mean "is equal to" but can be understood as "is close to", which is all most of the programmers need to know.
Either of these interpretations would be a surprising way of defining "specify", IMO.
Those would only be _possible_ specifications made up by a reader at that point in the text (that would turn up to be almost true). Synonyms for "specify" could be "determine", "define", "characterize", "fix".
Quoted 3 lines
By the way, I see what you mean about the POSIX description of
select(). It speaks of "maximum". But there, I would say the problem is an imprecision in the standard.
I think the standard uses maximum to make it clear that the call has to return right _after_ the timeout has elapsed.
Quoted 3 lines
They get things worded better in
thepoll()spec, which says: "poll()shall wait at least timeout milliseconds".
You forgot the beginning of the sentence:
" If none of the defined events have occurred on any selected file
descriptor, poll() shall wait at least timeout milliseconds. "
This is correct because of the conditional "If ..." and would not be without it.
Quoted 9 lines
Quoted 4 lines
I suggest prepending the following before the complete description bewtween parentheses if a better (i.e. more explicit) wording is desired:
" timeout is a lower bound on the actual maximum waiting time."
Now, I do (I think) understand why the current text troubles you: it's because the description is counter-intuitive. But, when one thinks about it, one realizes that it is accurate (and s/minimum/maximum/ is not).
I agree that s/minimum/maximum/ would make the statement less accurate than you would like it to be since it would not have any hints of possible roundings of the timeout; but as I explained above, I think the present text is wrong because it reverses the meaning of timeout.
Quoted 2 lines
And the very next sentences are there to help the reader understand this point:
True; those sentences are of help to someone who knows the select(2) call already.
Quoted 6 lines
(This interval will be rounded up to the system clock granular‐ ity, and kernel scheduling delays mean that the blocking interval may overrun by a small amount.)
One could I suppose reword something like this:
Quoted 7 lines
The timeout argument specifies the interval that
select()should block waiting for a file descriptor to become ready. In effect, timeout specifies a minimum interval: the timeout will be rounded up to the system clock granularity, and kernel scheduling delays mean that the blocking interval may overrun by a small amount.But I'm not sure that that is really much of an improvement.
I see it as a huge improvement because it does not reverse the meaning of timeout.
Regards
Signature · 5 lines
G.raud Meyer -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
A message that is not in the archive (sent off-list or not yet received): [email protected]
Quoted 8 lines
Quoted 8 lines
One could I suppose reword something like this:
The timeout argument specifies the interval that
select()should block waiting for a file descriptor to become ready. In effect, timeout specifies a minimum interval: the timeout will be rounded up to the system clock granularity, and kernel scheduling delays mean that the blocking interval may overrun by a small amount.
Quoted 4 lines
Quoted 1 line
But I'm not sure that that is really much of an improvement.
I see it as a huge improvement because it does not reverse the meaning of timeout.
Okay -- I've the simpler patch below.
Cheers,
Michael
man2/select.2 +3 -3
@@ -159,12 +159,12 @@ is the highest-numbered file descriptor in any of the three sets, plus 1. .PP The .I timeout -argument specifies the minimum interval that +argument specifies the interval that .BR select () should block waiting for a file descriptor to become ready. -(This interval will be rounded up to the system clock granularity, +This interval will be rounded up to the system clock granularity, and kernel scheduling delays mean that the blocking interval -may overrun by a small amount.) +may overrun by a small amount. If both fields of the .I timeval structure are zero, then
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html