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 не зарегистрирован. Он поднимет 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)