Re: FW: WaitForMultipleObjects/etc. In Kernel

["Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]

On 01/30/2014 09:04 PM, Network Nut wrote:
>> -----Original Message-----
>> From: Michael Kerrisk (man-pages) [mailto:mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org]
>> Sent: Wednesday, January 29, 2014 4:40 AM
>> To: Network Nut
>> Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org; linux-man-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
>> Subject: Re: FW: WaitForMultipleObjects/etc. In Kernel
>>
>> On 01/27/2014 10:21 PM, Network Nut wrote:
>>> See below.
>>>
>>> -----Original Message-----
>>> From: Clemens Ladisch [mailto:clemens-P6GI/4k7KOmELgA04lAiVw@public.gmane.org]
>>> Sent: Monday, January 27, 2014 3:07 AM
>>> To: Network Nut
>>> Cc: linux-kernel-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
>>> Subject: Re: WaitForMultipleObjects/etc. In Kernel
>>>
>>>> BTW, the man page for epoll_wait seems to be incorrect.
>>>
>>> <https://www.kernel.org/doc/man-pages/reporting_bugs.html>
>>>
>>>> "The timeout argument specifies the minimum number of milliseconds
>>>>        that epoll_wait() will block."
>>>>
>>>> I think the word "minimum" should be "maximum".
>>
>> I've removed the word "minimum" from the sentence. Note that
>> "maximum" would not be correct. See the surrounding text for an
>> explanation of why.
>>
>> Thanks for the report.
>>
>> Cheers,
>>
>> Michael
> 
> Hi Michael,
> 
> I re-read the sentence with the word "minimum" being removed. It makes sense
> now, at least for those of us who already understand how it should work
> [WaitForMultipleObjects]. But I wonder....Imagine a programmer who is
> relatively new to synchronization, just discovering the power of waiting for
> multiple fd's. Reading that statement, s/he might be inclined to believe
> that the function really will wait, say, 1000 milliseconds, without regard
> for signaling state of any of the fd's that might transition during the call
> to epoll_wait. The reason would be that s/he has no reason to believe
> otherwise, as that is what the man page says. By contrast, those of us who
> already know the nature of this function would not be confused because we
> would think, "Ok, I know that epoll_wait will not actually wait 1000 ms in
> all cases, but ..." 
> 
> Not trying to teach the teacher here. :) Just saying'. [Yes, it's a
> nit-pick.]

Fair enough. You're not the fist to comment on this. It seems that more detailed
language would be helpful. I've reworked the text here to read:

       The  timeout argument specifies the number of milliseconds that
       epoll_wait() will block.  The call will block until either:

       *  a file descriptor delivers an event;

       *  the call is interrupted by a signal handler; or

       *  the timout expires.

       Note that the timeout 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.  Specifying  a
       timeout  of -1 causes epoll_wait() to block indefinitely, while
       specifying a timeout equal to zero cause epoll_wait() to return
       immediately, even if no events are available.

I've also made similar changes in select(2) and poll(2).

> Since we are on the subject, I also believe that the man page for epoll_wait
> should state whether sequence of the signaled fd's is guaranteed to be
> correlated to the order in which they were specified.

There is not such a guarantee, as far as I know.

> As you know, there are
> many situations where programmer might want to wait on, say, eventfd that
> says that thread should exit, plus four other semaphores, etc. If the four
> other semaphores guard queues that are, in general, never empty, then on
> each loop, the semaphores will be triggered. If then, on one of the loops,
> the eventfd for "exit" is triggered, there is no guarantee, according to the
> man page, that the "exit" eventfd will be returned in the triggered-set. It
> would seem natural that, if the "exit" eventfd is added to the first
> position with epoll_ctl, then of any trigger-set where "exit" eventfd is
> set, that "exit" eventfd ~must~ be included as a matter of explicit
> prioritization. Guaranteeing a correlation between specified order in
> epoll_ctrl and yielded order in epoll_wait would allow the programmer to
> specify maxevents=1 to epoll_wait, at which point, the "exit" eventfd, if
> triggered, would preempt any of the semaphores.
> 
> Or...maybe I am missing something else?

The only guarantee that I know of is that if multiple FDs a ready and 
epoll_wait() requests fewer events than there are FDs ready, then
successive calls will cycle though the list of ready FDs. This helps avoid
starvation.

Cheers,

Michael
> -Nut
> 
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
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