select — Ожидание завершения операций ввода-вывода

Этот модуль предоставляет доступ к функциям select() и poll(), доступным в большинстве операционных систем, devpoll(), доступной в Solaris и производных системах, epoll(), доступной в Linux 2.5 и новее, и kqueue(), доступной в большинстве BSD. Обратите внимание: в Windows модуль работает только с сокетами; в других операционных системах он также работает с файлами других типов (в частности, в Unix — с каналами). Его нельзя использовать с обычными файлами, чтобы определить, вырос ли файл с момента последнего чтения.

Примечание

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

Доступность: недоступен в Emscripten и WASI.

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

Модуль определяет следующее:

exception select.error: Устаревший псевдоним OSError.

Изменено в версии 3.3: В соответствии с PEP 3151 этот класс стал псевдонимом OSError.

select.devpoll()

(Поддерживается только в Solaris и производных системах.) Возвращает объект опроса /dev/poll; поддерживаемые объектами devpoll методы описаны ниже в разделе Объекты опроса /dev/poll.

Объекты devpoll() связаны с количеством файловых дескрипторов, разрешённым на момент создания объекта. Если программа уменьшит это значение, вызов devpoll() завершится ошибкой. Если программа увеличит это значение, вызов devpoll() может вернуть неполный список активных файловых дескрипторов.

Новый файловый дескриптор является непередаваемым по наследству.

Добавлено в версии 3.3.

Изменено в версии 3.4: Теперь новый файловый дескриптор не передаётся по наследству.

select.epoll(sizehint=-1, flags=0)

(Поддерживается только в Linux 2.5.44 и новее.) Возвращает объект опроса по фронту сигнала, который можно использовать как интерфейс с триггером по фронту или по уровню для событий ввода-вывода.

sizehint сообщает epoll ожидаемое количество регистрируемых событий. Значение должно быть положительным или -1, чтобы использовать значение по умолчанию. Оно используется только в старых системах, где epoll_create1() недоступен; в противном случае оно не влияет на работу (хотя его значение всё равно проверяется).

Параметр flags устарел и полностью игнорируется. Однако, если он задан, его значение должно быть 0 или select.EPOLL_CLOEXEC, иначе будет вызвано исключение OSError.

Поддерживаемые объектами epoll методы описаны ниже в разделе Объекты опроса по фронту и уровню сигнала (epoll).

Объекты epoll поддерживают протокол управления контекстом: при использовании в инструкции with новый файловый дескриптор автоматически закрывается в конце блока.

Новый файловый дескриптор является непередаваемым по наследству.

Изменено в версии 3.3: Добавлен параметр flags.

Изменено в версии 3.4: Добавлена поддержка инструкции with. Теперь новый файловый дескриптор не передаётся по наследству.

Устарело с версии 3.4: Параметр flags. Теперь по умолчанию используется select.EPOLL_CLOEXEC. Чтобы сделать файловый дескриптор передаваемым по наследству, используйте os.set_inheritable().

select.poll(): (Поддерживается не всеми операционными системами.) Возвращает объект опроса, который позволяет регистрировать и отменять регистрацию файловых дескрипторов, а затем опрашивать их на наличие событий ввода-вывода; поддерживаемые объектами опроса методы описаны ниже в разделе Объекты опроса.

select.kqueue()

(Поддерживается только в BSD.) Возвращает объект очереди ядра; поддерживаемые объектами kqueue методы описаны ниже в разделе Объекты Kqueue.

Новый файловый дескриптор является непередаваемым по наследству.

Изменено в версии 3.4: Теперь новый файловый дескриптор не передаётся по наследству.

select.kevent(ident, filter=KQ_FILTER_READ, flags=KQ_EV_ADD, fflags=0, data=0, udata=0): (Поддерживается только в BSD.) Возвращает объект события ядра; поддерживаемые объектами kevent методы описаны ниже в разделе Объекты Kevent.

