7.3.1 Polling Objects
Keywords: lib

##
7.3.1 Polling Objects

The `poll()` system call, supported on most Unix systems, provides better scalability for network servers that service many, many clients at the same time. `poll()` scales better because the system call only requires listing the file descriptors of interest, while `select()` builds a bitmap, turns on bits for the fds of interest, and then afterward the whole bitmap has to be linearly scanned again. `select()` is O(highest file descriptor), while `poll()` is O(number of file descriptors).

`register` (fd[, eventmask])
  Register a file descriptor with the polling object. Future calls to the `poll()` method will then check whether the file descriptor has any pending I/O events. fd can be either an integer, or an object with a `fileno()` method that returns an integer. File objects implement `fileno()`, so they can also be used as the argument.

  eventmask is an optional bitmask describing the type of events you want to check for, and can be a combination of the constants `POLLIN`, `POLLPRI`, and `POLLOUT`, described in the table below. If not specified, the default value used will check for all 3 types of events.

  Constant | Meaning
  --- | ---
  `POLLIN` | There is data to read
  `POLLPRI` | There is urgent data to read
  `POLLOUT` | Ready for output: writing will not block
  `POLLERR` | Error condition of some sort
  `POLLHUP` | Hung up
  `POLLNVAL` | Invalid request: descriptor not open

  Registering a file descriptor that's already registered is not an error, and has the same effect as registering the descriptor exactly once.

`unregister` (fd)
  Remove a file descriptor being tracked by a polling object. Just like the `register()` method, fd can be an integer or an object with a `fileno()` method that returns an integer.

  Attempting to remove a file descriptor that was never registered causes a `KeyError` exception to be raised.

`poll` ([timeout])
  Polls the set of registered file descriptors, and returns a possibly-empty list containing `(fd, event)` 2-tuples for the descriptors that have events or errors to report. fd is the file descriptor, and event is a bitmask with bits set for the reported events for that descriptor -- `POLLIN` for waiting input, `POLLOUT` to indicate that the descriptor can be written to, and so forth. An empty list indicates that the call timed out and no file descriptors had any events to report.