Использование примитивов синхронизации (event.h, mutex.h, rwlock.h, semaphore.h, condvar.h)

Библиотека libkos предоставляет API, позволяющие использовать следующие примитивы синхронизации:

события (event.h);
мьютексы (mutex.h);
блокировки чтения-записи (rwlock.h);
семафоры (semaphore.h);
условные переменные (condvar.h).

Заголовочные файлы находятся в KasperskyOS SDK по пути sysroot-*-kos/include/kos.

API предназначены для синхронизации потоков исполнения, принадлежащих одному и тому же процессу.

События

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

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

Инициализация события вызовом функции KosEventInit().
Использование события потоками исполнения:
- Ожидание перехода события из несигнального состояния в сигнальное вызовом функции KosEventWait() или KosEventWaitTimeout() (на стороне уведомляемых потоков исполнения).
- Изменение состояния события вызовами функций KosEventSet() и KosEventReset() (на стороне уведомляющих потоков исполнения).

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

Функции event.h

Функция	Сведения о функции
`KosEventInit()`	Назначение Инициализирует событие. После инициализации событие находится в несигнальном состоянии. Параметры [out] `event` – указатель на событие. Тип события определен в заголовочном файле `sysroot-*-kos/include/kos/sync_types.h` из состава KasperskyOS SDK. Возвращаемые значения Нет.
`KosEventSet()`	Назначение Устанавливает событие в сигнальное состояние. Параметры [out] `event` – указатель на событие. Тип события определен в заголовочном файле `sysroot-*-kos/include/kos/sync_types.h` из состава KasperskyOS SDK. Возвращаемые значения Нет.
`KosEventReset()`	Назначение Устанавливает событие в несигнальное состояние. Параметры [out] `event` – указатель на событие. Тип события определен в заголовочном файле `sysroot-*-kos/include/kos/sync_types.h` из состава KasperskyOS SDK. Возвращаемые значения Нет.
`KosEventWait()`	Назначение Ожидает перехода события из несигнального состояния в сигнальное сколь угодно долго. Параметры [in,out] `event` – указатель на событие. Тип события определен в заголовочном файле `sysroot--kos/include/kos/sync_types.h` из состава KasperskyOS SDK. [in] `reset` – значение, которое задает, нужно ли установить событие в несигнальное состояние после завершения ожидания (`rtl_true` – да, `rtl_false` – нет). Тип параметра определен в заголовочном файле `sysroot--kos/include/rtl/stdbool.h` из состава KasperskyOS SDK. Возвращаемые значения Нет.
`KosEventWaitTimeout()`	Назначение Ожидает перехода события из несигнального состояния в сигнальное не дольше заданного времени. Параметры [in,out] `event` – указатель на событие. Тип события определен в заголовочном файле `sysroot--kos/include/kos/sync_types.h` из состава KasperskyOS SDK. [in] `reset` – значение, которое задает, нужно ли установить событие в несигнальное состояние после завершения ожидания (`rtl_true` – да, `rtl_false` – нет). Тип параметра определен в заголовочном файле `sysroot--kos/include/rtl/stdbool.h` из состава KasperskyOS SDK. [in] `mdelay` – время ожидания в миллисекундах или `INFINITE_TIMEOUT`, чтобы задать неограниченное время ожидания. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки. Если время ожидания истекло, возвращает `rcTimeout`.

Мьютексы

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

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

Инициализация мьютекса вызовом функции KosMutexInit() или KosMutexInitEx().
Использование мьютекса потоками исполнения:
1. Захват мьютекса вызовом функции KosMutexTryLock(), KosMutexLock() или KosMutexLockTimeout().
2. Освобождение мьютекса вызовом функции KosMutexUnlock().

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

Функции mutex.h