select.select(rlist, wlist, xlist[, timeout])

Это простой интерфейс к системному вызову Unix select(). Первые три аргумента — итерируемые объекты, содержащие «объекты, готовые к ожиданию»: целые числа, представляющие файловые дескрипторы, или объекты с методом без параметров с именем fileno(), возвращающим такое целое число:

rlist: ожидать готовности к чтению
wlist: ожидать готовности к записи
xlist: ожидать «исключительную ситуацию» (описание того, что система считает такой ситуацией, см. на странице руководства)

Пустые итерируемые объекты допускаются, но возможность передать три пустых итерируемых объекта зависит от платформы. (Известно, что это работает в Unix, но не в Windows.) Необязательный аргумент timeout задаёт время ожидания в секундах числом с плавающей точкой. Если аргумент timeout не указан, функция блокируется до готовности хотя бы одного файлового дескриптора. Значение времени ожидания, равное нулю, задаёт опрос без блокировки.

Возвращаемое значение — кортеж из трёх списков готовых объектов: подмножеств первых трёх аргументов. Если время ожидания истекло, а ни один файловый дескриптор не стал готовым, возвращаются три пустых списка.

К допустимым типам объектов в итерируемых объектах относятся файловые объекты Python файловые объекты (например, sys.stdin или объекты, возвращённые функциями open() или os.popen()), а также объекты сокетов, возвращённые функцией socket.socket(). Можно также самостоятельно определить класс-обёртку, если у него есть подходящий метод fileno() (который действительно возвращает файловый дескриптор, а не произвольное целое число).

Примечание

Файловые объекты в Windows не допускаются, но сокеты допускаются. В Windows базовая функция select() предоставляется библиотекой WinSock и не обрабатывает файловые дескрипторы, не созданные WinSock.

Изменено в версии 3.5: Теперь при прерывании сигналом функция вызывается повторно с пересчитанным временем ожидания, кроме случаев, когда обработчик сигнала вызывает исключение (обоснование см. в PEP 475); вместо этого исключение InterruptedError не вызывается.

select.PIPE_BUF

Минимальное количество байтов, которое можно записать в канал без блокировки, если функция select(), poll() или другой интерфейс этого модуля сообщил о готовности канала к записи. Это не относится к другим типам файловых объектов, например сокетам.

POSIX гарантирует, что это значение не меньше 512.

Доступность: Unix

Добавлено в версии 3.2.

`/dev/poll` Объекты опроса

В Solaris и производных системах есть /dev/poll. Если select() имеет сложность O(наибольший файловый дескриптор), а poll() — O(количество файловых дескрипторов), то /dev/poll имеет сложность O(активные файловые дескрипторы).

Поведение /dev/poll очень близко к поведению стандартного объекта poll().

devpoll.close(): Закрывает файловый дескриптор объекта опроса.

Добавлено в версии 3.4.

devpoll.closed: Значение True, если объект опроса закрыт.

Добавлено в версии 3.4.

devpoll.fileno(): Возвращает номер файлового дескриптора объекта опроса.

Добавлено в версии 3.4.

devpoll.register(fd[, eventmask])

Регистрирует файловый дескриптор в объекте опроса. Последующие вызовы метода poll() будут проверять наличие ожидающих событий ввода-вывода для файлового дескриптора. В качестве fd можно передать целое число или объект с методом fileno(), возвращающим целое число. Файловые объекты реализуют fileno(), поэтому их также можно передавать в качестве аргумента.

eventmask — необязательная битовая маска, описывающая типы событий, которые требуется проверять. Константы совпадают с константами объекта poll(). Значение по умолчанию — комбинация констант POLLIN, POLLPRI и POLLOUT.

Предупреждение

Повторная регистрация уже зарегистрированного файлового дескриптора не считается ошибкой, но результат не определён. В этом случае следует сначала отменить регистрацию дескриптора или изменить её параметры. Это важное отличие от poll().

