ꦫꦣꦺꦤ꧀ꦄꦤ꧀ꦠꦱꦺꦤ

PATH: usr / share / doc / python3-docs / html / _sources / library

:mod:`selectors` --- High-level I/O multiplexing
================================================

.. module:: selectors
   :synopsis: High-level I/O multiplexing.

.. versionadded:: 3.4

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

--------------

Introduction
------------

This module allows high-level and efficient I/O multiplexing, built upon the
:mod:`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 :class:`BaseSelector` abstract base class, along with several
concrete implementations (:class:`KqueueSelector`, :class:`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
:meth:`fileno()` method, or a raw file descriptor. See :term:`file object`.

:class:`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).

.. seealso::

:mod:`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:

.. class:: SelectorKey

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

.. attribute:: fileobj

File object registered.

.. attribute:: fd

Underlying file descriptor.

.. attribute:: events

Events that must be waited for on this file object.

.. attribute:: data

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

.. class:: BaseSelector

A :class:`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
   :class:`DefaultSelector` instead, or one of :class:`SelectSelector`,
   :class:`KqueueSelector` etc. if you want to specifically use an
   implementation, and your platform supports it.
   :class:`BaseSelector` and its concrete implementations support the
   :term:`context manager` protocol.

.. abstractmethod:: register(fileobj, events, data=None)

*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 :class:`SelectorKey` instance, or raises a
      :exc:`ValueError` in case of invalid event mask or file descriptor, or
      :exc:`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 :class:`SelectorKey` instance, or raises a
      :exc:`KeyError` if *fileobj* is not registered.  It will raise
      :exc:`ValueError` if *fileobj* is invalid (e.g. it has no ``fileno()``
      method or its ``fileno()`` method has an invalid return value).

.. method:: modify(fileobj, events, data=None)

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

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

This returns a new :class:`SelectorKey` instance, or raises a
      :exc:`ValueError` in case of invalid event mask or file descriptor, or
      :exc:`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 :class:`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.

.. versionchanged:: 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.

.. method:: 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.

.. method:: get_key(fileobj)

Return the key associated with a registered file object.

This returns the :class:`SelectorKey` instance associated to this file
      object, or raises :exc:`KeyError` if the file object is not registered.

.. abstractmethod:: get_map()

Return a mapping of file objects to selector keys.

This returns a :class:`~collections.abc.Mapping` instance mapping
      registered file objects to their associated :class:`SelectorKey`
      instance.

.. class:: 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:: SelectSelector()

:func:`select.select`-based selector.

.. class:: PollSelector()

:func:`select.poll`-based selector.

.. class:: EpollSelector()

:func:`select.epoll`-based selector.

.. method:: fileno()

This returns the file descriptor used by the underlying
      :func:`select.epoll` object.

.. class:: DevpollSelector()

:func:`select.devpoll`-based selector.

.. method:: fileno()

This returns the file descriptor used by the underlying
      :func:`select.devpoll` object.

.. versionadded:: 3.5

.. class:: KqueueSelector()

:func:`select.kqueue`-based selector.

.. method:: fileno()

