Содержание страницы

O completion

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

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

exception select.error¶: Исключение, возникающее при ошибке. Сопутствующее значение – это пара, содержащая числовой код ошибки из errno и соответствующую строку, как она была бы выведена функцией C perror().

select.epoll([sizehint=-1])¶: (Поддерживается только на Linux 2.5.44 и новее.) Возвращает объект edge-опроса, который можно использовать как интерфейс с триггерами по фронту или по уровню для событий ввода/вывода; см. раздел Объекты опроса с триггерами по фронту и уровню (epoll) ниже, где перечислены методы, поддерживаемые объектами epoll.

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

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

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

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

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

Примечание

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

16.1.1. Объекты опроса с триггерами по фронту и уровню (epoll)¶Edge and Level Trigger Polling (epoll) Objects

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

eventmask

Константа Значение

EPOLLIN Доступен для чтения

EPOLLOUT Доступен для записи

EPOLLPRI Срочные данные для чтения

EPOLLERR Возникла ошибка на ассоциированном файловом дескрипторе

EPOLLHUP Произошёл разрыв соединения на ассоциированном файловом дескрипторе

EPOLLET Установить триггер по фронту (Edge Trigger), по умолчанию – триггер по уровню (Level Trigger)

EPOLLONESHOT Установить одноразовое поведение. После извлечения одного события файловый дескриптор внутренне отключается.

EPOLLRDNORM ???

EPOLLRDBAND ???

EPOLLWRNORM ???

EPOLLWRBAND ???

EPOLLMSG ???

Константа	Значение
`EPOLLIN`	Доступен для чтения
`EPOLLOUT`	Доступен для записи
`EPOLLPRI`	Срочные данные для чтения
`EPOLLERR`	Возникла ошибка на ассоциированном файловом дескрипторе
`EPOLLHUP`	Произошёл разрыв соединения на ассоциированном файловом дескрипторе
`EPOLLET`	Установить триггер по фронту (Edge Trigger), по умолчанию – триггер по уровню (Level Trigger)
`EPOLLONESHOT`	Установить одноразовое поведение. После извлечения одного события файловый дескриптор внутренне отключается.
`EPOLLRDNORM`	???
`EPOLLRDBAND`	???
`EPOLLWRNORM`	???
`EPOLLWRBAND`	???
`EPOLLMSG`	???

epoll.close()¶: Закрывает управляющий файловый дескриптор объекта epoll.

epoll.fileno()¶: Возвращает номер файлового дескриптора управляющего fd.

epoll.fromfd(fd)¶: Создает объект epoll из заданного файлового дескриптора.

epoll.register(fd[, eventmask])¶: Регистрирует файловый дескриптор в объекте epoll.

Примечание

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

epoll.modify(fd, eventmask)¶: Изменяет зарегистрированный файловый дескриптор.

epoll.unregister(fd)¶: Удаляет зарегистрированный файловый дескриптор из объекта epoll.

epoll.poll([timeout=-1[, maxevents=-1]])¶: Ожидает события. timeout в секундах (float)

16.1.2. Объекты опроса¶Polling Objects

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

poll.unregister(fd)¶

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

Попытка удалить файловый дескриптор, который не был зарегистрирован, вызывает исключение KeyError.

poll.poll([timeout])¶: Опрашивает набор зарегистрированных файловых дескрипторов и возвращает возможно пустой список, содержащий кортежи из двух элементов (fd, event) для дескрипторов, по которым есть события или ошибки. fd – файловый дескриптор, а event – битовая маска с установленными битами для сообщаемых событий этого дескриптора: POLLIN для ожидания ввода, POLLOUT – для указания, что в дескриптор можно писать, и так далее. Пустой список означает, что вызов завершился по тайм-ауту и ни один файловый дескриптор не имел событий. Если указан timeout, он задаёт время в миллисекундах, которое система будет ждать событий перед возвратом. Если timeout опущен, отрицателен или равен None, вызов будет блокироваться до появления события для этого объекта опроса.

16.1.3. Объекты Kqueue¶Kqueue Objects

kqueue.close()¶: Закрывает файловый дескриптор управления объекта kqueue.

kqueue.fileno()¶: Возвращает номер файлового дескриптора управляющего fd.

kqueue.fromfd(fd)¶: Создаёт объект kqueue из заданного файлового дескриптора.

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

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

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

16.1.4. Объекты Kevent¶Kevent Objects

http://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¶: Значение, определённое пользователем.