Функция	Сведения о функции
`KosMutexInit()`	Назначение Инициализирует мьютекс, который не является рекурсивным. Параметры [out] `mutex` – указатель на мьютекс. Тип мьютекса определен в заголовочном файле `sysroot-*-kos/include/kos/sync_types.h` из состава KasperskyOS SDK. Возвращаемые значения Нет.
`KosMutexInitEx()`	Назначение Инициализирует мьютекс. Параметры [out] `mutex` – указатель на мьютекс. Тип мьютекса определен в заголовочном файле `sysroot-*-kos/include/kos/sync_types.h` из состава KasperskyOS SDK. [in] `recursive` – значение, которое задает, должен ли мьютекс быть рекурсивным (`1` – да, `0` – нет). Возвращаемые значения Нет.
`KosMutexTryLock()`	Назначение Захватывает мьютекс. Если мьютекс уже захвачен, не ожидает его освобождения, а возвращает управление. Параметры [in,out] `mutex` – указатель на мьютекс. Тип мьютекса определен в заголовочном файле `sysroot-*-kos/include/kos/sync_types.h` из состава KasperskyOS SDK. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки. Если мьютекс уже захвачен, возвращает `rcBusy`.
`KosMutexLock()`	Назначение Захватывает мьютекс. Если мьютекс уже захвачен, ожидает его освобождения сколь угодно долго. Параметры [in,out] `mutex` – указатель на мьютекс. Тип мьютекса определен в заголовочном файле `sysroot-*-kos/include/kos/sync_types.h` из состава KasperskyOS SDK. Возвращаемые значения Нет.
`KosMutexUnlock()`	Назначение Освобождает мьютекс. Параметры [in,out] `mutex` – указатель на мьютекс. Тип мьютекса определен в заголовочном файле `sysroot-*-kos/include/kos/sync_types.h` из состава KasperskyOS SDK. Возвращаемые значения Нет.
`KosMutexLockTimeout()`	Назначение Захватывает мьютекс. Если мьютекс уже захвачен, ожидает его освобождения не дольше заданного времени. Параметры [in,out] `mutex` – указатель на мьютекс. Тип мьютекса определен в заголовочном файле `sysroot-*-kos/include/kos/sync_types.h` из состава KasperskyOS SDK. [in] `mdelay` – время ожидания в миллисекундах или `INFINITE_TIMEOUT`, чтобы задать неограниченное время ожидания. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки. Если время ожидания истекло, возвращает `rcTimeout`.

Блокировки чтения-записи

Блокировка чтения-записи – примитив синхронизации, который используется, чтобы разрешить доступ к разделяемым между потоками исполнения ресурсам либо на запись для одного потока исполнения, либо на чтение для нескольких потоков исполнения одновременно.

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

Инициализация блокировки чтения-записи вызовом функции KosRWLockInit().
Использование блокировки чтения-записи потоками исполнения:
1. Захват блокировки чтения-записи для записи (вызовом функции KosRWLockWrite() или KosRWLockTryWrite()) или для чтения (вызовом функции KosRWLockRead() или KosRWLockTryRead()).
2. Освобождение блокировки-чтения вызовом функции KosRWLockUnlock().

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

Функции rwlock.h

Функция	Сведения о функции
`KosRWLockInit()`	Назначение Инициализирует блокировку чтения-записи. Параметры [out] `rwlock` – указатель на блокировку чтения-записи. Тип блокировки чтения-записи определен в заголовочном файле `sysroot-*-kos/include/kos/sync_types.h` из состава KasperskyOS SDK. Возвращаемые значения Нет.
`KosRWLockRead()`	Назначение Захватывает блокировку чтения-записи для чтения. Если блокировка чтения-записи уже захвачена для записи, или есть потоки исполнения, ожидающие захвата этой блокировки чтения-записи для записи, то ожидает освобождения этой блокировки чтения-записи от захвата для записи сколь угодно долго. Параметры [in,out] `rwlock` – указатель на блокировку чтения-записи. Тип блокировки чтения-записи определен в заголовочном файле `sysroot-*-kos/include/kos/sync_types.h` из состава KasperskyOS SDK. Возвращаемые значения Нет.
`KosRWLockTryRead()`	Назначение Захватывает блокировку чтения-записи для чтения. Если блокировка чтения-записи уже захвачена для записи, или есть потоки исполнения, ожидающие захвата этой блокировки чтения-записи для записи, то не ожидает освобождения этой блокировки чтения-записи от захвата для записи, а возвращает управление. Параметры [in,out] `rwlock` – указатель на блокировку чтения-записи. Тип блокировки чтения-записи определен в заголовочном файле `sysroot-*-kos/include/kos/sync_types.h` из состава KasperskyOS SDK. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosRWLockWrite()`	Назначение Захватывает блокировку чтения-записи для записи. Если блокировка чтения-записи уже захвачена для записи или чтения, ожидает освобождения этой блокировки чтения-записи сколь угодно долго. Параметры [in,out] `rwlock` – указатель на блокировку чтения-записи. Тип блокировки чтения-записи определен в заголовочном файле `sysroot-*-kos/include/kos/sync_types.h` из состава KasperskyOS SDK. Возвращаемые значения Нет.
`KosRWLockTryWrite()`	Назначение Захватывает блокировку чтения-записи для записи. Если блокировка чтения-записи уже захвачена для записи или чтения, не ожидает освобождения этой блокировки чтения-записи, а возвращает управление. Параметры [in,out] `rwlock` – указатель на блокировку чтения-записи. Тип блокировки чтения-записи определен в заголовочном файле `sysroot-*-kos/include/kos/sync_types.h` из состава KasperskyOS SDK. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosRWLockUnlock()`	Назначение Освобождает блокировку чтения-записи. Параметры [in,out] `rwlock` – указатель на блокировку чтения-записи. Тип блокировки чтения-записи определен в заголовочном файле `sysroot-*-kos/include/kos/sync_types.h` из состава KasperskyOS SDK. Возвращаемые значения Нет. Дополнительные сведения Если блокировка чтения-записи захвачена для чтения, то эта блокировка чтения-записи остается захваченной для чтения, пока все потоки исполнения, выполняющие чтение, не освободят ее.

