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 или положительному целому числу
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: Значение, определяемое пользователем.