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

Исходный код: Lib/selectors.py

18.4.1. Введение

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

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

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

18.4.2. Классы

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

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

В дальнейшем события — это битовая маска, указывающая, какие события I/O должны ожидать на данном файловом объекте. Это может быть комбинацией констант модулей ниже:

class selectors.SelectorKey

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

fileobj

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

fd

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

events

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

data

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

class selectors.BaseSelector

BaseSelector используется для ожидания готовности события I/O на нескольких файловых объектах. Он поддерживает регистрацию, отмену регистрации файловых потоков и метод ожидания событий I/O в этих потоках с необязательным таймаутом. Это абстрактный базовый класс, поэтому его нельзя создать. Используйте DefaultSelector вместо этого или один из SelectSelector, KqueueSelector и т.д., если вы хотите использовать конкретную реализацию, и ваша платформа ее поддерживает. BaseSelector и его конкретные реализации поддерживают протокол менеджера контекста.

abstractmethod register(fileobj, events, data=None)

Зарегистрировать файловый объект для выбора, отслеживая его на наличие событий I/O.

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().

18.4.3. Примеры

Вот пример реализации простого эхо-сервера:

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)