Issue #6397: Support '/dev/poll' polling objects in select module, under Solaris & derivatives.

Doc/library/select.rst

@@ -6,7 +6,8 @@
 
 
 This module provides access to the :c:func:`select` and :c:func:`poll` functions
-available in most operating systems, :c:func:`epoll` available on Linux 2.5+ and
+available in most operating systems, :c:func:`devpoll` available on
+Solaris and derivatives, :c:func:`epoll` available on Linux 2.5+ and
 :c:func:`kqueue` available on most BSD.
 Note that on Windows, it only works for sockets; on other operating systems,
 it also works for other file types (in particular, on Unix, it works on pipes).
@@ -24,6 +25,19 @@ The module defines the following:
       Following :pep:`3151`, this class was made an alias of :exc:`OSError`.
 
 
+.. function:: devpoll()
+   (Only supported on Solaris and derivatives.)  Returns a ``/dev/poll``
+   polling object; see section :ref:`devpoll-objects` below for the
+   methods supported by devpoll objects.
+
+   :c:func:`devpoll` objects are linked to the number of file
+   descriptors allowed at the time of instantiation. If your program
+   reduces this value, :c:func:`devpoll` will fail. If your program
+   increases this value, c:func:`devpoll` may return an
+   incomplete list of active file descriptors.
+
+   .. versionadded:: 3.3
+
 .. function:: epoll(sizehint=-1)
 
    (Only supported on Linux 2.5.44 and newer.)  Returns an edge polling object,
@@ -107,6 +121,74 @@ The module defines the following:
    .. versionadded:: 3.2
 
 
+.. _devpoll-objects:
+
+``/dev/poll`` Polling Objects
+----------------------------------------------
+
+   http://developers.sun.com/solaris/articles/using_devpoll.html
+   http://developers.sun.com/solaris/articles/polling_efficient.html
+
+Solaris and derivatives have ``/dev/poll``. While :c:func:`select` is
+O(highest file descriptor) and :c:func:`poll` is O(number of file
+descriptors), ``/dev/poll`` is O(active file descriptors).
+
+``/dev/poll`` behaviour is very close to the standard :c:func:`poll`
+object.
+
+
+.. method:: devpoll.register(fd[, eventmask])
+
+   Register a file descriptor with the polling object.  Future calls to the
+   :meth:`poll` method will then check whether the file descriptor has any pending
+   I/O events.  *fd* can be either an integer, or an object with a :meth:`fileno`
+   method that returns an integer.  File objects implement :meth:`fileno`, so they
+   can also be used as the argument.
+
+   *eventmask* is an optional bitmask describing the type of events you want to
+   check for. The constants are the same that with :c:func:`poll`
+   object. The default value is a combination of the constants :const:`POLLIN`,
+   :const:`POLLPRI`, and :const:`POLLOUT`.
+
+   .. warning::
+
+      Registering a file descriptor that's already registered is not an
+      error, but the result is undefined. The appropiate action is to
+      unregister or modify it first. This is an important difference
+      compared with :c:func:`poll`.
+
+
+.. method:: devpoll.modify(fd[, eventmask])
+
+   This method does an :meth:`unregister` followed by a
+   :meth:`register`. It is (a bit) more efficient that doing the same
+   explicitly.
+
+
+.. method:: devpoll.unregister(fd)
+
+   Remove a file descriptor being tracked by a polling object.  Just like the
+   :meth:`register` method, *fd* can be an integer or an object with a
+   :meth:`fileno` method that returns an integer.
+
+   Attempting to remove a file descriptor that was never registered is
+   safely ignored.
+
+
+.. method:: devpoll.poll([timeout])
+
+   Polls the set of registered file descriptors, and returns a possibly-empty list
+   containing ``(fd, event)`` 2-tuples for the descriptors that have events or
+   errors to report. *fd* is the file descriptor, and *event* is a bitmask with
+   bits set for the reported events for that descriptor --- :const:`POLLIN` for
+   waiting input, :const:`POLLOUT` to indicate that the descriptor can be written
+   to, and so forth. An empty list indicates that the call timed out and no file
+   descriptors had any events to report. If *timeout* is given, it specifies the
+   length of time in milliseconds which the system will wait for events before
+   returning. If *timeout* is omitted, -1, or :const:`None`, the call will
+   block until there is an event for this poll object.
+
+
 .. _epoll-objects:
 
 Edge and Level Trigger Polling (epoll) Objects

Lib/test/test_devpoll.py

