selectors — Высокоуровневое множественное использование I/O

Введение

Этот модуль предоставляет высокоуровневое и эффективное множественное использование I/O, основанное на примитивах модуля select. Пользователям рекомендуется использовать этот модуль вместо него, если только они не хотят иметь точный контроль над используемыми примитивами на уровне ОС.

Он определяет абстрактный базовый класс BaseSelector вместе с несколькими конкретными реализациями (KqueueSelector, EpollSelector…), которые могут использоваться для ожидания уведомления о готовности I/O для нескольких файловых объектов. В дальнейшем под «файловым объектом» понимается любой объект с методом 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)