selectors — Высокоуровневый мультиплексинг ввода-вывода

Исходный код: Lib/selectors.py

Введение

Этот модуль предоставляет высокоуровневый и эффективный мультиплексинг ввода-вывода, основанный на примитивах модуля select. Пользователям рекомендуется использовать этот модуль вместо него, если только не требуется точный контроль над примитивами, используемыми на уровне операционной системы.

Он определяет абстрактный базовый класс BaseSelector, а также несколько конкретных реализаций (KqueueSelector, EpollSelector…), которые могут использоваться для ожидания уведомлений о готовности ввода-вывода на нескольких файловых объектах. В дальнейшем под «файловым объектом» подразумевается любой объект с методом fileno() или необработанный дескриптор файла. Смотрите файловый объект.

DefaultSelector — псевдоним наиболее эффективной реализации, доступной на текущей платформе: для большинства пользователей это должен быть предпочтительный выбор.

Классы

Иерархия классов:

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

В дальнейшем события — это битовая маска, указывающая, какие события ввода-вывода следует ожидать для данного файлового объекта. Она может быть комбинацией нижеследующих констант модуля:

class selectors.SelectorKey

SelectorKey — namedtuple, используемая для сопоставления файлового объекта с его базовым дескриптором файла, маской выбранных событий и прикрепленными данными. Она возвращается несколькими методами класса BaseSelector.

fileobj

Зарегистрированный файловый объект.

fd

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

events

События, которые необходимо ожидать для этого файлового объекта.

data

Необязательные непрозрачные данные, связанные с этим файловым объектом; например, для хранения идентификатора сеанса на клиента.

class selectors.BaseSelector

BaseSelector используется для ожидания готовности событий ввода-вывода на нескольких файловых объектах. Он поддерживает регистрацию, отмену регистрации и метод ожидания событий ввода-вывода на этих потоках с необязательным таймаутом. Это абстрактный базовый класс, поэтому его нельзя создать. Используйте DefaultSelector или один из SelectSelector, KqueueSelector и т. д., если требуется конкретная реализация и ваша платформа ее поддерживает. BaseSelector и его конкретные реализации поддерживают протокол менеджера контекста.

abstractmethod register(fileobj, events, data=None)

Регистрация файлового объекта для выбора, мониторинг его событий ввода-вывода.

fileobj — это файловый объект для мониторинга. Это может быть целочисленный дескриптор файла или объект с методом fileno(). events — это битовая маска событий для мониторинга. data — непрозрачный объект.

Возвращает новый экземпляр SelectorKey или исключение ValueError в случае некорректной маски событий или дескриптора файла, или KeyError, если файловый объект уже зарегистрирован.

abstractmethod unregister(fileobj)

Отмена регистрации файлового объекта из выбора, удаление его из мониторинга. Файловый объект должен быть отменён от регистрации до закрытия.

fileobj должен быть файловым объектом, ранее зарегистрированным.

Возвращает связанный экземпляр SelectorKey или исключение KeyError, если fileobj не зарегистрирован. Будет вызвано исключение ValueError, если fileobj некорректен (например, у него нет метода fileno() или его метод fileno() возвращает некорректное значение).

modify(fileobj, events, data=None)

Изменение отслеживаемых событий или прикреплённых данных зарегистрированного файлового объекта.

Это эквивалентно BaseSelector.unregister(fileobj)() и BaseSelector.register(fileobj, events, data)(), но может быть реализовано более эффективно.

Возвращает новый экземпляр SelectorKey или исключение ValueError в случае некорректной маски событий или дескриптора файла, или KeyError, если файловый объект не зарегистрирован.

abstractmethod select(timeout=None)

Ожидание, пока некоторые зарегистрированные файловые объекты не станут готовыми или истечёт таймаут.

Если timeout > 0, это задаёт максимальное время ожидания в секундах. Если timeout <= 0, вызов не будет блокироваться и сообщит о файловых объектах, которые в данный момент готовы. Если timeout равен None, вызов будет блокироваться до тех пор, пока один из отслеживаемых файловых объектов не станет готовым.

Возвращает список кортежей (key, events), по одному для каждого готового файлового объекта.

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)