devpoll.modify(fd[, eventmask]): Этот метод выполняет unregister(), а затем register(). Это (немного) эффективнее, чем выполнять те же действия явно.

devpoll.unregister(fd)

Удаляет файловый дескриптор из списка отслеживаемых объектом опроса. Как и в методе register(), в качестве fd можно передать целое число или объект с методом fileno(), возвращающим целое число.

Попытка удалить файловый дескриптор, который никогда не регистрировался, безопасно игнорируется.

devpoll.poll([timeout]): Опросить набор зарегистрированных файловых дескрипторов и вернуть, возможно, пустой список, содержащий (fd, event) кортежи из двух элементов для дескрипторов, о которых нужно сообщить события или ошибки. fd — файловый дескриптор, а event — битовая маска с установленными битами для событий, о которых сообщается для этого дескриптора: POLLIN означает ожидание ввода, POLLOUT указывает, что в дескриптор можно записывать, и так далее. Пустой список означает, что время ожидания истекло и для файловых дескрипторов не было событий, о которых нужно сообщить. Если задан timeout, он определяет время ожидания событий в миллисекундах. Если timeout не указан, равен -1 или None, вызов будет блокироваться до появления события для этого объекта опроса.

Изменено в версии 3.5: Теперь при прерывании сигналом функция вызывается повторно с пересчитанным временем ожидания, кроме случаев, когда обработчик сигнала вызывает исключение (обоснование см. в PEP 475); вместо этого исключение InterruptedError не вызывается.

Объекты опроса по фронту и уровню сигнала (epoll)

https://linux.die.net/man/4/epoll

eventmask

Константа	Значение
`EPOLLIN`	Доступен для чтения
`EPOLLOUT`	Доступен для записи
`EPOLLPRI`	Срочные данные доступны для чтения
`EPOLLERR`	В связанном файловом дескрипторе возникла ошибка
`EPOLLHUP`	Связанный файловый дескриптор отключён
`EPOLLET`	Включить режим триггера по фронту; по умолчанию используется режим триггера по уровню
`EPOLLONESHOT`	Включить одноразовый режим. После получения одного события файловый дескриптор отключается внутри системы
`EPOLLEXCLUSIVE`	Будить только один объект epoll, если для связанного файлового дескриптора возникло событие. По умолчанию (если этот флаг не установлен) пробуждаются все объекты epoll, опрашивающие файловый дескриптор.
`EPOLLRDHUP`	Партнёр по потоковому сокету закрыл соединение или завершил передачу данных в одном направлении.
`EPOLLRDNORM`	Эквивалент `EPOLLIN`
`EPOLLRDBAND`	Доступны для чтения данные приоритетного класса.
`EPOLLWRNORM`	Эквивалент `EPOLLOUT`
`EPOLLWRBAND`	Данные приоритетного класса доступны для записи.
`EPOLLMSG`	Игнорируется.

Добавлено в версии 3.6: Добавлена EPOLLEXCLUSIVE. Поддерживается только ядром Linux версии 4.5 и новее.

epoll.close(): Закрывает управляющий файловый дескриптор объекта epoll.

epoll.closed: Значение True, если объект epoll закрыт.

epoll.fileno(): Возвращает номер управляющего файлового дескриптора.

epoll.fromfd(fd): Создаёт объект epoll из заданного файлового дескриптора.

epoll.register(fd[, eventmask]): Регистрирует файловый дескриптор в объекте epoll.

epoll.modify(fd, eventmask): Изменяет зарегистрированный файловый дескриптор.

epoll.unregister(fd): Удаляет зарегистрированный файловый дескриптор из объекта epoll.

Изменено в версии 3.9: Теперь метод не игнорирует ошибку EBADF.

epoll.poll(timeout=None, maxevents=-1): Ожидает события. Время ожидания задаётся в секундах (числом с плавающей точкой).

