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)