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

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

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

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

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

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

Доступность: Solaris.

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

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

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

Доступность: Linux >= 2.5.44.

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

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

select.kqueue()

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

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

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

Доступность: BSD, macOS.

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

Доступность: BSD, macOS.

select.select(rlist, wlist, xlist, timeout=None)

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

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

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

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

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

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

Добавлено в версии 3.14: Добавлена константа EPOLLWAKEUP. Она поддерживается только ядром Linux версии 3.5 или новее.

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

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

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

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

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

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

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

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

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

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

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

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

poll.register(fd[, eventmask])

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

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

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

poll.modify(fd, eventmask): Изменяет уже зарегистрированный fd. Это равносильно вызову 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: Определяемое пользователем значение.