Семафоры

Семафор – примитив синхронизации, основанный на счетчике, значение которого может быть атомарно изменено. Значение счетчика обычно отражает число доступных разделяемых между потоками исполнения ресурсов. Для исполнения критической секции поток ожидает, пока значение счетчика не станет больше нуля. Если значение счетчика больше нуля, то оно уменьшается на единицу, и поток исполняет критическую секцию. После исполнения критической секции поток исполнения сигнализирует семафор, в результате чего значение счетчика увеличивается.

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

Инициализация семафора вызовом функции KosSemaphoreInit().
Использование семафора потоками исполнения:
1. Ожидание семафора вызовом функции KosSemaphoreWait(), KosSemaphoreWaitTimeout() или KosSemaphoreTryWait().
2. Сигнализация семафора вызовом функции KosSemaphoreSignal() или KosSemaphoreSignalN().
Освобождение ресурсов семафора вызовом функции KosSemaphoreDeinit().

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

Функции semaphore.h

Функция	Сведения о функции
`KosSemaphoreInit()`	Назначение Инициализирует семафор. Параметры [out] `semaphore` – указатель на семафор. Тип семафора определен в заголовочном файле `sysroot--kos/include/kos/sync_types.h` из состава KasperskyOS SDK. [in] `count` – значение счетчика. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки. Если значение в параметре `count` превышает константу `KOS_SEMAPHORE_VALUE_MAX`, возвращает `rcInvalidArgument`. (Константа `KOS_SEMAPHORE_VALUE_MAX` определена в заголовочном файле `sysroot--kos/include/kos/sync_types.h` из состава KasperskyOS SDK.)
`KosSemaphoreDeinit()`	Назначение Освобождает ресурсы семафора. Параметры [in] `semaphore` – указатель на семафор. Тип семафора определен в заголовочном файле `sysroot-*-kos/include/kos/sync_types.h` из состава KasperskyOS SDK. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки. Если есть потоки исполнения, ожидающие семафор, возвращает `rcBusy`.
`KosSemaphoreSignal()`	Назначение Сигнализирует семафор с увеличением счетчика на единицу. Параметры [in,out] `semaphore` – указатель на семафор. Тип семафора определен в заголовочном файле `sysroot-*-kos/include/kos/sync_types.h` из состава KasperskyOS SDK. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosSemaphoreSignalN()`	Назначение Сигнализирует семафор с увеличением счетчика на заданное число. Параметры [in,out] `semaphore` – указатель на семафор. Тип семафора определен в заголовочном файле `sysroot-*-kos/include/kos/sync_types.h` из состава KasperskyOS SDK. [in] `n` – натуральное число, на которое нужно увеличить счетчик. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosSemaphoreWaitTimeout()`	Назначение Ожидает семафор не дольше заданного времени. Параметры [in,out] `semaphore` – указатель на семафор. Тип семафора определен в заголовочном файле `sysroot-*-kos/include/kos/sync_types.h` из состава KasperskyOS SDK. [in] `mdelay` – время ожидания семафора в миллисекундах или `INFINITE_TIMEOUT`, чтобы задать неограниченное время ожидания. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки. Если время ожидания истекло, возвращает `rcTimeout`.
`KosSemaphoreWait()`	Назначение Ожидает семафор сколь угодно долго. Параметры [in,out] `semaphore` – указатель на семафор. Тип семафора определен в заголовочном файле `sysroot-*-kos/include/kos/sync_types.h` из состава KasperskyOS SDK. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosSemaphoreTryWait()`	Назначение Ожидает семафор. Если счетчик семафора имеет нулевое значение, не ожидает увеличения счетчика этого семафора, а возвращает управление. Параметры [in,out] `semaphore` – указатель на семафор. Тип семафора определен в заголовочном файле `sysroot-*-kos/include/kos/sync_types.h` из состава KasperskyOS SDK. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки. Если счетчик семафора имеет нулевое значение, возвращает `rcBusy`.

Условные переменные

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

Типовой сценарий использования 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`, чтобы задать неограниченное время ожидания. Возвращаемые значения В случае успеха возвращает `rcOk`. Если время ожидания истекло, возвращает `rcTimeout`.
`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. Возвращаемые значения Нет.

В начало