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)