Изменено в версии 3.5: Теперь при прерывании сигналом функция вызывается повторно с пересчитанным временем ожидания, кроме случаев, когда обработчик сигнала вызывает исключение (обоснование см. в PEP 475); вместо этого исключение InterruptedError не вызывается.

Объекты опроса

Системный вызов poll(), поддерживаемый большинством систем Unix, обеспечивает лучшую масштабируемость сетевых серверов, обслуживающих одновременно очень большое количество клиентов. poll() масштабируется лучше, поскольку системный вызов требует только перечислить интересующие файловые дескрипторы, тогда как select() создаёт битовую карту, устанавливает биты для интересующих файловых дескрипторов, а затем линейно сканирует всю карту. Сложность select() составляет O(наибольший файловый дескриптор), тогда как сложность poll() — O(количество файловых дескрипторов).

poll.register(fd[, eventmask])

eventmask — необязательная битовая маска, описывающая типы событий, которые требуется проверять. Она может представлять собой комбинацию констант POLLIN, POLLPRI и POLLOUT, описанных в таблице ниже. Если значение не задано, по умолчанию проверяются все три типа событий.

Константа	Значение
`POLLIN`	Есть данные для чтения
`POLLPRI`	Есть срочные данные для чтения
`POLLOUT`	Готов к выводу: запись не будет блокироваться
`POLLERR`	Возникла ошибка какого-либо рода
`POLLHUP`	Соединение разорвано
`POLLRDHUP`	Партнёр по потоковому сокету закрыл соединение или завершил передачу данных в одном направлении
`POLLNVAL`	Недопустимый запрос: дескриптор не открыт

Повторная регистрация уже зарегистрированного файлового дескриптора не считается ошибкой и равносильна однократной регистрации дескриптора.

poll.modify(fd, eventmask): Изменяет уже зарегистрированный файловый дескриптор. Результат такой же, как при вызове register(fd, eventmask). Попытка изменить файловый дескриптор, который никогда не регистрировался, вызывает исключение OSError с кодом errno ENOENT.

poll.unregister(fd)

Попытка удалить файловый дескриптор, который никогда не регистрировался, вызывает исключение KeyError.

poll.poll([timeout]): Опросить набор зарегистрированных файловых дескрипторов и вернуть, возможно, пустой список, содержащий (fd, event) кортежи из двух элементов для дескрипторов, о которых нужно сообщить события или ошибки. fd — файловый дескриптор, а event — битовая маска с установленными битами для событий, о которых сообщается для этого дескриптора: POLLIN означает ожидание ввода, POLLOUT указывает, что в дескриптор можно записывать, и так далее. Пустой список означает, что время ожидания истекло и для файловых дескрипторов не было событий, о которых нужно сообщить. Если задан timeout, он определяет время ожидания событий в миллисекундах. Если timeout не указан, отрицателен или равен None, вызов будет блокироваться до появления события для этого объекта опроса.

Изменено в версии 3.5: Теперь при прерывании сигналом функция вызывается повторно с пересчитанным временем ожидания, кроме случаев, когда обработчик сигнала вызывает исключение (обоснование см. в PEP 475); вместо этого исключение InterruptedError не вызывается.

Объекты Kqueue

kqueue.close(): Закрывает управляющий файловый дескриптор объекта kqueue.

kqueue.closed: Значение True, если объект kqueue закрыт.

kqueue.fileno(): Возвращает номер управляющего файлового дескриптора.

kqueue.fromfd(fd): Создаёт объект kqueue из заданного файлового дескриптора.

kqueue.control(changelist, max_events[, timeout]) → eventlist

Низкоуровневый интерфейс к kevent

changelist должен быть итерируемым объектом, содержащим объекты kevent, или None
max_events должен быть равен 0 или положительным целым числом
время ожидания задаётся в секундах (допускаются числа с плавающей точкой); значение по умолчанию — None, то есть бесконечное ожидание

Объекты Kevent

https://man.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2

