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

Added in version 3.4.

Источник: Lib/selectors.py

Введение

Этот модуль обеспечивает высокоуровневое и эффективное мультиплексирование ввода-вывода, построенное на примитивах модуля select. Пользователям рекомендуется использовать этот модуль, если только они не хотят получить точный контроль над используемыми примитивами на уровне ОС.

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

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

Примечание

Тип поддерживаемых файловых объектов зависит от платформы: в Windows поддерживаются сокеты, но не pipes, в то время как в Unix поддерживаются оба типа (могут поддерживаться и некоторые другие типы, например fifos или специальные файловые устройства).

См.также

select

Модуль низкоуровневого мультиплексирования ввода/вывода.

Availability: не WASI.

Этот модуль не работает или недоступен на WebAssembly. Дополнительную информацию см. в разделе Платформы WebAssembly.

Занятия

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

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

Далее events - это побитовая маска, указывающая, какие события ввода-вывода следует ожидать для данного файлового объекта. Это может быть комбинация констант модулей, приведенных ниже:

Постоянно

Значение
selectors.EVENT_READ

Доступно для чтения
selectors.EVENT_WRITE

Доступно для записи
class selectors.SelectorKey

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

fileobj

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

fd

Дескриптор базового файла.

events

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

data

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

class selectors.BaseSelector

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

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

Added in version 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)