Re: select.2: s/minimum/maximum/

Re: select.2: s/minimum/maximum/

[G.raud]

> Date: Thu, 22 Aug 2013 09:22:32 +0200
> From: "Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
> Subject: Re: select.2: s/minimum/maximum/
> 
> On 08/20/13 01:00, G.raud wrote:
> > In this part of the manpage:
> > 
> > " The timeout argument specifies the minimum interval that select()
> >   should block waiting for a file descriptor to become ready.        "
> 
> This isn't correct (though maybe there is room for a better wording).
> 
> The 'timeout' places a ceiling on how long the call will block,
> but that ceiling has the *minimum* value provided by the argument.
> See what I mean?

The text that you cite and that is not correct is extracted from the
present manpage.  The corrected text should be:

 " The timeout argument specifies the maximum interval that select()
   should block waiting for a file descriptor to become ready.  "

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.

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."

-- 
G.raud Meyer
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: select.2: s/minimum/maximum/

[Michael Kerrisk (man-pages)]

Hi,

On Thu, Aug 22, 2013 at 5:38 PM, G.raud <graud-KK0ffGbhmjU@public.gmane.org> wrote:
>> Date: Thu, 22 Aug 2013 09:22:32 +0200
>> From: "Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
>> Subject: Re: select.2: s/minimum/maximum/
>>
>> On 08/20/13 01:00, G.raud wrote:
>> > In this part of the manpage:
>> >
>> > " The timeout argument specifies the minimum interval that select()
>> >   should block waiting for a file descriptor to become ready.        "
>>
>> This isn't correct (though maybe there is room for a better wording).
>>
>> The 'timeout' places a ceiling on how long the call will block,
>> but that ceiling has the *minimum* value provided by the argument.
>> See what I mean?
>
> 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.

> 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'. 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.

> 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.

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. They get things worded better in
the poll() spec, which says: "poll()  shall  wait  at  least timeout
milliseconds".

> 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). And the very next sentences are there to help the reader
understand this point:

       (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:

       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.

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: select.2: s/minimum/maximum/

[G.raud]

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.

> Date: Fri, 23 Aug 2013 10:51:12 +0200
> From: "Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
> To: "G.raud" <graud-KK0ffGbhmjU@public.gmane.org>
> Cc: linux-man <linux-man-u79uwXL29TY76Z2rM5mHXA@public.gmane.org>
> Subject: Re: select.2: s/minimum/maximum/
> 
> >> Date: Thu, 22 Aug 2013 09:22:32 +0200
> >> From: "Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
> >> Subject: Re: select.2: s/minimum/maximum/
> >>
> > 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.

> > 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.

> 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.

> > 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".

> 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.

> They get things worded better in
> the poll() 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.

> > 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.

> 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.

>        (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:
> 
>        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

-- 
G.raud Meyer
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: select.2: s/minimum/maximum/

[Michael Kerrisk (man-pages)]

>> 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.
>>
>> 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

--- a/man2/select.2
+++ b/man2/select.2
@@ -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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

select.2: s/minimum/maximum/

[G.raud]

In this part of the manpage:

" The timeout argument specifies the minimum interval that select()
  should block waiting for a file descriptor to become ready.        "

-- 
G.raud Meyer
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: select.2: s/minimum/maximum/

[Michael Kerrisk (man-pages)]

On 08/20/13 01:00, G.raud wrote:
> In this part of the manpage:
> 
> " The timeout argument specifies the minimum interval that select()
>   should block waiting for a file descriptor to become ready.        "

This isn't correct (though maybe there is room for a better wording).

The 'timeout' places a ceiling on how long the call will block,
but that ceiling has the *minimum* value provided by the argument.
See what I mean?

Cheers,

Michael

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html