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): Ожидать событий. timeout в секундах (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, чтобы ждать вечно

Объекты 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: Пользовательское значение.