1 2:mod:`select` --- Waiting for I/O completion 3============================================ 4 5.. module:: select 6 :synopsis: Wait for I/O completion on multiple streams. 7 8 9This module provides access to the :c:func:`select` and :c:func:`poll` functions 10available in most operating systems, :c:func:`epoll` available on Linux 2.5+ and 11:c:func:`kqueue` available on most BSD. 12Note that on Windows, it only works for sockets; on other operating systems, 13it also works for other file types (in particular, on Unix, it works on pipes). 14It cannot be used on regular files to determine whether a file has grown since 15it was last read. 16 17The module defines the following: 18 19 20.. exception:: error 21 22 The exception raised when an error occurs. The accompanying value is a pair 23 containing the numeric error code from :c:data:`errno` and the corresponding 24 string, as would be printed by the C function :c:func:`perror`. 25 26 27.. function:: epoll([sizehint=-1]) 28 29 (Only supported on Linux 2.5.44 and newer.) Returns an edge polling object, 30 which can be used as Edge or Level Triggered interface for I/O events; see 31 section :ref:`epoll-objects` below for the methods supported by epolling 32 objects. 33 34 .. versionadded:: 2.6 35 36 37.. function:: poll() 38 39 (Not supported by all operating systems.) Returns a polling object, which 40 supports registering and unregistering file descriptors, and then polling them 41 for I/O events; see section :ref:`poll-objects` below for the methods supported 42 by polling objects. 43 44 45.. function:: kqueue() 46 47 (Only supported on BSD.) Returns a kernel queue object; see section 48 :ref:`kqueue-objects` below for the methods supported by kqueue objects. 49 50 .. versionadded:: 2.6 51 52 53.. function:: kevent(ident, filter=KQ_FILTER_READ, flags=KQ_EV_ADD, fflags=0, data=0, udata=0) 54 55 (Only supported on BSD.) Returns a kernel event object; see section 56 :ref:`kevent-objects` below for the methods supported by kevent objects. 57 58 .. versionadded:: 2.6 59 60 61.. function:: select(rlist, wlist, xlist[, timeout]) 62 63 This is a straightforward interface to the Unix :c:func:`select` system call. 64 The first three arguments are sequences of 'waitable objects': either 65 integers representing file descriptors or objects with a parameterless method 66 named :meth:`~io.IOBase.fileno` returning such an integer: 67 68 * *rlist*: wait until ready for reading 69 * *wlist*: wait until ready for writing 70 * *xlist*: wait for an "exceptional condition" (see the manual page for what 71 your system considers such a condition) 72 73 Empty sequences are allowed, but acceptance of three empty sequences is 74 platform-dependent. (It is known to work on Unix but not on Windows.) The 75 optional *timeout* argument specifies a time-out as a floating point number 76 in seconds. When the *timeout* argument is omitted the function blocks until 77 at least one file descriptor is ready. A time-out value of zero specifies a 78 poll and never blocks. 79 80 The return value is a triple of lists of objects that are ready: subsets of the 81 first three arguments. When the time-out is reached without a file descriptor 82 becoming ready, three empty lists are returned. 83 84 .. index:: 85 single: socket() (in module socket) 86 single: popen() (in module os) 87 88 Among the acceptable object types in the sequences are Python file objects (e.g. 89 ``sys.stdin``, or objects returned by :func:`open` or :func:`os.popen`), socket 90 objects returned by :func:`socket.socket`. You may also define a :dfn:`wrapper` 91 class yourself, as long as it has an appropriate :meth:`~io.IOBase.fileno` 92 method (that really returns a file descriptor, not just a random integer). 93 94 .. note:: 95 96 .. index:: single: WinSock 97 98 File objects on Windows are not acceptable, but sockets are. On Windows, 99 the underlying :c:func:`select` function is provided by the WinSock 100 library, and does not handle file descriptors that don't originate from 101 WinSock. 102 103.. attribute:: select.PIPE_BUF 104 105 Files reported as ready for writing by :func:`select`, :func:`poll` or 106 similar interfaces in this module are guaranteed to not block on a write 107 of up to :const:`PIPE_BUF` bytes. 108 This value is guaranteed by POSIX to be at least 512. Availability: Unix. 109 110 .. versionadded:: 2.7 111 112 113.. _epoll-objects: 114 115Edge and Level Trigger Polling (epoll) Objects 116---------------------------------------------- 117 118 http://linux.die.net/man/4/epoll 119 120 *eventmask* 121 122 +-----------------------+-----------------------------------------------+ 123 | Constant | Meaning | 124 +=======================+===============================================+ 125 | :const:`EPOLLIN` | Available for read | 126 +-----------------------+-----------------------------------------------+ 127 | :const:`EPOLLOUT` | Available for write | 128 +-----------------------+-----------------------------------------------+ 129 | :const:`EPOLLPRI` | Urgent data for read | 130 +-----------------------+-----------------------------------------------+ 131 | :const:`EPOLLERR` | Error condition happened on the assoc. fd | 132 +-----------------------+-----------------------------------------------+ 133 | :const:`EPOLLHUP` | Hang up happened on the assoc. fd | 134 +-----------------------+-----------------------------------------------+ 135 | :const:`EPOLLET` | Set Edge Trigger behavior, the default is | 136 | | Level Trigger behavior | 137 +-----------------------+-----------------------------------------------+ 138 | :const:`EPOLLONESHOT` | Set one-shot behavior. After one event is | 139 | | pulled out, the fd is internally disabled | 140 +-----------------------+-----------------------------------------------+ 141 | :const:`EPOLLRDNORM` | Equivalent to :const:`EPOLLIN` | 142 +-----------------------+-----------------------------------------------+ 143 | :const:`EPOLLRDBAND` | Priority data band can be read. | 144 +-----------------------+-----------------------------------------------+ 145 | :const:`EPOLLWRNORM` | Equivalent to :const:`EPOLLOUT` | 146 +-----------------------+-----------------------------------------------+ 147 | :const:`EPOLLWRBAND` | Priority data may be written. | 148 +-----------------------+-----------------------------------------------+ 149 | :const:`EPOLLMSG` | Ignored. | 150 +-----------------------+-----------------------------------------------+ 151 152 153.. method:: epoll.close() 154 155 Close the control file descriptor of the epoll object. 156 157 158.. method:: epoll.fileno() 159 160 Return the file descriptor number of the control fd. 161 162 163.. method:: epoll.fromfd(fd) 164 165 Create an epoll object from a given file descriptor. 166 167 168.. method:: epoll.register(fd[, eventmask]) 169 170 Register a fd descriptor with the epoll object. 171 172 .. note:: 173 174 Registering a file descriptor that's already registered raises an 175 IOError -- contrary to :ref:`poll-objects`'s register. 176 177 178.. method:: epoll.modify(fd, eventmask) 179 180 Modify a register file descriptor. 181 182 183.. method:: epoll.unregister(fd) 184 185 Remove a registered file descriptor from the epoll object. 186 187 188.. method:: epoll.poll([timeout=-1[, maxevents=-1]]) 189 190 Wait for events. timeout in seconds (float) 191 192 193.. _poll-objects: 194 195Polling Objects 196--------------- 197 198The :c:func:`poll` system call, supported on most Unix systems, provides better 199scalability for network servers that service many, many clients at the same 200time. :c:func:`poll` scales better because the system call only requires listing 201the file descriptors of interest, while :c:func:`select` builds a bitmap, turns 202on bits for the fds of interest, and then afterward the whole bitmap has to be 203linearly scanned again. :c:func:`select` is O(highest file descriptor), while 204:c:func:`poll` is O(number of file descriptors). 205 206 207.. method:: poll.register(fd[, eventmask]) 208 209 Register a file descriptor with the polling object. Future calls to the 210 :meth:`poll` method will then check whether the file descriptor has any 211 pending I/O events. *fd* can be either an integer, or an object with a 212 :meth:`~io.IOBase.fileno` method that returns an integer. File objects 213 implement :meth:`!fileno`, so they can also be used as the argument. 214 215 *eventmask* is an optional bitmask describing the type of events you want to 216 check for, and can be a combination of the constants :const:`POLLIN`, 217 :const:`POLLPRI`, and :const:`POLLOUT`, described in the table below. If not 218 specified, the default value used will check for all 3 types of events. 219 220 +-------------------+------------------------------------------+ 221 | Constant | Meaning | 222 +===================+==========================================+ 223 | :const:`POLLIN` | There is data to read | 224 +-------------------+------------------------------------------+ 225 | :const:`POLLPRI` | There is urgent data to read | 226 +-------------------+------------------------------------------+ 227 | :const:`POLLOUT` | Ready for output: writing will not block | 228 +-------------------+------------------------------------------+ 229 | :const:`POLLERR` | Error condition of some sort | 230 +-------------------+------------------------------------------+ 231 | :const:`POLLHUP` | Hung up | 232 +-------------------+------------------------------------------+ 233 | :const:`POLLNVAL` | Invalid request: descriptor not open | 234 +-------------------+------------------------------------------+ 235 236 Registering a file descriptor that's already registered is not an error, and has 237 the same effect as registering the descriptor exactly once. 238 239 240.. method:: poll.modify(fd, eventmask) 241 242 Modifies an already registered fd. This has the same effect as 243 ``register(fd, eventmask)``. Attempting to modify a file descriptor 244 that was never registered causes an :exc:`IOError` exception with errno 245 :const:`ENOENT` to be raised. 246 247 .. versionadded:: 2.6 248 249 250.. method:: poll.unregister(fd) 251 252 Remove a file descriptor being tracked by a polling object. Just like the 253 :meth:`register` method, *fd* can be an integer or an object with a 254 :meth:`~io.IOBase.fileno` method that returns an integer. 255 256 Attempting to remove a file descriptor that was never registered causes a 257 :exc:`KeyError` exception to be raised. 258 259 260.. method:: poll.poll([timeout]) 261 262 Polls the set of registered file descriptors, and returns a possibly-empty list 263 containing ``(fd, event)`` 2-tuples for the descriptors that have events or 264 errors to report. *fd* is the file descriptor, and *event* is a bitmask with 265 bits set for the reported events for that descriptor --- :const:`POLLIN` for 266 waiting input, :const:`POLLOUT` to indicate that the descriptor can be written 267 to, and so forth. An empty list indicates that the call timed out and no file 268 descriptors had any events to report. If *timeout* is given, it specifies the 269 length of time in milliseconds which the system will wait for events before 270 returning. If *timeout* is omitted, negative, or :const:`None`, the call will 271 block until there is an event for this poll object. 272 273 274.. _kqueue-objects: 275 276Kqueue Objects 277-------------- 278 279.. method:: kqueue.close() 280 281 Close the control file descriptor of the kqueue object. 282 283 284.. method:: kqueue.fileno() 285 286 Return the file descriptor number of the control fd. 287 288 289.. method:: kqueue.fromfd(fd) 290 291 Create a kqueue object from a given file descriptor. 292 293 294.. method:: kqueue.control(changelist, max_events[, timeout=None]) -> eventlist 295 296 Low level interface to kevent 297 298 - changelist must be an iterable of kevent object or ``None`` 299 - max_events must be 0 or a positive integer 300 - timeout in seconds (floats possible) 301 302 303.. _kevent-objects: 304 305Kevent Objects 306-------------- 307 308https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2 309 310.. attribute:: kevent.ident 311 312 Value used to identify the event. The interpretation depends on the filter 313 but it's usually the file descriptor. In the constructor ident can either 314 be an int or an object with a fileno() function. kevent stores the integer 315 internally. 316 317.. attribute:: kevent.filter 318 319 Name of the kernel filter. 320 321 +---------------------------+---------------------------------------------+ 322 | Constant | Meaning | 323 +===========================+=============================================+ 324 | :const:`KQ_FILTER_READ` | Takes a descriptor and returns whenever | 325 | | there is data available to read | 326 +---------------------------+---------------------------------------------+ 327 | :const:`KQ_FILTER_WRITE` | Takes a descriptor and returns whenever | 328 | | there is data available to write | 329 +---------------------------+---------------------------------------------+ 330 | :const:`KQ_FILTER_AIO` | AIO requests | 331 +---------------------------+---------------------------------------------+ 332 | :const:`KQ_FILTER_VNODE` | Returns when one or more of the requested | 333 | | events watched in *fflag* occurs | 334 +---------------------------+---------------------------------------------+ 335 | :const:`KQ_FILTER_PROC` | Watch for events on a process id | 336 +---------------------------+---------------------------------------------+ 337 | :const:`KQ_FILTER_NETDEV` | Watch for events on a network device | 338 | | [not available on Mac OS X] | 339 +---------------------------+---------------------------------------------+ 340 | :const:`KQ_FILTER_SIGNAL` | Returns whenever the watched signal is | 341 | | delivered to the process | 342 +---------------------------+---------------------------------------------+ 343 | :const:`KQ_FILTER_TIMER` | Establishes an arbitrary timer | 344 +---------------------------+---------------------------------------------+ 345 346.. attribute:: kevent.flags 347 348 Filter action. 349 350 +---------------------------+---------------------------------------------+ 351 | Constant | Meaning | 352 +===========================+=============================================+ 353 | :const:`KQ_EV_ADD` | Adds or modifies an event | 354 +---------------------------+---------------------------------------------+ 355 | :const:`KQ_EV_DELETE` | Removes an event from the queue | 356 +---------------------------+---------------------------------------------+ 357 | :const:`KQ_EV_ENABLE` | Permitscontrol() to returns the event | 358 +---------------------------+---------------------------------------------+ 359 | :const:`KQ_EV_DISABLE` | Disablesevent | 360 +---------------------------+---------------------------------------------+ 361 | :const:`KQ_EV_ONESHOT` | Removes event after first occurrence | 362 +---------------------------+---------------------------------------------+ 363 | :const:`KQ_EV_CLEAR` | Reset the state after an event is retrieved | 364 +---------------------------+---------------------------------------------+ 365 | :const:`KQ_EV_SYSFLAGS` | internal event | 366 +---------------------------+---------------------------------------------+ 367 | :const:`KQ_EV_FLAG1` | internal event | 368 +---------------------------+---------------------------------------------+ 369 | :const:`KQ_EV_EOF` | Filter specific EOF condition | 370 +---------------------------+---------------------------------------------+ 371 | :const:`KQ_EV_ERROR` | See return values | 372 +---------------------------+---------------------------------------------+ 373 374 375.. attribute:: kevent.fflags 376 377 Filter specific flags. 378 379 :const:`KQ_FILTER_READ` and :const:`KQ_FILTER_WRITE` filter flags: 380 381 +----------------------------+--------------------------------------------+ 382 | Constant | Meaning | 383 +============================+============================================+ 384 | :const:`KQ_NOTE_LOWAT` | low water mark of a socket buffer | 385 +----------------------------+--------------------------------------------+ 386 387 :const:`KQ_FILTER_VNODE` filter flags: 388 389 +----------------------------+--------------------------------------------+ 390 | Constant | Meaning | 391 +============================+============================================+ 392 | :const:`KQ_NOTE_DELETE` | *unlink()* was called | 393 +----------------------------+--------------------------------------------+ 394 | :const:`KQ_NOTE_WRITE` | a write occurred | 395 +----------------------------+--------------------------------------------+ 396 | :const:`KQ_NOTE_EXTEND` | the file was extended | 397 +----------------------------+--------------------------------------------+ 398 | :const:`KQ_NOTE_ATTRIB` | an attribute was changed | 399 +----------------------------+--------------------------------------------+ 400 | :const:`KQ_NOTE_LINK` | the link count has changed | 401 +----------------------------+--------------------------------------------+ 402 | :const:`KQ_NOTE_RENAME` | the file was renamed | 403 +----------------------------+--------------------------------------------+ 404 | :const:`KQ_NOTE_REVOKE` | access to the file was revoked | 405 +----------------------------+--------------------------------------------+ 406 407 :const:`KQ_FILTER_PROC` filter flags: 408 409 +----------------------------+--------------------------------------------+ 410 | Constant | Meaning | 411 +============================+============================================+ 412 | :const:`KQ_NOTE_EXIT` | the process has exited | 413 +----------------------------+--------------------------------------------+ 414 | :const:`KQ_NOTE_FORK` | the process has called *fork()* | 415 +----------------------------+--------------------------------------------+ 416 | :const:`KQ_NOTE_EXEC` | the process has executed a new process | 417 +----------------------------+--------------------------------------------+ 418 | :const:`KQ_NOTE_PCTRLMASK` | internal filter flag | 419 +----------------------------+--------------------------------------------+ 420 | :const:`KQ_NOTE_PDATAMASK` | internal filter flag | 421 +----------------------------+--------------------------------------------+ 422 | :const:`KQ_NOTE_TRACK` | follow a process across *fork()* | 423 +----------------------------+--------------------------------------------+ 424 | :const:`KQ_NOTE_CHILD` | returned on the child process for | 425 | | *NOTE_TRACK* | 426 +----------------------------+--------------------------------------------+ 427 | :const:`KQ_NOTE_TRACKERR` | unable to attach to a child | 428 +----------------------------+--------------------------------------------+ 429 430 :const:`KQ_FILTER_NETDEV` filter flags (not available on Mac OS X): 431 432 +----------------------------+--------------------------------------------+ 433 | Constant | Meaning | 434 +============================+============================================+ 435 | :const:`KQ_NOTE_LINKUP` | link is up | 436 +----------------------------+--------------------------------------------+ 437 | :const:`KQ_NOTE_LINKDOWN` | link is down | 438 +----------------------------+--------------------------------------------+ 439 | :const:`KQ_NOTE_LINKINV` | link state is invalid | 440 +----------------------------+--------------------------------------------+ 441 442 443.. attribute:: kevent.data 444 445 Filter specific data. 446 447 448.. attribute:: kevent.udata 449 450 User defined value. 451