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)