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

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

Примечание

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

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

exception select.error: Устаревшее алиас класса OSError.

Изменено в версии 3.3: Следуя PEP 3151, этот класс был переименован в алиас OSError.

select.devpoll()

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

Объекты 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 опущен, функция блокируется до тех пор, пока хотя бы один дескриптор файла не будет готов. Значение таймаута 0 задаёт опрос и никогда не блокирует.

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

К приемлемым типам объектов в итерируемых объектах относятся 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.

END_OF_DOCUMENT_MARKER

`/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) кортежи 2-х элементов для дескрипторов, у которых есть события или ошибки для отчёта. 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`	Произошло состояние ошибки в ассоциированном fd
`EPOLLHUP`	Произошел обрыв соединения в ассоциированном fd
`EPOLLET`	Установить поведение триггера по краю, по умолчанию используется поведение триггера по уровню
`EPOLLONESHOT`	Установить одноразовое поведение. После извлечения одного события fd внутренне отключается
`EPOLLEXCLUSIVE`	Разбудить только один объект epoll, когда у ассоциированного fd есть событие. По умолчанию (если этот флаг не установлен) разбуждаются все объекты epoll, опрашивающие fd.
`EPOLLRDHUP`	Клиент сокета потока закрыл соединение или отключил запись половины соединения.
`EPOLLRDNORM`	Эквивалентно `EPOLLIN`
`EPOLLRDBAND`	Данные приоритетной полосы могут быть прочитаны.
`EPOLLWRNORM`	Эквивалентно `EPOLLOUT`
`EPOLLWRBAND`	Данные приоритета могут быть записаны.
`EPOLLMSG`	Игнорируется.

Новое в версии 3.6: EPOLLEXCLUSIVE было добавлено. Оно поддерживается только ядром Linux 4.5 или более поздней версии.

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

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

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

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

epoll.register(fd[, eventmask]): Зарегистрировать дескриптор fd в объекте epoll.

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

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

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

epoll.poll(timeout=None, maxevents=- 1): Ожидание событий. таймаут в секундах (float)

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

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

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

poll.register(fd[, eventmask])

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

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

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

Регистрация уже зарегистрированного дескриптора файла не является ошибкой и имеет такой же эффект, как регистрация дескриптора ровно один раз.

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

poll.unregister(fd)

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

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

poll.poll([timeout]): Опрашивает набор зарегистрированных дескрипторов файлов и возвращает, возможно, пустой список, содержащий (fd, event) кортежей 2-элементов для дескрипторов, у которых есть события или ошибки, требующие отчета. 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, для ожидания вечно

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

Объекты Kevent

https://www.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: Пользовательское значение.