+# Test case for the select.devpoll() function
+
+# Initial tests are copied as is from "test_poll.py"
+
+import os, select, random, unittest, sys
+from test.support import TESTFN, run_unittest
+
+try:
+    select.devpoll
+except AttributeError:
+    raise unittest.SkipTest("select.devpoll not defined -- skipping test_devpoll")
+
+
+def find_ready_matching(ready, flag):
+    match = []
+    for fd, mode in ready:
+        if mode & flag:
+            match.append(fd)
+    return match
+
+class DevPollTests(unittest.TestCase):
+
+    def test_devpoll1(self):
+        # Basic functional test of poll object
+        # Create a bunch of pipe and test that poll works with them.
+
+        p = select.devpoll()
+
+        NUM_PIPES = 12
+        MSG = b" This is a test."
+        MSG_LEN = len(MSG)
+        readers = []
+        writers = []
+        r2w = {}
+        w2r = {}
+
+        for i in range(NUM_PIPES):
+            rd, wr = os.pipe()
+            p.register(rd)
+            p.modify(rd, select.POLLIN)
+            p.register(wr, select.POLLOUT)
+            readers.append(rd)
+            writers.append(wr)
+            r2w[rd] = wr
+            w2r[wr] = rd
+
+        bufs = []
+
+        while writers:
+            ready = p.poll()
+            ready_writers = find_ready_matching(ready, select.POLLOUT)
+            if not ready_writers:
+                self.fail("no pipes ready for writing")
+            wr = random.choice(ready_writers)
+            os.write(wr, MSG)
+
+            ready = p.poll()
+            ready_readers = find_ready_matching(ready, select.POLLIN)
+            if not ready_readers:
+                self.fail("no pipes ready for reading")
+            self.assertEqual([w2r[wr]], ready_readers)
+            rd = ready_readers[0]
+            buf = os.read(rd, MSG_LEN)
+            self.assertEqual(len(buf), MSG_LEN)
+            bufs.append(buf)
+            os.close(r2w[rd]) ; os.close(rd)
+            p.unregister(r2w[rd])
+            p.unregister(rd)
+            writers.remove(r2w[rd])
+
+        self.assertEqual(bufs, [MSG] * NUM_PIPES)
+
+    def test_timeout_overflow(self):
+        pollster = select.devpoll()
+        w, r = os.pipe()
+        pollster.register(w)
+
+        pollster.poll(-1)
+        self.assertRaises(OverflowError, pollster.poll, -2)
+        self.assertRaises(OverflowError, pollster.poll, -1 << 31)
+        self.assertRaises(OverflowError, pollster.poll, -1 << 64)
+
+        pollster.poll(0)
+        pollster.poll(1)
+        pollster.poll(1 << 30)
+        self.assertRaises(OverflowError, pollster.poll, 1 << 31)
+        self.assertRaises(OverflowError, pollster.poll, 1 << 63)
+        self.assertRaises(OverflowError, pollster.poll, 1 << 64)
+
+def test_main():
+    run_unittest(DevPollTests)
+
+if __name__ == '__main__':
+    test_main()

Misc/NEWS

@@ -365,6 +365,9 @@ Core and Builtins
 Library
 -------
 
+- Issue #6397: Support "/dev/poll" polling objects in select module,
+  under Solaris & derivatives.
+
 - Issues #1745761, #755670, #13357, #12629, #1200313: HTMLParser now correctly
   handles non-valid attributes, including adjacent and unquoted attributes.
 

configure

@@ -6139,12 +6139,13 @@ fi
 
 for ac_header in asm/types.h conio.h curses.h direct.h dlfcn.h errno.h \
 fcntl.h grp.h \
-ieeefp.h io.h langinfo.h libintl.h ncurses.h poll.h process.h pthread.h \
+ieeefp.h io.h langinfo.h libintl.h ncurses.h process.h pthread.h \
 sched.h shadow.h signal.h stdint.h stropts.h termios.h \
 unistd.h utime.h \
-sys/audioio.h sys/xattr.h sys/bsdtty.h sys/epoll.h sys/event.h sys/file.h sys/loadavg.h \
+poll.h sys/devpoll.h sys/epoll.h sys/poll.h \
+sys/audioio.h sys/xattr.h sys/bsdtty.h sys/event.h sys/file.h sys/loadavg.h \
 sys/lock.h sys/mkdev.h sys/modem.h \
-sys/param.h sys/poll.h sys/select.h sys/sendfile.h sys/socket.h sys/statvfs.h \
+sys/param.h sys/select.h sys/sendfile.h sys/socket.h sys/statvfs.h \
 sys/stat.h sys/termio.h sys/time.h \
 sys/times.h sys/types.h sys/uio.h sys/un.h sys/utsname.h sys/wait.h pty.h \
 libutil.h sys/resource.h netpacket/packet.h sysexits.h bluetooth.h \

configure.in

@@ -1329,12 +1329,13 @@ dnl AC_MSG_RESULT($cpp_type)
 AC_HEADER_STDC
 AC_CHECK_HEADERS(asm/types.h conio.h curses.h direct.h dlfcn.h errno.h \
 fcntl.h grp.h \
-ieeefp.h io.h langinfo.h libintl.h ncurses.h poll.h process.h pthread.h \
+ieeefp.h io.h langinfo.h libintl.h ncurses.h process.h pthread.h \
 sched.h shadow.h signal.h stdint.h stropts.h termios.h \
 unistd.h utime.h \
-sys/audioio.h sys/xattr.h sys/bsdtty.h sys/epoll.h sys/event.h sys/file.h sys/loadavg.h \
+poll.h sys/devpoll.h sys/epoll.h sys/poll.h \
+sys/audioio.h sys/xattr.h sys/bsdtty.h sys/event.h sys/file.h sys/loadavg.h \
 sys/lock.h sys/mkdev.h sys/modem.h \
-sys/param.h sys/poll.h sys/select.h sys/sendfile.h sys/socket.h sys/statvfs.h \
+sys/param.h sys/select.h sys/sendfile.h sys/socket.h sys/statvfs.h \
 sys/stat.h sys/termio.h sys/time.h \
 sys/times.h sys/types.h sys/uio.h sys/un.h sys/utsname.h sys/wait.h pty.h \
 libutil.h sys/resource.h netpacket/packet.h sysexits.h bluetooth.h \

pyconfig.h.in

@@ -883,6 +883,9 @@
 /* Define to 1 if you have the <sys/bsdtty.h> header file. */
 #undef HAVE_SYS_BSDTTY_H
 
+/* Define to 1 if you have the <sys/devpoll.h> header file. */
+#undef HAVE_SYS_DEVPOLL_H
+
 /* Define to 1 if you have the <sys/dir.h> header file, and it defines `DIR'.
    */
 #undef HAVE_SYS_DIR_H