# `selectors` — High-level I/O multiplexing

Added in version 3.4.

Código fuente: Lib/selectors.py

## Introducción

Este módulo permite multiplexación de E/S eficiente y de alto nivel, basada en los primitivos del módulo `select`. Se recomienda a los usuarios utilizar este módulo en su lugar, a menos que deseen un control preciso sobre los primitivos a nivel de sistema operativo utilizados.

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` es un alias de la implementación más eficiente disponible en la plataforma actual: esta debería ser la opción predeterminada para la mayoría de los usuarios.

Nota

El tipo de objetos de archivo admitidos depende de la plataforma: en Windows, se admiten sockets, pero no pipes, mientras que en Unix, ambos son compatibles (también se pueden admitir algunos otros tipos, como FIFOs o dispositivos de archivo especiales).

Ver también

`select`

  Módulo de multiplexación de E/S de bajo nivel.

Availability: not Emscripten, not WASI.

Este modulo no funciona o no está disponible para plataformas WebAssembly `wasm32-emscripten` y `wasm32-wasi`. Consulte Plataformas WebAssembly para más información.

## Clases

Jerarquía de clases:

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

De aquí en adelante, events es una máscara bit a bit que indica qué eventos de E/S se deben esperar en un objeto de archivo determinado. Puede ser cualquier combinación de las siguientes constantes de módulo:

> Constante | Significado
> --- | ---
> selectors.EVENT_READ | Disponible para lectura
> selectors.EVENT_WRITE | Disponible para escritura

class selectors.SelectorKey

  La clase `SelectorKey` es una `namedtuple` que se utiliza para asociar un objeto de archivo a su descriptor de archivo subyacente, máscara de evento seleccionada y datos adjuntos. Es retornada por varios métodos `BaseSelector`.

  fileobj

    Objeto de archivo registrado.

  fd

    Descriptor de archivo subyacente.

  events

    Eventos que se deben esperar en este objeto de archivo.

  data

    Datos opacos opcionales asociados a este objeto de archivo: por ejemplo, podría usarse para almacenar un ID de sesión por cliente.

class selectors.BaseSelector

  Un `BaseSelector` se usa para esperar a que el evento de E/S esté listo en varios objetos de archivo. Admite el registro y la cancelación del registro de secuencias de archivos y un método para esperar eventos de E/S en esas secuencias, con un tiempo de espera opcional. Es una clase base abstracta, por lo que no se puede crear una instancia. Use `DefaultSelector` en su lugar, o un `SelectSelector`, `KqueueSelector`, etc. si deseas usar específicamente una implementación y su plataforma la admite. `BaseSelector` y sus implementaciones concretas soportan el protocolo context manager.

  abstractmethod register(fileobj, events, data=None)

    Registra un objeto de archivo para su selección y lo monitoriza en busca de eventos de E/S.

    fileobj es el objeto de archivo a monitorear. Puede ser un descriptor de archivo de tipo entero o un objeto con un método `fileno()`. events es una máscara bit a bit de eventos para monitorear. data es un objeto opaco.

    Esto retorna una nueva instancia `SelectorKey`, o lanza un `ValueError` en caso de una máscara de evento o un descriptor de archivo no válidos, o `KeyError` si el objeto de archivo ya está registrado.

  abstractmethod unregister(fileobj)

    Anula el registro de un objeto de archivo de la selección y lo elimina del monitoreo. Se anulará el registro de un objeto de archivo antes de cerrarlo.

    fileobj debe ser un objeto de archivo previamente registrado.

    Esto retorna la instancia `SelectorKey` asociada, o lanza un `KeyError` si fileobj no está registrado. Se lanzará un `ValueError` si fileobj no es válido (por ejemplo, no tiene el método `fileno ()` o su método `fileno ()` tiene un valor de retorno no válido).

  modify(fileobj, events, data=None)

    Cambia los eventos monitorizados de un objeto de archivo registrado o los datos adjuntos.

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

    Esto retorna una nueva instancia de `SelectorKey`, o lanza un `ValueError` en caso de una máscara de evento o un descriptor de archivo no válidos, o `KeyError` si el objeto de archivo no está registrado.

  abstractmethod select(timeout=None)

    Espera hasta que algunos objetos de archivo registrados estén listos o el tiempo de espera expire.

    Si `timeout > 0`, esto especifica el tiempo máximo de espera, en segundos. Si `timeout <= 0`, la llamada no se bloqueará y reportará los objetos de archivo actualmente listos. Si timeout es `None`, la llamada se bloqueará hasta que un objeto de archivo monitorizado esté listo.

    Retorna una lista de tuplas `(key, events)`, una por cada objeto de archivo listo.

    key es la instancia `SelectorKey` correspondiente a un objeto de archivo listo. events es una máscara de bits de eventos listos en este objeto de archivo.

    Nota

    Este método puede regresar antes de que cualquier objeto de archivo esté listo o haya transcurrido el tiempo de espera si el proceso actual recibe una señal: en este caso, se retornará una lista vacía.

    Distinto en la versión 3.5: El selector ahora se reintenta con un tiempo de espera recalculado cuando es interrumpido por una señal si el gestor de señales no lanzó una excepción (ver PEP 475 para la justificación), en lugar de retornar una lista vacía de eventos antes del tiempo de espera.

  close()

    Cierra el selector.

    Se debe llamar para asegurarse de que se libera cualquier recurso subyacente. El selector no se utilizará una vez cerrado.

  get_key(fileobj)

    Retorna la clave asociada con un objeto de archivo registrado.

    Esto retorna la instancia `SelectorKey` asociada a este objeto de archivo, o lanza un `KeyError` si el objeto de archivo no está registrado.

  abstractmethod get_map()

    Retorna un mapeo asociando objetos de archivo a las llaves del selector.

    Retorna una instancia de `Mapping` mapeando objetos de archivo registrados a su instancia `SelectorKey` asociada.

class selectors.DefaultSelector

  La clase de selector predeterminada, utiliza la implementación más eficiente disponible en la plataforma actual. Esta debería ser la opción predeterminada para la mayoría de los usuarios.

class selectors.SelectSelector

  Selector basado en `select.select()`.

class selectors.PollSelector

  Selector basado en `select.poll()`.

class selectors.EpollSelector

  Selector basado en `select.epoll()`.

  fileno()

    Esto retorna el descriptor de archivo utilizado por el objeto `select.epoll()` subyacente.

class selectors.DevpollSelector

  Selector basado en `select.devpoll()`.

  fileno()

    Esto retorna el descriptor de archivo utilizado por el objeto `select.devpoll()` subyacente.

  Added in version 3.5.

class selectors.KqueueSelector

  Selector basado en `select.kqueue()`.

  fileno()

    Esto retorna el descriptor de archivo utilizado por el objeto `select.kqueue()` subyacente.

## Ejemplos

Aquí hay una implementación simple de un servidor de eco:

    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)