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)