Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`select` --- Waiting for I/O completion |
| 2 | ============================================ |
| 3 | |
| 4 | .. module:: select |
| 5 | :synopsis: Wait for I/O completion on multiple streams. |
| 6 | |
| 7 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 8 | This module provides access to the :c:func:`select` and :c:func:`poll` functions |
Jesus Cea | d8b9ae6 | 2011-11-14 19:07:41 +0100 | [diff] [blame] | 9 | available in most operating systems, :c:func:`devpoll` available on |
| 10 | Solaris and derivatives, :c:func:`epoll` available on Linux 2.5+ and |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 11 | :c:func:`kqueue` available on most BSD. |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 12 | Note that on Windows, it only works for sockets; on other operating systems, |
| 13 | it also works for other file types (in particular, on Unix, it works on pipes). |
| 14 | It cannot be used on regular files to determine whether a file has grown since |
| 15 | it was last read. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 16 | |
Victor Stinner | 73821c4 | 2013-09-04 20:40:13 +0200 | [diff] [blame] | 17 | .. note:: |
| 18 | |
| 19 | The :mod:`selectors` module allows high-level and efficient I/O |
| 20 | multiplexing, built upon the :mod:`select` module primitives. Users are |
| 21 | encouraged to use the :mod:`selectors` module instead, unless they want |
| 22 | precise control over the OS-level primitives used. |
| 23 | |
| 24 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 25 | The module defines the following: |
| 26 | |
| 27 | |
| 28 | .. exception:: error |
| 29 | |
Antoine Pitrou | 9b7fcf8 | 2011-10-12 16:23:02 +0200 | [diff] [blame] | 30 | A deprecated alias of :exc:`OSError`. |
| 31 | |
| 32 | .. versionchanged:: 3.3 |
| 33 | Following :pep:`3151`, this class was made an alias of :exc:`OSError`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 34 | |
| 35 | |
Jesus Cea | d8b9ae6 | 2011-11-14 19:07:41 +0100 | [diff] [blame] | 36 | .. function:: devpoll() |
Jesus Cea | f450c1b | 2011-11-15 05:42:59 +0100 | [diff] [blame] | 37 | |
Jesus Cea | d8b9ae6 | 2011-11-14 19:07:41 +0100 | [diff] [blame] | 38 | (Only supported on Solaris and derivatives.) Returns a ``/dev/poll`` |
| 39 | polling object; see section :ref:`devpoll-objects` below for the |
| 40 | methods supported by devpoll objects. |
| 41 | |
| 42 | :c:func:`devpoll` objects are linked to the number of file |
| 43 | descriptors allowed at the time of instantiation. If your program |
| 44 | reduces this value, :c:func:`devpoll` will fail. If your program |
Jesus Cea | f450c1b | 2011-11-15 05:42:59 +0100 | [diff] [blame] | 45 | increases this value, :c:func:`devpoll` may return an |
Jesus Cea | d8b9ae6 | 2011-11-14 19:07:41 +0100 | [diff] [blame] | 46 | incomplete list of active file descriptors. |
| 47 | |
Victor Stinner | daf4555 | 2013-08-28 00:53:59 +0200 | [diff] [blame] | 48 | The new file descriptor is :ref:`non-inheritable <fd_inheritance>`. |
| 49 | |
Jesus Cea | d8b9ae6 | 2011-11-14 19:07:41 +0100 | [diff] [blame] | 50 | .. versionadded:: 3.3 |
| 51 | |
Victor Stinner | daf4555 | 2013-08-28 00:53:59 +0200 | [diff] [blame] | 52 | .. versionchanged:: 3.4 |
| 53 | The new file descriptor is now non-inheritable. |
| 54 | |
Benjamin Peterson | 2fb9ae9 | 2011-12-27 15:15:41 -0600 | [diff] [blame] | 55 | .. function:: epoll(sizehint=-1, flags=0) |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 56 | |
Benjamin Peterson | 2fb9ae9 | 2011-12-27 15:15:41 -0600 | [diff] [blame] | 57 | (Only supported on Linux 2.5.44 and newer.) Return an edge polling object, |
| 58 | which can be used as Edge or Level Triggered interface for I/O |
| 59 | events. *sizehint* is deprecated and completely ignored. *flags* can be set |
| 60 | to :const:`EPOLL_CLOEXEC`, which causes the epoll descriptor to be closed |
R David Murray | 2bc930f | 2013-12-31 11:17:21 -0500 | [diff] [blame] | 61 | automatically when :func:`os.execve` is called. |
| 62 | |
| 63 | See the :ref:`epoll-objects` section below for the methods supported by |
| 64 | epolling objects. |
| 65 | |
| 66 | ``epoll`` objects support the context management protocol: when used in a |
| 67 | :keyword:`with` statement, the new file descriptor is automatically closed |
| 68 | at the end of the block. |
Benjamin Peterson | 2fb9ae9 | 2011-12-27 15:15:41 -0600 | [diff] [blame] | 69 | |
Victor Stinner | daf4555 | 2013-08-28 00:53:59 +0200 | [diff] [blame] | 70 | The new file descriptor is :ref:`non-inheritable <fd_inheritance>`. |
| 71 | |
Benjamin Peterson | 2fb9ae9 | 2011-12-27 15:15:41 -0600 | [diff] [blame] | 72 | .. versionchanged:: 3.3 |
Benjamin Peterson | 2fb9ae9 | 2011-12-27 15:15:41 -0600 | [diff] [blame] | 73 | Added the *flags* parameter. |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 74 | |
Antoine Pitrou | 09bb89b | 2012-12-15 21:14:21 +0100 | [diff] [blame] | 75 | .. versionchanged:: 3.4 |
| 76 | Support for the :keyword:`with` statement was added. |
Victor Stinner | daf4555 | 2013-08-28 00:53:59 +0200 | [diff] [blame] | 77 | The new file descriptor is now non-inheritable. |
Antoine Pitrou | 09bb89b | 2012-12-15 21:14:21 +0100 | [diff] [blame] | 78 | |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 79 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 80 | .. function:: poll() |
| 81 | |
| 82 | (Not supported by all operating systems.) Returns a polling object, which |
| 83 | supports registering and unregistering file descriptors, and then polling them |
| 84 | for I/O events; see section :ref:`poll-objects` below for the methods supported |
| 85 | by polling objects. |
| 86 | |
| 87 | |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 88 | .. function:: kqueue() |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 89 | |
Georg Brandl | e767e04 | 2010-07-14 08:00:22 +0000 | [diff] [blame] | 90 | (Only supported on BSD.) Returns a kernel queue object; see section |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 91 | :ref:`kqueue-objects` below for the methods supported by kqueue objects. |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 92 | |
Victor Stinner | daf4555 | 2013-08-28 00:53:59 +0200 | [diff] [blame] | 93 | The new file descriptor is :ref:`non-inheritable <fd_inheritance>`. |
| 94 | |
| 95 | .. versionchanged:: 3.4 |
| 96 | The new file descriptor is now non-inheritable. |
| 97 | |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 98 | |
Benjamin Peterson | 1baf465 | 2009-12-31 03:11:23 +0000 | [diff] [blame] | 99 | .. function:: kevent(ident, filter=KQ_FILTER_READ, flags=KQ_EV_ADD, fflags=0, data=0, udata=0) |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 100 | |
Georg Brandl | e767e04 | 2010-07-14 08:00:22 +0000 | [diff] [blame] | 101 | (Only supported on BSD.) Returns a kernel event object; see section |
| 102 | :ref:`kevent-objects` below for the methods supported by kevent objects. |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 103 | |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 104 | |
Georg Brandl | 734e268 | 2008-08-12 08:18:18 +0000 | [diff] [blame] | 105 | .. function:: select(rlist, wlist, xlist[, timeout]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 106 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 107 | This is a straightforward interface to the Unix :c:func:`select` system call. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 108 | The first three arguments are sequences of 'waitable objects': either |
| 109 | integers representing file descriptors or objects with a parameterless method |
Serhiy Storchaka | 9e0ae53 | 2013-08-24 00:23:38 +0300 | [diff] [blame] | 110 | named :meth:`~io.IOBase.fileno` returning such an integer: |
Georg Brandl | 734e268 | 2008-08-12 08:18:18 +0000 | [diff] [blame] | 111 | |
| 112 | * *rlist*: wait until ready for reading |
| 113 | * *wlist*: wait until ready for writing |
| 114 | * *xlist*: wait for an "exceptional condition" (see the manual page for what |
| 115 | your system considers such a condition) |
| 116 | |
| 117 | Empty sequences are allowed, but acceptance of three empty sequences is |
| 118 | platform-dependent. (It is known to work on Unix but not on Windows.) The |
| 119 | optional *timeout* argument specifies a time-out as a floating point number |
| 120 | in seconds. When the *timeout* argument is omitted the function blocks until |
| 121 | at least one file descriptor is ready. A time-out value of zero specifies a |
| 122 | poll and never blocks. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 123 | |
| 124 | The return value is a triple of lists of objects that are ready: subsets of the |
| 125 | first three arguments. When the time-out is reached without a file descriptor |
| 126 | becoming ready, three empty lists are returned. |
| 127 | |
| 128 | .. index:: |
| 129 | single: socket() (in module socket) |
| 130 | single: popen() (in module os) |
| 131 | |
Antoine Pitrou | 11cb961 | 2010-09-15 11:11:28 +0000 | [diff] [blame] | 132 | Among the acceptable object types in the sequences are Python :term:`file |
| 133 | objects <file object>` (e.g. ``sys.stdin``, or objects returned by |
| 134 | :func:`open` or :func:`os.popen`), socket objects returned by |
| 135 | :func:`socket.socket`. You may also define a :dfn:`wrapper` class yourself, |
Serhiy Storchaka | 9e0ae53 | 2013-08-24 00:23:38 +0300 | [diff] [blame] | 136 | as long as it has an appropriate :meth:`~io.IOBase.fileno` method (that |
| 137 | really returns a file descriptor, not just a random integer). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 138 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 139 | .. note:: |
| 140 | |
| 141 | .. index:: single: WinSock |
| 142 | |
Georg Brandl | 734e268 | 2008-08-12 08:18:18 +0000 | [diff] [blame] | 143 | File objects on Windows are not acceptable, but sockets are. On Windows, |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 144 | the underlying :c:func:`select` function is provided by the WinSock |
Georg Brandl | 734e268 | 2008-08-12 08:18:18 +0000 | [diff] [blame] | 145 | library, and does not handle file descriptors that don't originate from |
| 146 | WinSock. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 147 | |
Antoine Pitrou | cfad97b | 2011-01-25 17:24:57 +0000 | [diff] [blame] | 148 | .. attribute:: PIPE_BUF |
Gregory P. Smith | b970b86 | 2009-07-04 02:28:47 +0000 | [diff] [blame] | 149 | |
Antoine Pitrou | da7be3e | 2011-01-25 16:28:44 +0000 | [diff] [blame] | 150 | The minimum number of bytes which can be written without blocking to a pipe |
Serhiy Storchaka | 9e0ae53 | 2013-08-24 00:23:38 +0300 | [diff] [blame] | 151 | when the pipe has been reported as ready for writing by :func:`~select.select`, |
Antoine Pitrou | da7be3e | 2011-01-25 16:28:44 +0000 | [diff] [blame] | 152 | :func:`poll` or another interface in this module. This doesn't apply |
| 153 | to other kind of file-like objects such as sockets. |
| 154 | |
Amaury Forgeot d'Arc | ace3102 | 2009-07-09 22:44:11 +0000 | [diff] [blame] | 155 | This value is guaranteed by POSIX to be at least 512. Availability: Unix. |
Gregory P. Smith | b970b86 | 2009-07-04 02:28:47 +0000 | [diff] [blame] | 156 | |
Mark Dickinson | 574b1d6 | 2009-10-01 20:20:09 +0000 | [diff] [blame] | 157 | .. versionadded:: 3.2 |
Gregory P. Smith | b970b86 | 2009-07-04 02:28:47 +0000 | [diff] [blame] | 158 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 159 | |
Jesus Cea | d8b9ae6 | 2011-11-14 19:07:41 +0100 | [diff] [blame] | 160 | .. _devpoll-objects: |
| 161 | |
| 162 | ``/dev/poll`` Polling Objects |
Georg Brandl | 525d355 | 2014-10-29 10:26:56 +0100 | [diff] [blame] | 163 | ----------------------------- |
Jesus Cea | d8b9ae6 | 2011-11-14 19:07:41 +0100 | [diff] [blame] | 164 | |
| 165 | Solaris and derivatives have ``/dev/poll``. While :c:func:`select` is |
| 166 | O(highest file descriptor) and :c:func:`poll` is O(number of file |
| 167 | descriptors), ``/dev/poll`` is O(active file descriptors). |
| 168 | |
| 169 | ``/dev/poll`` behaviour is very close to the standard :c:func:`poll` |
| 170 | object. |
| 171 | |
| 172 | |
Victor Stinner | 13423c3 | 2013-08-22 00:19:50 +0200 | [diff] [blame] | 173 | .. method:: devpoll.close() |
| 174 | |
| 175 | Close the file descriptor of the polling object. |
| 176 | |
| 177 | .. versionadded:: 3.4 |
| 178 | |
| 179 | |
| 180 | .. attribute:: devpoll.closed |
| 181 | |
| 182 | ``True`` if the polling object is closed. |
| 183 | |
| 184 | .. versionadded:: 3.4 |
| 185 | |
| 186 | |
| 187 | .. method:: devpoll.fileno() |
| 188 | |
| 189 | Return the file descriptor number of the polling object. |
| 190 | |
| 191 | .. versionadded:: 3.4 |
| 192 | |
| 193 | |
Jesus Cea | d8b9ae6 | 2011-11-14 19:07:41 +0100 | [diff] [blame] | 194 | .. method:: devpoll.register(fd[, eventmask]) |
| 195 | |
| 196 | Register a file descriptor with the polling object. Future calls to the |
Serhiy Storchaka | 9e0ae53 | 2013-08-24 00:23:38 +0300 | [diff] [blame] | 197 | :meth:`poll` method will then check whether the file descriptor has any |
| 198 | pending I/O events. *fd* can be either an integer, or an object with a |
| 199 | :meth:`~io.IOBase.fileno` method that returns an integer. File objects |
| 200 | implement :meth:`!fileno`, so they can also be used as the argument. |
Jesus Cea | d8b9ae6 | 2011-11-14 19:07:41 +0100 | [diff] [blame] | 201 | |
| 202 | *eventmask* is an optional bitmask describing the type of events you want to |
| 203 | check for. The constants are the same that with :c:func:`poll` |
| 204 | object. The default value is a combination of the constants :const:`POLLIN`, |
| 205 | :const:`POLLPRI`, and :const:`POLLOUT`. |
| 206 | |
| 207 | .. warning:: |
| 208 | |
| 209 | Registering a file descriptor that's already registered is not an |
| 210 | error, but the result is undefined. The appropiate action is to |
| 211 | unregister or modify it first. This is an important difference |
| 212 | compared with :c:func:`poll`. |
| 213 | |
| 214 | |
| 215 | .. method:: devpoll.modify(fd[, eventmask]) |
| 216 | |
| 217 | This method does an :meth:`unregister` followed by a |
| 218 | :meth:`register`. It is (a bit) more efficient that doing the same |
| 219 | explicitly. |
| 220 | |
| 221 | |
| 222 | .. method:: devpoll.unregister(fd) |
| 223 | |
| 224 | Remove a file descriptor being tracked by a polling object. Just like the |
| 225 | :meth:`register` method, *fd* can be an integer or an object with a |
Serhiy Storchaka | 9e0ae53 | 2013-08-24 00:23:38 +0300 | [diff] [blame] | 226 | :meth:`~io.IOBase.fileno` method that returns an integer. |
Jesus Cea | d8b9ae6 | 2011-11-14 19:07:41 +0100 | [diff] [blame] | 227 | |
| 228 | Attempting to remove a file descriptor that was never registered is |
| 229 | safely ignored. |
| 230 | |
| 231 | |
| 232 | .. method:: devpoll.poll([timeout]) |
| 233 | |
| 234 | Polls the set of registered file descriptors, and returns a possibly-empty list |
| 235 | containing ``(fd, event)`` 2-tuples for the descriptors that have events or |
| 236 | errors to report. *fd* is the file descriptor, and *event* is a bitmask with |
| 237 | bits set for the reported events for that descriptor --- :const:`POLLIN` for |
| 238 | waiting input, :const:`POLLOUT` to indicate that the descriptor can be written |
| 239 | to, and so forth. An empty list indicates that the call timed out and no file |
| 240 | descriptors had any events to report. If *timeout* is given, it specifies the |
| 241 | length of time in milliseconds which the system will wait for events before |
| 242 | returning. If *timeout* is omitted, -1, or :const:`None`, the call will |
| 243 | block until there is an event for this poll object. |
| 244 | |
| 245 | |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 246 | .. _epoll-objects: |
| 247 | |
| 248 | Edge and Level Trigger Polling (epoll) Objects |
| 249 | ---------------------------------------------- |
| 250 | |
| 251 | http://linux.die.net/man/4/epoll |
| 252 | |
| 253 | *eventmask* |
| 254 | |
| 255 | +-----------------------+-----------------------------------------------+ |
| 256 | | Constant | Meaning | |
| 257 | +=======================+===============================================+ |
| 258 | | :const:`EPOLLIN` | Available for read | |
| 259 | +-----------------------+-----------------------------------------------+ |
| 260 | | :const:`EPOLLOUT` | Available for write | |
| 261 | +-----------------------+-----------------------------------------------+ |
| 262 | | :const:`EPOLLPRI` | Urgent data for read | |
| 263 | +-----------------------+-----------------------------------------------+ |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 264 | | :const:`EPOLLERR` | Error condition happened on the assoc. fd | |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 265 | +-----------------------+-----------------------------------------------+ |
Christian Heimes | 5e69685 | 2008-04-09 08:37:03 +0000 | [diff] [blame] | 266 | | :const:`EPOLLHUP` | Hang up happened on the assoc. fd | |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 267 | +-----------------------+-----------------------------------------------+ |
| 268 | | :const:`EPOLLET` | Set Edge Trigger behavior, the default is | |
| 269 | | | Level Trigger behavior | |
| 270 | +-----------------------+-----------------------------------------------+ |
| 271 | | :const:`EPOLLONESHOT` | Set one-shot behavior. After one event is | |
| 272 | | | pulled out, the fd is internally disabled | |
| 273 | +-----------------------+-----------------------------------------------+ |
Jean-Paul Calderone | 7f54dce | 2010-07-18 16:30:31 +0000 | [diff] [blame] | 274 | | :const:`EPOLLRDNORM` | Equivalent to :const:`EPOLLIN` | |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 275 | +-----------------------+-----------------------------------------------+ |
Jean-Paul Calderone | 7f54dce | 2010-07-18 16:30:31 +0000 | [diff] [blame] | 276 | | :const:`EPOLLRDBAND` | Priority data band can be read. | |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 277 | +-----------------------+-----------------------------------------------+ |
Jean-Paul Calderone | 7f54dce | 2010-07-18 16:30:31 +0000 | [diff] [blame] | 278 | | :const:`EPOLLWRNORM` | Equivalent to :const:`EPOLLOUT` | |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 279 | +-----------------------+-----------------------------------------------+ |
Jean-Paul Calderone | 7f54dce | 2010-07-18 16:30:31 +0000 | [diff] [blame] | 280 | | :const:`EPOLLWRBAND` | Priority data may be written. | |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 281 | +-----------------------+-----------------------------------------------+ |
Jean-Paul Calderone | 7f54dce | 2010-07-18 16:30:31 +0000 | [diff] [blame] | 282 | | :const:`EPOLLMSG` | Ignored. | |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 283 | +-----------------------+-----------------------------------------------+ |
| 284 | |
| 285 | |
| 286 | .. method:: epoll.close() |
| 287 | |
| 288 | Close the control file descriptor of the epoll object. |
| 289 | |
| 290 | |
Victor Stinner | 13423c3 | 2013-08-22 00:19:50 +0200 | [diff] [blame] | 291 | .. attribute:: epoll.closed |
| 292 | |
| 293 | ``True`` if the epoll object is closed. |
| 294 | |
| 295 | |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 296 | .. method:: epoll.fileno() |
| 297 | |
| 298 | Return the file descriptor number of the control fd. |
| 299 | |
| 300 | |
| 301 | .. method:: epoll.fromfd(fd) |
| 302 | |
| 303 | Create an epoll object from a given file descriptor. |
| 304 | |
| 305 | |
| 306 | .. method:: epoll.register(fd[, eventmask]) |
| 307 | |
| 308 | Register a fd descriptor with the epoll object. |
| 309 | |
| 310 | |
| 311 | .. method:: epoll.modify(fd, eventmask) |
| 312 | |
Georg Brandl | 632c812 | 2014-01-12 18:03:12 +0100 | [diff] [blame] | 313 | Modify a registered file descriptor. |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 314 | |
| 315 | |
| 316 | .. method:: epoll.unregister(fd) |
| 317 | |
| 318 | Remove a registered file descriptor from the epoll object. |
| 319 | |
| 320 | |
Hynek Schlawack | dfa4652 | 2012-05-21 11:01:54 +0200 | [diff] [blame] | 321 | .. method:: epoll.poll(timeout=-1, maxevents=-1) |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 322 | |
| 323 | Wait for events. timeout in seconds (float) |
| 324 | |
| 325 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 326 | .. _poll-objects: |
| 327 | |
| 328 | Polling Objects |
| 329 | --------------- |
| 330 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 331 | The :c:func:`poll` system call, supported on most Unix systems, provides better |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 332 | scalability for network servers that service many, many clients at the same |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 333 | time. :c:func:`poll` scales better because the system call only requires listing |
| 334 | the file descriptors of interest, while :c:func:`select` builds a bitmap, turns |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 335 | on bits for the fds of interest, and then afterward the whole bitmap has to be |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 336 | linearly scanned again. :c:func:`select` is O(highest file descriptor), while |
| 337 | :c:func:`poll` is O(number of file descriptors). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 338 | |
| 339 | |
| 340 | .. method:: poll.register(fd[, eventmask]) |
| 341 | |
| 342 | Register a file descriptor with the polling object. Future calls to the |
Serhiy Storchaka | 9e0ae53 | 2013-08-24 00:23:38 +0300 | [diff] [blame] | 343 | :meth:`poll` method will then check whether the file descriptor has any |
| 344 | pending I/O events. *fd* can be either an integer, or an object with a |
| 345 | :meth:`~io.IOBase.fileno` method that returns an integer. File objects |
| 346 | implement :meth:`!fileno`, so they can also be used as the argument. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 347 | |
| 348 | *eventmask* is an optional bitmask describing the type of events you want to |
| 349 | check for, and can be a combination of the constants :const:`POLLIN`, |
| 350 | :const:`POLLPRI`, and :const:`POLLOUT`, described in the table below. If not |
| 351 | specified, the default value used will check for all 3 types of events. |
| 352 | |
| 353 | +-------------------+------------------------------------------+ |
| 354 | | Constant | Meaning | |
| 355 | +===================+==========================================+ |
| 356 | | :const:`POLLIN` | There is data to read | |
| 357 | +-------------------+------------------------------------------+ |
| 358 | | :const:`POLLPRI` | There is urgent data to read | |
| 359 | +-------------------+------------------------------------------+ |
| 360 | | :const:`POLLOUT` | Ready for output: writing will not block | |
| 361 | +-------------------+------------------------------------------+ |
| 362 | | :const:`POLLERR` | Error condition of some sort | |
| 363 | +-------------------+------------------------------------------+ |
| 364 | | :const:`POLLHUP` | Hung up | |
| 365 | +-------------------+------------------------------------------+ |
| 366 | | :const:`POLLNVAL` | Invalid request: descriptor not open | |
| 367 | +-------------------+------------------------------------------+ |
| 368 | |
| 369 | Registering a file descriptor that's already registered is not an error, and has |
| 370 | the same effect as registering the descriptor exactly once. |
| 371 | |
| 372 | |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 373 | .. method:: poll.modify(fd, eventmask) |
| 374 | |
| 375 | Modifies an already registered fd. This has the same effect as |
Jean-Paul Calderone | 7f94f39 | 2010-07-18 16:13:27 +0000 | [diff] [blame] | 376 | ``register(fd, eventmask)``. Attempting to modify a file descriptor |
Andrew Svetlov | 050f9ea | 2014-04-01 00:23:23 +0300 | [diff] [blame] | 377 | that was never registered causes an :exc:`OSError` exception with errno |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 378 | :const:`ENOENT` to be raised. |
| 379 | |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 380 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 381 | .. method:: poll.unregister(fd) |
| 382 | |
| 383 | Remove a file descriptor being tracked by a polling object. Just like the |
| 384 | :meth:`register` method, *fd* can be an integer or an object with a |
Serhiy Storchaka | 9e0ae53 | 2013-08-24 00:23:38 +0300 | [diff] [blame] | 385 | :meth:`~io.IOBase.fileno` method that returns an integer. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 386 | |
| 387 | Attempting to remove a file descriptor that was never registered causes a |
| 388 | :exc:`KeyError` exception to be raised. |
| 389 | |
| 390 | |
| 391 | .. method:: poll.poll([timeout]) |
| 392 | |
| 393 | Polls the set of registered file descriptors, and returns a possibly-empty list |
| 394 | containing ``(fd, event)`` 2-tuples for the descriptors that have events or |
| 395 | errors to report. *fd* is the file descriptor, and *event* is a bitmask with |
| 396 | bits set for the reported events for that descriptor --- :const:`POLLIN` for |
| 397 | waiting input, :const:`POLLOUT` to indicate that the descriptor can be written |
| 398 | to, and so forth. An empty list indicates that the call timed out and no file |
| 399 | descriptors had any events to report. If *timeout* is given, it specifies the |
| 400 | length of time in milliseconds which the system will wait for events before |
| 401 | returning. If *timeout* is omitted, negative, or :const:`None`, the call will |
| 402 | block until there is an event for this poll object. |
| 403 | |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 404 | |
| 405 | .. _kqueue-objects: |
| 406 | |
| 407 | Kqueue Objects |
| 408 | -------------- |
| 409 | |
| 410 | .. method:: kqueue.close() |
| 411 | |
| 412 | Close the control file descriptor of the kqueue object. |
| 413 | |
| 414 | |
Victor Stinner | 13423c3 | 2013-08-22 00:19:50 +0200 | [diff] [blame] | 415 | .. attribute:: kqueue.closed |
| 416 | |
| 417 | ``True`` if the kqueue object is closed. |
| 418 | |
| 419 | |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 420 | .. method:: kqueue.fileno() |
| 421 | |
| 422 | Return the file descriptor number of the control fd. |
| 423 | |
| 424 | |
Benjamin Peterson | 9bc9351 | 2008-09-22 22:10:59 +0000 | [diff] [blame] | 425 | .. method:: kqueue.fromfd(fd) |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 426 | |
| 427 | Create a kqueue object from a given file descriptor. |
| 428 | |
| 429 | |
Hynek Schlawack | 979f37a | 2012-05-22 16:12:18 +0200 | [diff] [blame] | 430 | .. method:: kqueue.control(changelist, max_events[, timeout=None]) -> eventlist |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 431 | |
| 432 | Low level interface to kevent |
| 433 | |
| 434 | - changelist must be an iterable of kevent object or None |
| 435 | - max_events must be 0 or a positive integer |
| 436 | - timeout in seconds (floats possible) |
| 437 | |
| 438 | |
| 439 | .. _kevent-objects: |
| 440 | |
| 441 | Kevent Objects |
| 442 | -------------- |
| 443 | |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 444 | http://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2 |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 445 | |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 446 | .. attribute:: kevent.ident |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 447 | |
| 448 | Value used to identify the event. The interpretation depends on the filter |
| 449 | but it's usually the file descriptor. In the constructor ident can either |
Serhiy Storchaka | 9e0ae53 | 2013-08-24 00:23:38 +0300 | [diff] [blame] | 450 | be an int or an object with a :meth:`~io.IOBase.fileno` method. kevent |
| 451 | stores the integer internally. |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 452 | |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 453 | .. attribute:: kevent.filter |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 454 | |
Georg Brandl | 1b5ab45 | 2009-08-13 07:56:35 +0000 | [diff] [blame] | 455 | Name of the kernel filter. |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 456 | |
| 457 | +---------------------------+---------------------------------------------+ |
| 458 | | Constant | Meaning | |
| 459 | +===========================+=============================================+ |
| 460 | | :const:`KQ_FILTER_READ` | Takes a descriptor and returns whenever | |
| 461 | | | there is data available to read | |
| 462 | +---------------------------+---------------------------------------------+ |
| 463 | | :const:`KQ_FILTER_WRITE` | Takes a descriptor and returns whenever | |
Georg Brandl | 1b5ab45 | 2009-08-13 07:56:35 +0000 | [diff] [blame] | 464 | | | there is data available to write | |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 465 | +---------------------------+---------------------------------------------+ |
| 466 | | :const:`KQ_FILTER_AIO` | AIO requests | |
| 467 | +---------------------------+---------------------------------------------+ |
| 468 | | :const:`KQ_FILTER_VNODE` | Returns when one or more of the requested | |
| 469 | | | events watched in *fflag* occurs | |
| 470 | +---------------------------+---------------------------------------------+ |
| 471 | | :const:`KQ_FILTER_PROC` | Watch for events on a process id | |
| 472 | +---------------------------+---------------------------------------------+ |
| 473 | | :const:`KQ_FILTER_NETDEV` | Watch for events on a network device | |
| 474 | | | [not available on Mac OS X] | |
| 475 | +---------------------------+---------------------------------------------+ |
| 476 | | :const:`KQ_FILTER_SIGNAL` | Returns whenever the watched signal is | |
| 477 | | | delivered to the process | |
| 478 | +---------------------------+---------------------------------------------+ |
| 479 | | :const:`KQ_FILTER_TIMER` | Establishes an arbitrary timer | |
| 480 | +---------------------------+---------------------------------------------+ |
| 481 | |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 482 | .. attribute:: kevent.flags |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 483 | |
Georg Brandl | 1b5ab45 | 2009-08-13 07:56:35 +0000 | [diff] [blame] | 484 | Filter action. |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 485 | |
| 486 | +---------------------------+---------------------------------------------+ |
| 487 | | Constant | Meaning | |
| 488 | +===========================+=============================================+ |
| 489 | | :const:`KQ_EV_ADD` | Adds or modifies an event | |
| 490 | +---------------------------+---------------------------------------------+ |
| 491 | | :const:`KQ_EV_DELETE` | Removes an event from the queue | |
| 492 | +---------------------------+---------------------------------------------+ |
| 493 | | :const:`KQ_EV_ENABLE` | Permitscontrol() to returns the event | |
| 494 | +---------------------------+---------------------------------------------+ |
| 495 | | :const:`KQ_EV_DISABLE` | Disablesevent | |
| 496 | +---------------------------+---------------------------------------------+ |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 497 | | :const:`KQ_EV_ONESHOT` | Removes event after first occurrence | |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 498 | +---------------------------+---------------------------------------------+ |
| 499 | | :const:`KQ_EV_CLEAR` | Reset the state after an event is retrieved | |
| 500 | +---------------------------+---------------------------------------------+ |
| 501 | | :const:`KQ_EV_SYSFLAGS` | internal event | |
| 502 | +---------------------------+---------------------------------------------+ |
| 503 | | :const:`KQ_EV_FLAG1` | internal event | |
| 504 | +---------------------------+---------------------------------------------+ |
| 505 | | :const:`KQ_EV_EOF` | Filter specific EOF condition | |
| 506 | +---------------------------+---------------------------------------------+ |
| 507 | | :const:`KQ_EV_ERROR` | See return values | |
| 508 | +---------------------------+---------------------------------------------+ |
| 509 | |
| 510 | |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 511 | .. attribute:: kevent.fflags |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 512 | |
Georg Brandl | 1b5ab45 | 2009-08-13 07:56:35 +0000 | [diff] [blame] | 513 | Filter specific flags. |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 514 | |
Georg Brandl | 1b5ab45 | 2009-08-13 07:56:35 +0000 | [diff] [blame] | 515 | :const:`KQ_FILTER_READ` and :const:`KQ_FILTER_WRITE` filter flags: |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 516 | |
| 517 | +----------------------------+--------------------------------------------+ |
| 518 | | Constant | Meaning | |
| 519 | +============================+============================================+ |
| 520 | | :const:`KQ_NOTE_LOWAT` | low water mark of a socket buffer | |
| 521 | +----------------------------+--------------------------------------------+ |
| 522 | |
Georg Brandl | 1b5ab45 | 2009-08-13 07:56:35 +0000 | [diff] [blame] | 523 | :const:`KQ_FILTER_VNODE` filter flags: |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 524 | |
| 525 | +----------------------------+--------------------------------------------+ |
| 526 | | Constant | Meaning | |
| 527 | +============================+============================================+ |
| 528 | | :const:`KQ_NOTE_DELETE` | *unlink()* was called | |
| 529 | +----------------------------+--------------------------------------------+ |
Georg Brandl | 2ee470f | 2008-07-16 12:55:28 +0000 | [diff] [blame] | 530 | | :const:`KQ_NOTE_WRITE` | a write occurred | |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 531 | +----------------------------+--------------------------------------------+ |
| 532 | | :const:`KQ_NOTE_EXTEND` | the file was extended | |
| 533 | +----------------------------+--------------------------------------------+ |
| 534 | | :const:`KQ_NOTE_ATTRIB` | an attribute was changed | |
| 535 | +----------------------------+--------------------------------------------+ |
| 536 | | :const:`KQ_NOTE_LINK` | the link count has changed | |
| 537 | +----------------------------+--------------------------------------------+ |
| 538 | | :const:`KQ_NOTE_RENAME` | the file was renamed | |
| 539 | +----------------------------+--------------------------------------------+ |
| 540 | | :const:`KQ_NOTE_REVOKE` | access to the file was revoked | |
| 541 | +----------------------------+--------------------------------------------+ |
| 542 | |
Georg Brandl | 1b5ab45 | 2009-08-13 07:56:35 +0000 | [diff] [blame] | 543 | :const:`KQ_FILTER_PROC` filter flags: |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 544 | |
| 545 | +----------------------------+--------------------------------------------+ |
| 546 | | Constant | Meaning | |
| 547 | +============================+============================================+ |
| 548 | | :const:`KQ_NOTE_EXIT` | the process has exited | |
| 549 | +----------------------------+--------------------------------------------+ |
| 550 | | :const:`KQ_NOTE_FORK` | the process has called *fork()* | |
| 551 | +----------------------------+--------------------------------------------+ |
| 552 | | :const:`KQ_NOTE_EXEC` | the process has executed a new process | |
| 553 | +----------------------------+--------------------------------------------+ |
| 554 | | :const:`KQ_NOTE_PCTRLMASK` | internal filter flag | |
| 555 | +----------------------------+--------------------------------------------+ |
| 556 | | :const:`KQ_NOTE_PDATAMASK` | internal filter flag | |
| 557 | +----------------------------+--------------------------------------------+ |
| 558 | | :const:`KQ_NOTE_TRACK` | follow a process across *fork()* | |
| 559 | +----------------------------+--------------------------------------------+ |
| 560 | | :const:`KQ_NOTE_CHILD` | returned on the child process for | |
| 561 | | | *NOTE_TRACK* | |
| 562 | +----------------------------+--------------------------------------------+ |
| 563 | | :const:`KQ_NOTE_TRACKERR` | unable to attach to a child | |
| 564 | +----------------------------+--------------------------------------------+ |
| 565 | |
Georg Brandl | 1b5ab45 | 2009-08-13 07:56:35 +0000 | [diff] [blame] | 566 | :const:`KQ_FILTER_NETDEV` filter flags (not available on Mac OS X): |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 567 | |
| 568 | +----------------------------+--------------------------------------------+ |
| 569 | | Constant | Meaning | |
| 570 | +============================+============================================+ |
| 571 | | :const:`KQ_NOTE_LINKUP` | link is up | |
| 572 | +----------------------------+--------------------------------------------+ |
| 573 | | :const:`KQ_NOTE_LINKDOWN` | link is down | |
| 574 | +----------------------------+--------------------------------------------+ |
| 575 | | :const:`KQ_NOTE_LINKINV` | link state is invalid | |
| 576 | +----------------------------+--------------------------------------------+ |
| 577 | |
| 578 | |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 579 | .. attribute:: kevent.data |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 580 | |
Georg Brandl | 1b5ab45 | 2009-08-13 07:56:35 +0000 | [diff] [blame] | 581 | Filter specific data. |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 582 | |
| 583 | |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 584 | .. attribute:: kevent.udata |
Christian Heimes | 4fbc72b | 2008-03-22 00:47:35 +0000 | [diff] [blame] | 585 | |
Georg Brandl | 1b5ab45 | 2009-08-13 07:56:35 +0000 | [diff] [blame] | 586 | User defined value. |