Python 3.6.5 Documentation >  "selectors" — High-level I/O multiplexing

"selectors" — High-level I/O multiplexing
*****************************************

New in version 3.4.

**Source code:** Lib/selectors.py

======================================================================

Introduction
============

This module allows high-level and efficient I/O multiplexing, built
upon the "select" module primitives. Users are encouraged to use this
module instead, unless they want precise control over the OS-level
primitives used.

It defines a "BaseSelector" abstract base class, along with several
concrete implementations ("KqueueSelector", "EpollSelector"…), that
can be used to wait for I/O readiness notification on multiple file
objects. In the following, “file object” refers to any object with a
"fileno()" method, or a raw file descriptor. See *file object*.

"DefaultSelector" is an alias to the most efficient implementation
available on the current platform: this should be the default choice
for most users.

Note: The type of file objects supported depends on the platform: on
Windows, sockets are supported, but not pipes, whereas on Unix, both
are supported (some other types may be supported as well, such as
fifos or special file devices).

See also:

"select"
Low-level I/O multiplexing module.

Classes
=======

Classes hierarchy:

BaseSelector
+-- SelectSelector
+-- PollSelector
+-- EpollSelector
+-- DevpollSelector
+-- KqueueSelector

In the following, *events* is a bitwise mask indicating which I/O
events should be waited for on a given file object. It can be a
combination of the modules constants below:

+-------------------------+-------------------------------------------------+
| Constant | Meaning |
+=========================+=================================================+
| "EVENT_READ" | Available for read |
+-------------------------+-------------------------------------------------+
| "EVENT_WRITE" | Available for write |
+-------------------------+-------------------------------------------------+

class selectors.SelectorKey

A "SelectorKey" is a "namedtuple" used to associate a file object
to its underlying file descriptor, selected event mask and attached
data. It is returned by several "BaseSelector" methods.

fileobj

File object registered.

fd

Underlying file descriptor.

events

Events that must be waited for on this file object.

data

Optional opaque data associated to this file object: for
example, this could be used to store a per-client session ID.

class selectors.BaseSelector

A "BaseSelector" is used to wait for I/O event readiness on
multiple file objects. It supports file stream registration,
unregistration, and a method to wait for I/O events on those
streams, with an optional timeout. It’s an abstract base class, so
cannot be instantiated. Use "DefaultSelector" instead, or one of
"SelectSelector", "KqueueSelector" etc. if you want to specifically
use an implementation, and your platform supports it.
"BaseSelector" and its concrete implementations support the
*context manager* protocol.

abstractmethod register(fileobj, events, data=None)

Register a file object for selection, monitoring it for I/O
events.

*fileobj* is the file object to monitor. It may either be an
integer file descriptor or an object with a "fileno()" method.
*events* is a bitwise mask of events to monitor. *data* is an
opaque object.

This returns a new "SelectorKey" instance, or raises a
"ValueError" in case of invalid event mask or file descriptor,
or "KeyError" if the file object is already registered.

abstractmethod unregister(fileobj)

Unregister a file object from selection, removing it from
monitoring. A file object shall be unregistered prior to being
closed.

*fileobj* must be a file object previously registered.

This returns the associated "SelectorKey" instance, or raises a
"KeyError" if *fileobj* is not registered. It will raise
"ValueError" if *fileobj* is invalid (e.g. it has no "fileno()"
method or its "fileno()" method has an invalid return value).

modify(fileobj, events, data=None)

Change a registered file object’s monitored events or attached
data.

This is equivalent to "BaseSelector.unregister(fileobj)()"
followed by "BaseSelector.register(fileobj, events, data)()",
except that it can be implemented more efficiently.

This returns a new "SelectorKey" instance, or raises a
"ValueError" in case of invalid event mask or file descriptor,
or "KeyError" if the file object is not registered.

abstractmethod select(timeout=None)

Wait until some registered file objects become ready, or the
timeout expires.

If "timeout > 0", this specifies the maximum wait time, in
seconds. If "timeout <= 0", the call won’t block, and will
report the currently ready file objects. If *timeout* is "None",
the call will block until a monitored file object becomes ready.

This returns a list of "(key, events)" tuples, one for each
ready file object.

*key* is the "SelectorKey" instance corresponding to a ready
file object. *events* is a bitmask of events ready on this file
object.

Note: This method can return before any file object becomes
ready or the timeout has elapsed if the current process
receives a signal: in this case, an empty list will be
returned.

Changed in version 3.5: The selector is now retried with a
recomputed timeout when interrupted by a signal if the signal
handler did not raise an exception (see **PEP 475** for the
rationale), instead of returning an empty list of events before
the timeout.

close()

Close the selector.

This must be called to make sure that any underlying resource is
freed. The selector shall not be used once it has been closed.

get_key(fileobj)

Return the key associated with a registered file object.

This returns the "SelectorKey" instance associated to this file
object, or raises "KeyError" if the file object is not
registered.

abstractmethod get_map()

Return a mapping of file objects to selector keys.

This returns a "Mapping" instance mapping registered file
objects to their associated "SelectorKey" instance.

class selectors.DefaultSelector

The default selector class, using the most efficient implementation
available on the current platform. This should be the default
choice for most users.

class selectors.SelectSelector

"select.select()"-based selector.

class selectors.PollSelector

"select.poll()"-based selector.

class selectors.EpollSelector

"select.epoll()"-based selector.

fileno()

This returns the file descriptor used by the underlying
"select.epoll()" object.

class selectors.DevpollSelector

"select.devpoll()"-based selector.

fileno()

This returns the file descriptor used by the underlying
"select.devpoll()" object.

New in version 3.5.

class selectors.KqueueSelector

"select.kqueue()"-based selector.

fileno()

This returns the file descriptor used by the underlying
"select.kqueue()" object.

Examples
========

Here is a simple echo server implementation:

import selectors
import socket

sel = selectors.DefaultSelector()

def accept(sock, mask):
conn, addr = sock.accept() # Should be ready
print('accepted', conn, 'from', addr)
conn.setblocking(False)
sel.register(conn, selectors.EVENT_READ, read)

def read(conn, mask):
data = conn.recv(1000) # Should be ready
if data:
print('echoing', repr(data), 'to', conn)
conn.send(data) # Hope it won't block
else:
print('closing', conn)
sel.unregister(conn)
conn.close()

sock = socket.socket()
sock.bind(('localhost', 1234))
sock.listen(100)
sock.setblocking(False)
sel.register(sock, selectors.EVENT_READ, accept)

while True:
events = sel.select()
for key, mask in events:
callback = key.data
callback(key.fileobj, mask)