Использование условных переменных (condvar.h)

API определен в заголовочном файле sysroot-*-kos/include/kos/condvar.h из состава KasperskyOS SDK. Также в составе KasperskyOS SDK поставляется заголовочный файл sysroot-*-kos/include/kos/sync_api.h, который дает возможность транзитивно включить в исходный код программы заголовочный файл condvar.h и заголовочные файлы для использования других примитивов синхронизации.

API предназначен для синхронизации потоков исполнения на основе условных переменных. Условная переменная – примитив синхронизации, который используется для уведомления одного или нескольких потоков исполнения о выполнении требуемого этим потокам условия. Условная переменная используется совместно с мьютексом (мьютекс без поддержки наследования приоритета). Уведомляющий и уведомляемый потоки захватывают мьютекс для исполнения критических секций. Уведомляемый поток при исполнении критической секции проверяет, выполняется ли требуемое ему условие (например, подготовлены ли данные уведомляющим потоком). Если условие выполняется, то уведомляемый поток исполняет критическую секцию и освобождает мьютекс. Если условие не выполняется, то уведомляемый поток блокируется на условной переменной, ожидая выполнения условия. При этом мьютекс автоматически освобождается. Уведомляющий поток при исполнении критической секции проверяет, выполняется ли условие, требуемое уведомляемому потоку. Если условие выполняется, то уведомляющий поток сигнализирует об этом через условную переменную и освобождает мьютекс. Уведомляемый поток, заблокированный в ожидании выполнения требуемого ему условия, возобновляет исполнение критической секции, автоматически захватывая мьютекс. После исполнения критической секции уведомляемый поток освобождает мьютекс.

Сведения о функциях API приведены в таблице ниже.

Использование API

Типовой сценарий использования API включает следующие шаги:

Инициализация условной переменной и мьютекса.
Чтобы инициализировать условную переменную, нужно вызвать функцию KosCondvarInit().
Использование условной переменной и мьютекса потоками исполнения.

Использование условной переменной и мьютекса на стороне уведомляемых потоков исполнения включает следующие шаги:

Захват мьютекса.
Проверка выполнения условия.
Ожидание выполнения условия вызовом функции KosCondvarWait() или KosCondvarWaitTimeout().
После возврата функции KosCondvarWait() или KosCondvarWaitTimeout() обычно нужно снова проверить, что условие выполняется, так как другой уведомляемый поток исполнения также получил сигнал и мог сделать условие снова недействительным. (Например, другой поток мог извлечь данные, подготовленные уведомляющим потоком). Для этого нужно использовать следующую конструкцию:

while(<условие>)

<вызов KosCondvarWait() или KosCondvarWaitTimeout()>
Освобождение мьютекса.

Использование условной переменной и мьютекса на стороне уведомляющих потоков исполнения включает следующие шаги:

Захват мьютекса.
Проверка выполнения условия.
Сигнализация о выполнении условия вызовом функции KosCondvarSignal() или KosCondvarBroadcast().
Освобождение мьютекса.

Сведения о функциях API

Функции condvar.h

Функция	Сведения о функции
`KosCondvarInit()`	Назначение Инициализирует условную переменную. Параметры [out] `condvar` – указатель на условную переменную. Тип условной переменной определен в заголовочном файле `sysroot-*-kos/include/kos/sync_types.h` из состава KasperskyOS SDK. Возвращаемые значения Нет.
`KosCondvarWaitTimeout()`	Назначение Ожидает выполнения условия не дольше заданного времени. Параметры [in] `condvar` – указатель на условную переменную. Тип условной переменной определен в заголовочном файле `sysroot--kos/include/kos/sync_types.h` из состава KasperskyOS SDK. [in,out] `mutex` – указатель на мьютекс. Тип мьютекса определен в заголовочном файле `sysroot--kos/include/kos/sync_types.h` из состава KasperskyOS SDK. [in] `mdelay` – время ожидания выполнения условия в миллисекундах или `INFINITE_TIMEOUT`, чтобы задать неограниченное время ожидания. Константа `INFINITE_TIMEOUT` определена в заголовочном файле `sysroot-*-kos/include/rtl/rtc.h` из состава KasperskyOS SDK. Возвращаемые значения В случае успеха возвращает `rcOk`. Если время ожидания истекло, возвращает `rcTimeout`. Дополнительные сведения Неблокирующий вызов, если в параметре `mdelay` указан `0`.
`KosCondvarWait()`	Назначение Ожидает выполнения условия сколь угодно долго. Параметры [in] `condvar` – указатель на условную переменную. Тип условной переменной определен в заголовочном файле `sysroot--kos/include/kos/sync_types.h` из состава KasperskyOS SDK. [in,out] `mutex` – указатель на мьютекс. Тип мьютекса определен в заголовочном файле `sysroot--kos/include/kos/sync_types.h` из состава KasperskyOS SDK. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosCondvarSignal()`	Назначение Сигнализирует о выполнении условия одному из потоков исполнения, ожидающих выполнения этого условия. Параметры [in,out] `condvar` – указатель на условную переменную. Тип условной переменной определен в заголовочном файле `sysroot-*-kos/include/kos/sync_types.h` из состава KasperskyOS SDK. Возвращаемые значения Нет.
`KosCondvarBroadcast()`	Назначение Сигнализирует о выполнении условия всем потокам исполнения, ожидающим выполнения этого условия. Параметры [in,out] `condvar` – указатель на условную переменную. Тип условной переменной определен в заголовочном файле `sysroot-*-kos/include/kos/sync_types.h` из состава KasperskyOS SDK. Возвращаемые значения Нет.

В начало