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

Введение

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

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

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

Классы

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

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

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

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 не зарегистрирован. Если fileobj недопустим (например, у него нет метода fileno() или метод fileno() возвращает недопустимое значение), вызывается исключение ValueError.

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)