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

Нове в версії 3.4.

Вихідний код: Lib/selectors.py

## Вступ

Цей модуль забезпечує високорівневе й ефективне мультиплексування введення/виведення, побудоване на примітивах модуля `select`. Користувачам рекомендується використовувати замість цього модуль, якщо вони не бажають точного контролю над використовуваними примітивами рівня ОС.

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` — це псевдонім найефективнішої реалізації, доступної на поточній платформі: це має бути вибір за умовчанням для більшості користувачів.

Примітка

Тип підтримуваних файлових об’єктів залежить від платформи: у Windows підтримуються сокети, але не канали, тоді як в Unix підтримуються обидва (можуть підтримуватися й деякі інші типи, наприклад fifos або спеціальні файлові пристрої).

Дивись також

`select`

  Модуль мультиплексування вводу/виводу низького рівня.

## Класи

Ієрархія класів:

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

Нижче події — це порозрядна маска, що вказує, на які події вводу/виводу слід чекати для певного файлового об’єкта. Це може бути комбінація наведених нижче констант модулів:

> Постійний | Значення
> --- | ---
> `EVENT_READ` | Доступний для читання
> `EVENT_WRITE` | Доступний для запису

class `selectors.``SelectorKey`

  `SelectorKey` — це `namedtuple`, який використовується для зв’язування об’єкта файлу з його основним дескриптором файлу, вибраною маскою події та вкладеними даними. Його повертають кілька методів `BaseSelector`.

  `fileobj`

    Файловий об’єкт зареєстровано.

  `fd`

    Базовий файловий дескриптор.

  `events`

    Події, які потрібно очікувати для цього файлового об’єкта.

  `data`

    Додаткові непрозорі дані, пов’язані з цим файловим об’єктом: наприклад, це можна використовувати для зберігання ідентифікатора сеансу кожного клієнта.

class `selectors.``BaseSelector`

  `BaseSelector` використовується для очікування готовності події вводу/виводу для кількох файлових об’єктів. Він підтримує реєстрацію потоку файлів, скасування реєстрації та метод очікування подій введення/виведення в цих потоках із додатковим тайм-аутом. Це абстрактний базовий клас, тому його не можна створити. Замість цього використовуйте `DefaultSelector` або один із `SelectSelector`, `KqueueSelector` тощо, якщо ви хочете використовувати певну реалізацію, і ваша платформа це підтримує. `BaseSelector` і його конкретні реалізації підтримують протокол context manager.

  abstractmethod `register`(fileobj, events, data=None)

    Зареєструйте файловий об’єкт для вибору, відстежуючи його для подій вводу/виводу.

    fileobj — файловий об’єкт для моніторингу. Це може бути цілочисельний файловий дескриптор або об’єкт із методом fileno(). події — це побітова маска подій для моніторингу. data є непрозорим об’єктом.

    Це повертає новий екземпляр `SelectorKey` або викликає `ValueError` у разі недійсної маски події чи дескриптора файлу, або `KeyError`, якщо об’єкт файлу вже зареєстровано.

  abstractmethod `unregister`(fileobj)

    Скасувати реєстрацію файлового об’єкта з вибору, видаливши його з моніторингу. Перед закриттям файлового об’єкта необхідно скасувати реєстрацію.

    fileobj має бути попередньо зареєстрованим файловим об’єктом.

    Це повертає пов’язаний екземпляр `SelectorKey` або викликає `KeyError`, якщо fileobj не зареєстровано. Він викличе `ValueError`, якщо fileobj недійсний (наприклад, він не має методу `fileno()` або його `fileno()` метод має недійсне повернуте значення).

  `modify`(fileobj, events, data=None)

    Змінити події або вкладені дані зареєстрованого файлового об’єкта.

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

    Це повертає новий екземпляр `SelectorKey` або викликає `ValueError` у разі недійсної маски події чи дескриптора файлу, або `KeyError`, якщо об’єкт файлу не зареєстровано.

  abstractmethod `select`(timeout=None)

    Зачекайте, поки деякі зареєстровані файлові об’єкти стануть готовими, або закінчиться час очікування.

    Якщо `timeout > 0`, це визначає максимальний час очікування в секундах. Якщо `timeout <= 0`, виклик не блокуватиметься, а повідомлятиметься про наразі готові файлові об’єкти. Якщо timeout має значення `None`, виклик блокуватиметься, доки контрольований файловий об’єкт не стане готовим.

    Це повертає список кортежів `(ключ, події)`, по одному для кожного готового файлового об’єкта.

    key — це екземпляр `SelectorKey`, що відповідає готовому файловому об’єкту. events — це бітова маска подій, готових для цього файлового об’єкта.

    Примітка

    Цей метод може повернутися до того, як будь-який файловий об’єкт стане готовим або мине час очікування, якщо поточний процес отримає сигнал: у цьому випадку буде повернено порожній список.

    Змінено в версії 3.5: Тепер селектор виконується повторно з переобчисленим тайм-аутом, коли його перериває сигнал, якщо обробник сигналу не викликав виняткову ситуацію (див. PEP 475 для обґрунтування), замість повернення порожнього списку подій до тайм-ауту.

  `close`()

    Закрийте селектор.

    Це потрібно викликати, щоб переконатися, що будь-який основний ресурс звільнено. Перемикач не можна використовувати після того, як він закритий.

  `get_key`(fileobj)

    Повертає ключ, пов’язаний із зареєстрованим файловим об’єктом.

    Це повертає екземпляр `SelectorKey`, пов’язаний із цим об’єктом файлу, або викликає `KeyError`, якщо об’єкт файлу не зареєстровано.

  abstractmethod `get_map`()

    Повернути відображення файлових об’єктів на клавіші вибору.

    Це повертає екземпляр `Mapping`, який зіставляє зареєстровані файлові об’єкти з їхнім пов’язаним екземпляром `SelectorKey`.

class `selectors.``DefaultSelector`

  Клас селектора за замовчуванням із використанням найефективнішої реалізації, доступної на поточній платформі. Це має бути вибір за умовчанням для більшості користувачів.

class `selectors.``SelectSelector`

  Селектор на основі `select.select()`.

class `selectors.``PollSelector`

  Селектор на основі `select.poll()`.

class `selectors.``EpollSelector`

  Селектор на основі `select.epoll()`.

  `fileno`()

    Це повертає дескриптор файлу, який використовується базовим об’єктом `select.epoll()`.

class `selectors.``DevpollSelector`

  Селектор на основі `select.devpoll()`.

  `fileno`()

    Це повертає дескриптор файлу, який використовується базовим об’єктом `select.devpoll()`.

  Нове в версії 3.5.

class `selectors.``KqueueSelector`

  `select.kqueue()` селектор.

  `fileno`()

    Це повертає дескриптор файлу, який використовується базовим об’єктом `select.kqueue()`.

## Приклади

Ось проста реалізація ехо-сервера:

    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)