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

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

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssembly platforms for more information.

Класи

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

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

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

Постійний	Значення
selectors.EVENT_READ	Доступний для читання
selectors.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)