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 ниже, чтобы узнать о методах, поддерживаемых объектами devpoll.

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

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

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

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

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

(Поддерживается только в Linux 2.5.44 и более поздних версиях.) Возвращает объект опроса событий, который может использоваться в качестве интерфейса для событий ввода-вывода с триггерами по краю или уровню. sizehint и flags устарели и полностью игнорируются.

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

Объекты 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 опущен, функция блокируется до тех пор, пока не будет готов хотя бы один дескриптор файла. Значение тайм-аута 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.

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.

2. Объекты опроса Edge и Level Trigger (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)

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

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

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

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

poll.register(fd[, eventmask])

Зарегистрировать дескриптор файла в объекте опроса. Будущие вызовы метода poll() будут проверять, есть ли у дескриптора файла ожидающие события ввода-вывода. fd может быть целым числом или объектом с методом fileno(), возвращающим целое число. Объекты файлов реализуют fileno(), поэтому их также можно использовать в качестве аргумента.

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

Константа	Значение
POLLIN	Есть данные для чтения
POLLPRI	Есть неотложные данные для чтения
POLLOUT	Готово к выводу: запись не заблокирует
POLLERR	Ошибка какого-то рода
POLLHUP	Отключено
POLLNVAL	Недействительный запрос: дескриптор не открыт

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

poll.modify(fd, eventmask)

Изменяет уже зарегистрированный дескриптор файла. Это имеет тот же эффект, что и 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.

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.

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 и %%%CODE_BLOCK_158%%:

Постоянная	Значение
KQ_NOTE_LOWAT	нижний предел заполнения буфера сокета

Флаги фильтров %%%CODE_BLOCK_160%%:

Постоянная	Значение
KQ_NOTE_DELETE	вызвано unlink()
KQ_NOTE_WRITE	произошла запись
KQ_NOTE_EXTEND	файл был расширен
KQ_NOTE_ATTRIB	было изменено атрибут
KQ_NOTE_LINK	изменилось число ссылок
KQ_NOTE_RENAME	файл был переименован
KQ_NOTE_REVOKE	доступ к файлу был отозван

Флаги фильтров %%%CODE_BLOCK_168%%:

Постоянная	Значение
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

Пользовательское значение.