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