Использование мьютексов (mutex.h)

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

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

Можно использовать мьютексы без поддержки наследования приоритета и опционально (в зависимости от конфигурации ядра KasperskyOS) с поддержкой наследования приоритета.

Мьютексы с поддержкой наследования приоритета имеют следующие особенности:

• Потоки исполнения, которые заблокированы в ожидании освобождения мьютекса, образуют очередь, состоящую из двух частей. Начальная часть очереди состоит из потоков исполнения реального времени (классов планирования FIFO и RR), упорядоченных по приоритету. Конечная часть очереди состоит из стандартных потоков исполнения, упорядоченных по принципу FIFO. Чем выше приоритет потока исполнения реального времени, тем ближе этот поток к началу очереди. При этом потоки исполнения реального времени с одинаковым приоритетом упорядочиваются по принципу FIFO. (О классах планирования и приоритетах потоков исполнения см. "Управление потоками исполнения (низкоуровневый API thread_api.h)".)
• В результате захвата мьютекса у потока исполнения может измениться класс планирования и приоритет. Изменение действует до освобождения мьютекса, после чего класс планирования и приоритет принимают прежние значения. Цель таких изменений заключается в том, чтобы высокоприоритетные потоки исполнения не блокировались на длительное время в ожидании освобождения мьютексов, захваченных низкоприоритетными потоками исполнения.
  • Если первым в очереди является поток исполнения реального времени с приоритетом выше, чем у потока исполнения реального времени, захватившего мьютекс, то у потока исполнения, захватившего мьютекс, класс планирования изменяется на FIFO (если был RR), а приоритет повышается до приоритета первого в очереди потока исполнения.
  • Если первым в очереди является поток исполнения реального времени, то у стандартного потока исполнения, захватившего мьютекс, класс планирования изменяется на FIFO, а приоритет становится равным приоритету первого в очереди потока исполнения.
  • Если первым в очереди является стандартный поток исполнения, то у потока исполнения, захватившего мьютекс, класс планирования и приоритет не изменяются.
  • Если поток исполнения реального времени, у которого в результате захвата мьютекса 1 изменился класс планирования и/или приоритет, заблокирован в ожидании освобождения мьютекса 2, а мьютекс 2 захвачен потоком исполнения реального времени с меньшим приоритетом, чем временный приоритет потока исполнения, захватившего мьютекс 1, то у потока исполнения, захватившего мьютекс 2, класс планирования изменяется на FIFO (если был RR), а приоритет повышается до временного приоритета потока исполнения, захватившего мьютекс 1.
  • Если поток исполнения реального времени, у которого в результате захвата мьютекса 1 изменился класс планирования и/или приоритет, заблокирован в ожидании освобождения мьютекса 2, а мьютекс 2 захвачен стандартным потоком исполнения, то у потока исполнения, захватившего мьютекс 2, класс планирования изменяется на FIFO, а приоритет становится равным временному приоритету потока исполнения, захватившего мьютекс 1.
• Мьютексы не могут быть рекурсивными.

Мьютексы без поддержки наследования приоритета имеют следующие особенности:

• Потоки исполнения, которые заблокированы в ожидании освобождения мьютекса, образуют очередь, упорядоченную по принципу FIFO, независимо от классов планирования и приоритетов.
• В результате захвата мьютекса у потока исполнения не может измениться класс планирования и приоритет.
• Мьютексы могут быть рекурсивными.

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

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

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

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

      Эта проверка выполняется атомарно и без захвата мьютекса. Сразу после того, как функция KosMutexIsLocked() вернула управление, состояние мьютекса может измениться. Поэтому эту функцию можно использовать только для того, чтобы убедиться, что мьютекс находится в ожидаемом состоянии после захвата (например, при рекурсивных захватах).

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

1. Инициализация мьютекса вызовом функции KosRtMutexInit().

   Перед выполнением этого шага нужно проверить, обеспечивает ли применяемая версия ядра возможность использовать мьютексы с поддержкой наследования приоритета. Для этого нужно вызвать функцию KosRtMutexIsSupported().

2. Использование мьютекса потоками исполнения:
   1. Захват мьютекса вызовом функции KosRtMutexLock() или KosRtMutexLockTimeout().
   2. Освобождение мьютекса вызовом функции KosRtMutexUnlock().

Сведения о функциях 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, чтобы задать неограниченное время ожидания. Константа INFINITE_TIMEOUT определена в заголовочном файле sysroot-*-kos/include/rtl/rtc.h из состава KasperskyOS SDK. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки. Если время ожидания истекло, возвращает rcTimeout. Дополнительные сведения Неблокирующий вызов, если в параметре mdelay указан 0.
KosMutexIsLocked()	Назначение Проверяет, захвачен ли мьютекс без поддержки наследования приоритета. Параметры [in] mutex – указатель на мьютекс. Тип мьютекса определен в заголовочном файле sysroot-*-kos/include/kos/sync_types.h из состава KasperskyOS SDK. Возвращаемые значения Если мьютекс захвачен, возвращает rtl_true, иначе возвращает rtl_false. Тип возвращаемого значения определен в заголовочном файле sysroot-*-kos/include/rtl/stdbool.h из состава KasperskyOS SDK.
KosRtMutexIsSupported()	Назначение Проверяет, обеспечивает ли применяемая версия ядра возможность использовать мьютексы с поддержкой наследования приоритета. Параметры Нет. Возвращаемые значения В случае успешной проверки возвращает rtl_true, иначе возвращает rtl_false. Тип возвращаемого значения определен в заголовочном файле sysroot-*-kos/include/rtl/stdbool.h из состава KasperskyOS SDK.
KosRtMutexInit()	Назначение Инициализирует мьютекс с поддержкой наследования приоритета. Параметры [out] mutex – указатель на мьютекс. Тип мьютекса определен в заголовочном файле sysroot-*-kos/include/kos/sync_types.h из состава KasperskyOS SDK. Возвращаемые значения Нет.
KosRtMutexLock()	Назначение Захватывает мьютекс с поддержкой наследования приоритета. Если мьютекс уже захвачен, ожидает его освобождения сколь угодно долго. Параметры [in,out] mutex – указатель на мьютекс. Тип мьютекса определен в заголовочном файле sysroot-*-kos/include/kos/sync_types.h из состава KasperskyOS SDK. Возвращаемые значения Нет.
KosRtMutexUnlock()	Назначение Освобождает мьютекс с поддержкой наследования приоритета. Параметры [in,out] mutex – указатель на мьютекс. Тип мьютекса определен в заголовочном файле sysroot-*-kos/include/kos/sync_types.h из состава KasperskyOS SDK. Возвращаемые значения Нет.
KosRtMutexLockTimeout()	Назначение Захватывает мьютекс с поддержкой наследования приоритета. Если мьютекс уже захвачен, ожидает его освобождения не дольше заданного времени. Параметры [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.

В начало