kevent.ident: Значение, используемое для идентификации события. Интерпретация зависит от фильтра, но обычно это файловый дескриптор. В конструкторе ident может быть целым числом или объектом с методом fileno(). kevent хранит целое число внутри.

kevent.filter

Имя фильтра ядра.

Константа	Значение
`KQ_FILTER_READ`	Принимает дескриптор и возвращает управление при появлении данных, доступных для чтения
`KQ_FILTER_WRITE`	Принимает дескриптор и возвращает управление при появлении данных, доступных для записи
`KQ_FILTER_AIO`	Запросы AIO
`KQ_FILTER_VNODE`	Возвращает управление при возникновении одного или нескольких запрошенных событий, отслеживаемых в fflag
`KQ_FILTER_PROC`	Отслеживает события для идентификатора процесса
`KQ_FILTER_NETDEV`	Отслеживает события сетевого устройства [недоступно в macOS]
`KQ_FILTER_SIGNAL`	Возвращает управление при доставке отслеживаемого сигнала процессу
`KQ_FILTER_TIMER`	Создаёт таймер произвольного действия

kevent.flags

Действие фильтра.

Константа	Значение
`KQ_EV_ADD`	Добавляет событие или изменяет его
`KQ_EV_DELETE`	Удаляет событие из очереди
`KQ_EV_ENABLE`	Разрешает control() возвращать событие
`KQ_EV_DISABLE`	Отключает событие
`KQ_EV_ONESHOT`	Удаляет событие после первого возникновения
`KQ_EV_CLEAR`	Сбрасывает состояние после получения события
`KQ_EV_SYSFLAGS`	внутреннее событие
`KQ_EV_FLAG1`	внутреннее событие
`KQ_EV_EOF`	Специальное условие EOF для фильтра
`KQ_EV_ERROR`	См. возвращаемые значения

kevent.fflags

Специальные флаги фильтра.

Флаги фильтров KQ_FILTER_READ и KQ_FILTER_WRITE:

Константа	Значение
`KQ_NOTE_LOWAT`	нижняя граница буфера сокета

Флаги фильтра KQ_FILTER_VNODE:

Константа	Значение
`KQ_NOTE_DELETE`	была вызвана функция unlink()
`KQ_NOTE_WRITE`	произошла запись
`KQ_NOTE_EXTEND`	файл был увеличен
`KQ_NOTE_ATTRIB`	атрибут был изменён
`KQ_NOTE_LINK`	изменилось количество ссылок
`KQ_NOTE_RENAME`	файл был переименован
`KQ_NOTE_REVOKE`	доступ к файлу был отозван

Флаги фильтра KQ_FILTER_PROC:

Константа	Значение
`KQ_NOTE_EXIT`	процесс завершился
`KQ_NOTE_FORK`	процесс вызвал fork()
`KQ_NOTE_EXEC`	процесс выполнил новый процесс
`KQ_NOTE_PCTRLMASK`	внутренний флаг фильтра
`KQ_NOTE_PDATAMASK`	внутренний флаг фильтра
`KQ_NOTE_TRACK`	отслеживать процесс после вызова fork()
`KQ_NOTE_CHILD`	возвращается для дочернего процесса при использовании NOTE_TRACK
`KQ_NOTE_TRACKERR`	не удалось подключиться к дочернему процессу

Флаги фильтра KQ_FILTER_NETDEV (недоступны в macOS):

Константа	Значение
`KQ_NOTE_LINKUP`	соединение установлено
`KQ_NOTE_LINKDOWN`	соединение разорвано
`KQ_NOTE_LINKINV`	состояние соединения недопустимо

kevent.data: Специальные данные фильтра.

kevent.udata: Значение, определённое пользователем.

select — Ожидание завершения операций ввода-вывода

/dev/poll Объекты опроса

Объекты опроса по фронту и уровню сигнала (epoll)

Объекты опроса

Объекты Kqueue

Объекты Kevent

`/dev/poll` Объекты опроса