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)