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

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

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

exception select.error

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

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

select.devpoll()

(Поддерживается только в Solaris и производных системах.) Возвращает объект опроса /dev/poll; см. раздел /dev/poll Polling 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 ниже для методов, поддерживаемых объектами epolling.

Объекты 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.

18.3.1. /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.

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

http://linux.die.net/man/4/epoll

eventmask

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=-1, maxevents=-1)

Ожидать событий. timeout в секундах (float)

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

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

Системный вызов poll(), поддерживаемый на большинстве Unix-систем, обеспечивает лучшую масштабируемость для серверов приложений, обслуживающих множество клиентов одновременно. poll() масштабируется лучше, потому что системный вызов требует только указания дескрипторов файлов, которые нужно отслеживать, в то время как select() строит битовую карту, включает биты для интересных fd и затем после этого снова нужно линейно просмотреть всю битовую карту. 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.

18.3.4. Объекты Kqueue

kqueue.close()

Закрыть дескриптор управляющего файла объекта kqueue.

kqueue.closed

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

kqueue.fileno()

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

kqueue.fromfd(fd)

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

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

Интерфейс низкого уровня к kevent

• changelist должен быть итерируемым объектом kevent или None
• max_events должен быть 0 или положительным целым числом
• timeout в секундах (допускаются числа с плавающей точкой)

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

18.3.5. Объекты 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

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