selectors — Уровневый многопотоковый ввод-вывод

Введение

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

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

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

Классы

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

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

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

class selectors.SelectorKey

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

fileobj

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

fd

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

events

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

data

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

class selectors.BaseSelector

A 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)