selectors — Высокоуровневое множественное кэширование ввода-вывода

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

1. Введение

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

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

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

2. Классы

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

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().

3. Примеры

Вот пример реализации простого эхо-сервера:

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)