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

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

Примечание

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

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

Этот модуль не работает или недоступен в WebAssembly. Дополнительные сведения см. в разделе Платформы 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 или положительному целому числу
timeout задаётся в секундах (допускаются числа с плавающей точкой); значение по умолчанию — 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` Объекты опроса