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

---

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

Примечание

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

Availability: не WASI.

Этот модуль не работает или недоступен на WebAssembly. Дополнительную информацию см. в разделе Платформы WebAssembly.

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

exception select.error

Утративший силу псевдоним OSError.

Изменено в версии 3.3: После PEP 3151 этот класс стал псевдонимом OSError.

select.devpoll()

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

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

Новый дескриптор файла - non-inheritable.

Added in version 3.3.

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

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

(Поддерживается только в Linux 2.5.44 и новее.) Возвращает объект опроса края, который можно использовать в качестве интерфейса Edge или Level Triggered для событий ввода/вывода.

sizehint информирует epoll об ожидаемом количестве регистрируемых событий. Значение должно быть положительным, или -1, чтобы использовать значение по умолчанию. Он используется только в старых системах, где epoll_create1() недоступен; в противном случае он не имеет никакого эффекта (хотя его значение все равно проверяется).

flags является устаревшим и полностью игнорируется. Тем не менее, если он указан, его значение должно быть 0 или select.EPOLL_CLOEXEC, иначе будет получено значение OSError.

Методы, поддерживаемые объектами epolling, см. в разделе Опрос триггеров по фронту и уровню (epoll) Объекты ниже.

Объекты epoll поддерживают протокол управления контекстом: при использовании в операторе with новый дескриптор файла автоматически закрывается в конце блока.

Новый дескриптор файла - non-inheritable.

Изменено в версии 3.3: Добавлен параметр flags.

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

Не рекомендуется, начиная с версии 3.4: Параметр flags. По умолчанию используется select.EPOLL_CLOEXEC. Используйте os.set_inheritable(), чтобы сделать дескриптор файла наследуемым.

select.poll()

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

select.kqueue()

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

Новый дескриптор файла - non-inheritable.

Изменено в версии 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(), возвращающим такое целое число:

• список: дождаться готовности к чтению

• wlist: ждать, пока не будет готово к записи

• xlist: ожидание «исключительного условия» (см. страницу руководства о том, что ваша система считает таким условием)

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

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

Среди допустимых типов объектов в итерациях - Python file objects (например, sys.stdin или объекты, возвращаемые open() или os.popen()), объекты сокетов, возвращаемые socket.socket(). Вы также можете определить класс wrapper самостоятельно, если у него есть соответствующий метод fileno() (который действительно возвращает дескриптор файла, а не просто случайное целое число).

Примечание

Файловые объекты в Windows недопустимы, а вот сокеты - да. В Windows базовая функция select() предоставляется библиотекой WinSock и не обрабатывает дескрипторы файлов, которые не исходят от WinSock.

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

select.PIPE_BUF

Минимальное количество байт, которое может быть записано без блокировки в трубу, когда труба была объявлена готовой к записи с помощью select(), poll() или другого интерфейса в этом модуле. Это не относится к другим файлоподобным объектам, таким как сокеты.

POSIX гарантирует, что это значение будет не менее 512.

Availability: Unix

Added in version 3.2.

/dev/poll Опрашиваемые объекты

Solaris и производные имеют значение /dev/poll. В то время как select() - это O(самый высокий файловый дескриптор), а poll() - это O(количество файловых дескрипторов), /dev/poll - это O(активные файловые дескрипторы).

Поведение /dev/poll очень близко к поведению стандартного объекта poll().

devpoll.close()

Закрывает дескриптор файла объекта опроса.

Added in version 3.4.

devpoll.closed

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

Added in version 3.4.

devpoll.fileno()

Возвращает номер файлового дескриптора объекта опроса.

Added in version 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	Ошибка произошла при выполнении assoc. fd
EPOLLHUP	Повесьте трубку, если вы не знаете, что делать.
EPOLLET	Установите поведение Edge Trigger, по умолчанию - Level Trigger.
EPOLLONESHOT	Установите однократное поведение. После извлечения одного события fd внутренне отключается
EPOLLEXCLUSIVE	Будить только один объект epoll, когда на связанном с ним fd происходит событие. По умолчанию (если этот флаг не установлен) пробуждаются все объекты epoll, опрашиваемые на fd.
EPOLLRDHUP	Пир потокового сокета закрыл соединение или отключил пишущую половину соединения.
EPOLLRDNORM	Эквивалент EPOLLIN
EPOLLRDBAND	Приоритетная полоса данных может быть прочитана.
EPOLLWRNORM	Эквивалент EPOLLOUT
EPOLLWRBAND	Приоритетные данные могут быть записаны.
EPOLLMSG	Игнорируется.

Added in version 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() строит битовую карту, включает биты для интересующих fds, а затем всю битовую карту приходится линейно сканировать снова. 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()

Возвращает номер файлового дескриптора элемента управления fd.

kqueue.fromfd(fd)

Создание объекта kqueue из заданного дескриптора файла.

kqueue.control(changelist, max_events[, timeout]) → eventlist

Низкоуровневый интерфейс к kevent

• Список изменений должен быть итерируемым объектом kevent или None.

• max_events должно быть 0 или целое положительное число

• таймаут в секундах (можно плавающие значения); по умолчанию None, чтобы ждать вечно

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

Объекты Kevent

https://man.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2

kevent.ident

Значение, используемое для идентификации события. Интерпретация зависит от фильтра, но обычно это дескриптор файла. В конструкторе ident может быть либо int, либо объектом с методом 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	Disablesevent
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

Значение, определяемое пользователем.