This returns the file descriptor used by the underlying
      :func:`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)

[+] ..
[-] crypt.rst.txt [edit]
[-] logging.handlers.rst.txt [edit]
[-] __main__.rst.txt [edit]
[-] pty.rst.txt [edit]
[-] email.rst.txt [edit]
[-] traceback.rst.txt [edit]
[-] fileinput.rst.txt [edit]
[-] xml.sax.reader.rst.txt [edit]
[-] curses.rst.txt [edit]
[-] copy.rst.txt [edit]
[-] aifc.rst.txt [edit]
[-] xmlrpc.client.rst.txt [edit]
[-] pydoc.rst.txt [edit]
[-] asyncio-eventloops.rst.txt [edit]
[-] uuid.rst.txt [edit]
[-] functional.rst.txt [edit]
[-] posix.rst.txt [edit]
[-] hashlib.rst.txt [edit]
[-] cmd.rst.txt [edit]
[-] nntplib.rst.txt [edit]
[-] python.rst.txt [edit]
[-] types.rst.txt [edit]
[-] exceptions.rst.txt [edit]
[-] tracemalloc.rst.txt [edit]
[-] othergui.rst.txt [edit]
[-] xml.dom.pulldom.rst.txt [edit]
[-] inspect.rst.txt [edit]
[-] asyncio-stream.rst.txt [edit]
[-] i18n.rst.txt [edit]
[-] concurrent.rst.txt [edit]
[-] imghdr.rst.txt [edit]
[-] spwd.rst.txt [edit]
[-] os.path.rst.txt [edit]
[-] email.message.rst.txt [edit]
[-] random.rst.txt [edit]
[-] fileformats.rst.txt [edit]
[-] faulthandler.rst.txt [edit]
[-] parser.rst.txt [edit]
[-] stat.rst.txt [edit]
[-] code.rst.txt [edit]
[-] email.headerregistry.rst.txt [edit]
[-] timeit.rst.txt [edit]
[-] optparse.rst.txt [edit]
[-] smtplib.rst.txt [edit]
[-] filesys.rst.txt [edit]
[-] email.mime.rst.txt [edit]
[-] itertools.rst.txt [edit]
[-] sys.rst.txt [edit]
[-] bdb.rst.txt [edit]
[-] stringprep.rst.txt [edit]
[-] asyncio-subprocess.rst.txt [edit]
[-] decimal.rst.txt [edit]
[-] unicodedata.rst.txt [edit]
[-] intro.rst.txt [edit]
[-] constants.rst.txt [edit]
[-] xmlrpc.rst.txt [edit]
[-] grp.rst.txt [edit]
[-] pickle.rst.txt [edit]
[-] mmap.rst.txt [edit]
[-] debug.rst.txt [edit]
[-] unittest.mock-examples.rst.txt [edit]
[-] undoc.rst.txt [edit]
[-] functools.rst.txt [edit]
[-] ssl.rst.txt [edit]
[-] locale.rst.txt [edit]
[-] secrets.rst.txt [edit]
[-] pprint.rst.txt [edit]
[-] email.header.rst.txt [edit]
[-] email.contentmanager.rst.txt [edit]
[-] _thread.rst.txt [edit]
[-] errno.rst.txt [edit]
[-] sunau.rst.txt [edit]
[-] syslog.rst.txt [edit]
[-] tkinter.ttk.rst.txt [edit]
[-] distribution.rst.txt [edit]
[-] pdb.rst.txt [edit]
[-] distutils.rst.txt [edit]
[-] dummy_threading.rst.txt [edit]
[-] text.rst.txt [edit]
[-] socketserver.rst.txt [edit]
[-] _dummy_thread.rst.txt [edit]
[-] persistence.rst.txt [edit]
[-] asyncio-eventloop.rst.txt [edit]
[-] collections.abc.rst.txt [edit]
[-] fnmatch.rst.txt [edit]
[-] quopri.rst.txt [edit]
[-] http.server.rst.txt [edit]
[-] keyword.rst.txt [edit]
[-] xml.dom.rst.txt [edit]
[-] cgi.rst.txt [edit]
[-] heapq.rst.txt [edit]
[-] email.iterators.rst.txt [edit]
[-] io.rst.txt [edit]
[-] curses.panel.rst.txt [edit]
[-] winreg.rst.txt [edit]
[-] urllib.parse.rst.txt [edit]
[-] unix.rst.txt [edit]
[-] getpass.rst.txt [edit]
[-] sched.rst.txt [edit]
[-] socket.rst.txt [edit]
[-] pipes.rst.txt [edit]
[-] email.compat32-message.rst.txt [edit]
[-] asyncio-sync.rst.txt [edit]
[-] modulefinder.rst.txt [edit]
[-] html.entities.rst.txt [edit]
[-] ctypes.rst.txt [edit]
[-] pyexpat.rst.txt [edit]
[-] pyclbr.rst.txt [edit]
[-] html.rst.txt [edit]
[-] test.rst.txt [edit]
[-] markup.rst.txt [edit]
[-] doctest.rst.txt [edit]
[-] csv.rst.txt [edit]
[-] colorsys.rst.txt [edit]
[-] xml.sax.rst.txt [edit]
[-] zlib.rst.txt [edit]
[-] subprocess.rst.txt [edit]
[-] base64.rst.txt [edit]
[-] platform.rst.txt [edit]
[-] binascii.rst.txt [edit]
[-] http.rst.txt [edit]
[-] nis.rst.txt [edit]
[-] statistics.rst.txt [edit]
[-] sqlite3.rst.txt [edit]
[-] json.rst.txt [edit]
[-] gzip.rst.txt [edit]
[-] netdata.rst.txt [edit]
[-] pkgutil.rst.txt [edit]
[-] linecache.rst.txt [edit]
[-] cgitb.rst.txt [edit]
[-] archiving.rst.txt [edit]
[-] argparse.rst.txt [edit]
[-] wsgiref.rst.txt [edit]
[-] tokenize.rst.txt [edit]
[-] mm.rst.txt [edit]
[-] telnetlib.rst.txt [edit]
[-] ossaudiodev.rst.txt [edit]
[-] tk.rst.txt [edit]
[-] string.rst.txt [edit]
[-] misc.rst.txt [edit]
[-] marshal.rst.txt [edit]
[-] email.encoders.rst.txt [edit]
[-] array.rst.txt [edit]
[-] queue.rst.txt [edit]
[-] copyreg.rst.txt [edit]
[-] atexit.rst.txt [edit]
[-] signal.rst.txt [edit]
[-] collections.rst.txt [edit]
[-] tkinter.scrolledtext.rst.txt [edit]
[-] tempfile.rst.txt [edit]
[-] codeop.rst.txt [edit]
[-] threading.rst.txt [edit]
[-] enum.rst.txt [edit]
[-] imp.rst.txt [edit]
[-] crypto.rst.txt [edit]
[-] bisect.rst.txt [edit]
[-] dbm.rst.txt [edit]
[-] formatter.rst.txt [edit]
[-] language.rst.txt [edit]
[-] trace.rst.txt [edit]
[-] tkinter.tix.rst.txt [edit]
[-] smtpd.rst.txt [edit]
[-] asyncio-task.rst.txt [edit]
[-] abc.rst.txt [edit]
[-] gettext.rst.txt [edit]
[-] concurrency.rst.txt [edit]
[-] allos.rst.txt [edit]
[-] xml.sax.utils.rst.txt [edit]
[-] tty.rst.txt [edit]
[-] mailcap.rst.txt [edit]
[-] msvcrt.rst.txt [edit]
[-] reprlib.rst.txt [edit]
[-] development.rst.txt [edit]
[-] contextlib.rst.txt [edit]
[-] configparser.rst.txt [edit]
[-] symbol.rst.txt [edit]
[-] shlex.rst.txt [edit]
[-] tabnanny.rst.txt [edit]
[-] asyncio-dev.rst.txt [edit]
[-] py_compile.rst.txt [edit]
[-] uu.rst.txt [edit]
[-] logging.rst.txt [edit]
[-] runpy.rst.txt [edit]
[-] pathlib.rst.txt [edit]
[-] os.rst.txt [edit]
[-] urllib.request.rst.txt [edit]
[-] html.parser.rst.txt [edit]
[-] bz2.rst.txt [edit]
[-] binhex.rst.txt [edit]
[-] time.rst.txt [edit]
[-] zipapp.rst.txt [edit]
[-] fcntl.rst.txt [edit]
[-] tkinter.rst.txt [edit]
[-] glob.rst.txt [edit]
[-] email.policy.rst.txt [edit]
[-] pwd.rst.txt [edit]
[-] numeric.rst.txt [edit]
[-] winsound.rst.txt [edit]
[-] urllib.robotparser.rst.txt [edit]
[-] selectors.rst.txt [edit]
[-] xdrlib.rst.txt [edit]
[-] webbrowser.rst.txt [edit]
[-] zipfile.rst.txt [edit]
[-] ipc.rst.txt [edit]
[-] mailbox.rst.txt [edit]
[-] plistlib.rst.txt [edit]
[-] getopt.rst.txt [edit]
[-] concurrent.futures.rst.txt [edit]
[-] symtable.rst.txt [edit]
[-] rlcompleter.rst.txt [edit]
[-] __future__.rst.txt [edit]
[-] asynchat.rst.txt [edit]
[-] audioop.rst.txt [edit]
[-] compileall.rst.txt [edit]
[-] unittest.mock.rst.txt [edit]
[-] dis.rst.txt [edit]
[-] index.rst.txt [edit]
[-] logging.config.rst.txt [edit]
[-] gc.rst.txt [edit]
[-] shutil.rst.txt [edit]
[-] sndhdr.rst.txt [edit]
[-] ipaddress.rst.txt [edit]
[-] asyncio-queue.rst.txt [edit]
[-] curses.ascii.rst.txt [edit]
[-] builtins.rst.txt [edit]
[-] calendar.rst.txt [edit]
[-] sysconfig.rst.txt [edit]
[-] token.rst.txt [edit]
[-] xml.dom.minidom.rst.txt [edit]
[-] textwrap.rst.txt [edit]
[-] importlib.rst.txt [edit]
[-] fpectl.rst.txt [edit]
[-] mimetypes.rst.txt [edit]
[-] netrc.rst.txt [edit]
[-] fractions.rst.txt [edit]
[-] select.rst.txt [edit]
[-] lzma.rst.txt [edit]
[-] math.rst.txt [edit]
[-] frameworks.rst.txt [edit]
[-] ftplib.rst.txt [edit]
[-] macpath.rst.txt [edit]
[-] numbers.rst.txt [edit]
[-] xml.etree.elementtree.rst.txt [edit]
[-] pickletools.rst.txt [edit]
[-] asyncore.rst.txt [edit]
[-] warnings.rst.txt [edit]
[-] resource.rst.txt [edit]
[-] unittest.rst.txt [edit]
[-] datetime.rst.txt [edit]
[-] asyncio-protocol.rst.txt [edit]
[-] urllib.rst.txt [edit]
[-] superseded.rst.txt [edit]
[-] email.generator.rst.txt [edit]
[-] ensurepip.rst.txt [edit]
[-] ast.rst.txt [edit]
[-] modules.rst.txt [edit]
[-] venv.rst.txt [edit]
[-] internet.rst.txt [edit]
[-] chunk.rst.txt [edit]
[-] asyncio.rst.txt [edit]
[-] turtle.rst.txt [edit]
[-] struct.rst.txt [edit]
[-] profile.rst.txt [edit]
[-] urllib.error.rst.txt [edit]
[-] http.cookiejar.rst.txt [edit]
[-] tarfile.rst.txt [edit]
[-] http.cookies.rst.txt [edit]
[-] multiprocessing.rst.txt [edit]
[-] msilib.rst.txt [edit]
[-] xmlrpc.server.rst.txt [edit]
[-] termios.rst.txt [edit]
[-] 2to3.rst.txt [edit]
[-] windows.rst.txt [edit]
[-] email.examples.rst.txt [edit]
[-] readline.rst.txt [edit]
[-] binary.rst.txt [edit]
[-] shelve.rst.txt [edit]
[-] re.rst.txt [edit]
[-] xml.sax.handler.rst.txt [edit]
[-] hmac.rst.txt [edit]
[-] datatypes.rst.txt [edit]
[-] typing.rst.txt [edit]
[-] custominterp.rst.txt [edit]
[-] email.charset.rst.txt [edit]
[-] email.util.rst.txt [edit]
[-] zipimport.rst.txt [edit]
[-] cmath.rst.txt [edit]
[-] idle.rst.txt [edit]
[-] operator.rst.txt [edit]
[-] site.rst.txt [edit]
[-] email.parser.rst.txt [edit]
[-] functions.rst.txt [edit]
[-] poplib.rst.txt [edit]
[-] filecmp.rst.txt [edit]
[-] codecs.rst.txt [edit]
[-] imaplib.rst.txt [edit]
[-] stdtypes.rst.txt [edit]
[-] difflib.rst.txt [edit]
[-] weakref.rst.txt [edit]
[-] http.client.rst.txt [edit]
[-] email.errors.rst.txt [edit]
[-] xml.rst.txt [edit]
[-] wave.rst.txt [edit]