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 Поlling Objects ниже для методов, поддерживаемых объектами 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.

См. раздел Edge and Level Trigger Polling (epoll) Objects ниже для методов, поддерживаемых объектами epoll.

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

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

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

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

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

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

select.kqueue()

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

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

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

select.kevent(ident, filter=KQ_FILTER_READ, flags=KQ_EV_ADD, fflags=0, data=0, udata=0): (Поддерживается только в BSD.) Возвращает объект события ядра; см. раздел Kevent Objects ниже для методов, поддерживаемых объектами 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.

Предупреждение

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

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`	Сокет типа stream: удалённое соединение или остановлена запись.
`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.

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

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

END_OF_DOCUMENT_MARKER

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

Системный вызов 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): Изменяет уже зарегистрированный дескриптор файла. Это имеет тот же эффект, что и register(fd, eventmask). Попытка изменить дескриптор файла, который никогда не был зарегистрирован, вызывает исключение OSError с errno ENOENT.

poll.unregister(fd)

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

Попытка удалить дескриптор файла, который никогда не был зарегистрирован, вызывает исключение 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(): Возвращает номер дескриптора файла управляющего fd.

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`	Отслеживание событий на сетевом устройстве [не доступно в Mac OS X]
`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 (не доступны в Mac OS X):

Константа	Значение
`KQ_NOTE_LINKUP`	соединение установлено
`KQ_NOTE_LINKDOWN`	соединение разорвано
`KQ_NOTE_LINKINV`	состояние соединения недействительно

kevent.data: Данные, специфичные для фильтра.

kevent.udata: Значение, заданное пользователем.

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

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

Объекты опроса с срабатыванием по краю и уровню (epoll)

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

Объекты Kqueue

Объекты Kevent

`/dev/poll` Объекты опроса