iofunc_notify()

Установить, опросить или удалить обработчик уведомлений

Прототип:

#include <sys/iofunc.h>
                                       
int iofunc_notify( resmgr_context_t *ctp,
                   io_notify_t *msg,
                   iofunc_notify_t *nop,
                   int trig,
                   const int *notifycounts,
                   int *armed );

Аргументы:

ctp

Указатель на структуру resmgr_context_t, которую библиотека менеджера ресурсов использует для передачи контекстной информации между функциями.

msg

Указатель на структуру io_notify_t, содержащую сообщение, полученное менеджером ресурсов.

nop

Массив структур iofunc_notify_t с поддерживаемыми менеджером ресурсов событиями. Ранее этот массив содержал три элемента: входные, выходные и нештатные списки уведомлений. После добавления расширенных событий (см. ниже) минимальный размер этого массива теперь равен трем. Фактический размер должен соответствовать количеству получаемых событий, но не более _NOTIFY_MAXCOND.

Как правило, эта структура используется менеджером ресурсов в рамках расширенной структуры атрибутов.

trig

Битовая маска, указывающая, какие события используются и могут сработать. Может использоваться два набора флагов. Значением может быть комбинация _NOTIFY_COND_INPUT, _NOTIFY_COND_OUTPUT и _NOTIFY_COND_OBAND, и дополнительно можно установить _NOTIFY_COND_EXTEN, чтобы указать следующие расширенные события:

_NOTIFY_CONDE_RDNORM

доступны обычные данные.

_NOTIFY_CONDE_WRNORM

место для обычных данных.

_NOTIFY_CONDE_RDBAND

доступны нештатные данные.

_NOTIFY_CONDE_PRI

доступны приоритетные данные.

_NOTIFY_CONDE_WRBAND

место для нештатных данных.

_NOTIFY_CONDE_ERR

ошибка устройства или потока.

_NOTIFY_CONDE_HUP

устройство было отключено.

_NOTIFY_CONDE_NVAL

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

Следующие флаги считаются эквивалентными:

_NOTIFY_COND_INPUT  == _NOTIFY_CONDE_RDNORM
_NOTIFY_COND_OUTPUT == _NOTIFY_CONDE_WRNORM
_NOTIFY_COND_OBAND  == _NOTIFY_CONDE_RDBAND

Установка флага _NOTIFY_COND_EXTEN влияет на параметр armed. Обычно это значение устанавливается в зависимости от условий в момент вызова.

notifycounts

NULL или массив целых чисел, обозначающих сколько элементов должно присутствовать в очереди каждого события, представленного в массиве nop, чтобы событие сработало. Этот массив и массив nop должны содержать одинаковое количество элементов. Обратите внимание, что если какое-либо из условий выполнено, то ничего не включается. Только если ни одно из условий не выполняется, событие включается в соответствии с параметром notifycounts. Если этот параметр NULL, то все счётчики равны единице.

armed

NULL или указатель на буфер, в который функция запишет 1, если уведомление включено, или 0 в противном случае.

Если установлен бит _NOTIFY_COND_EXTEN в аргументе trig, а armed не NULL, то при вызове iofunc_notify(), armed должен содержать количество элементов в массивах nop и notifycounts (при условии, что notifycounts не NULL. В противном случае функция предполагает, что в массивах nop и notifycounts три элемента.

Библиотека:

libc

Описание:

Вспомогательная функция уровня POSIX iofunc_notify() используется менеджером ресурсов для реализации уведомлений.

Эта функция проверяет сообщение, полученное менеджером ресурсов (передаётся в аргументе msg), и определяет, какое действие пытается выполнить пользовательский код:

_NOTIFY_ACTION_POLL

Возвращает однокомпонентный вектор ввода/вывода (IOV) с установленным полем flags, указывающим какие условия доступны (входные, выходные или нештатные). Вызывающий должен вернуть ( _RESMGR_NPARTS( 1 )) библиотеке менеджера ресурсов, возвращающей клиенту однокомпонентное сообщение.

_NOTIFY_ACTION_POLLARM

Аналогично _NOTIFY_ACTION_POLL, но включает дополнительные характеристики включения события если ни одно из условий не выполняется.

_NOTIFY_ACTION_TRANARM

Для каждого из указанных источников создать запись и сохранить в ней структуру события struct sigevent клиента. Обратите внимание, что одновременно для каждого устройства допускается только одно включение уведомления. Если клиент указывает событие SIGEV_NONE, то это выключает уведомление. При срабатывании события уведомление автоматически отключается.

Возвращаемое значение:

-1

Успешное завершение; библиотека менеджера ресурсов должна вернуть клиенту IOV, состоящий из одной части.

EBUSY

Уведомление для этого ресурса уже включено, эта библиотечная функция накладывает ограничение в одно уведомление для каждого ресурса.

Классификация:

ЗОСРВ «Нейтрино»

Безопасность использования

Точка остановки потока

Нет

Обработчик прерываний

Нет

Обработчик сигналов

Да

В потоке

Да

Тематические ссылки:

io_notify_t, iofunc_notify_t, iofunc_notify_remove(), iofunc_notify_trigger(), resmgr_context_t, _RESMGR_NPARTS(), struct sigevent

Предыдущий раздел: Описание API системной библиотеки