Bug 43072 (epoll_threads)

Summary:	epoll & threads
Product:	Documentation	Reporter:	Armin Rigo (arigo)
Component:	man-pages	Assignee:	Michael Kerrisk (mtk.manpages)
Status:	RESOLVED CODE_FIX
Severity:	normal	CC:	mtk.manpages
Priority:	P1
Hardware:	All
OS:	Linux
Kernel Version:	n/a	Subsystem:
Regression:	No	Bisected commit-id:

Description Armin Rigo 2012-04-08 11:49:58 UTC

The manpages of epoll do not mention the behavior in the presence of multiple threads.  By trying it out, I found out that the following works: if one thread does epoll_wait() on an epoll in which some fd was not registered at all, and blocks; and later another thread does epoll_ctl() to add the fd; then the fd will be reported by the original thread's epoll_wait() as soon as it meets the condition.  This behavior is something that may be very useful in some situations.  As far as I see, it cannot be achieved easily with select().  I think that it should be officially mentioned in the manpages (provided it is not an accident but works this way by design).

Comment 1 Michael Kerrisk 2012-04-14 19:56:10 UTC

Thanks for the report. You are right that it's useful and cannot be achieved with select(2) and poll(2).


I added the following to epoll_wait(2):

--- a/man2/epoll_wait.2
+++ b/man2/epoll_wait.2
@@ -183,6 +183,16 @@ Library support is provided in glibc starting with version 2.6.
 .SH CONFORMING TO
 .BR epoll_wait ()
 is Linux-specific.
+.SH NOTES
+While one thread is blocked in a call to
+.BR epoll_pwait (),
+it is possible for another thread to add a file descriptor to the waited-upon
+.B epoll
+instance.
+If the new file descriptor becomes ready,
+it will cause the
+.BR epoll_wait ()
+call to unblock.
 .SH "SEE ALSO"
 .BR epoll_create (2),
 .BR epoll_ctl (2),