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

API определен в заголовочном файле sysroot-*-kos/include/coresrv/sync/sync.h из состава KasperskyOS SDK.

API предназначен для синхронизации потоков исполнения на основе фьютексов и используется в коде функций API event.h, mutex.h, rwlock.h, semaphore.h, condvar.h. Фьютекс – низкоуровневый примитив синхронизации, для которого поддерживается две операции: блокировка потока исполнения с его добавлением в связанную с фьютексом очередь заблокированных потоков исполнения и возобновление исполнения потоков из связанной с фьютексом очереди заблокированных потоков исполнения. Фьютекс представляет собой объект ядра связанный с целочисленной переменной в пользовательском пространстве. Объект ядра обеспечивает возможность хранить очередь заблокированных потоков исполнения, связанную с фьютексом. Значение целочисленной переменной в пользовательском пространстве (значение фьютекса) атомарно изменяется синхронизируемыми потоками исполнения, чтобы сигнализировать об изменении состояния разделяемых ресурсов. Например, значение фьютекса может отражать, в каком состоянии находится событие (сигнальном или несигнальном), захвачен или освобожден мьютекс, какое значение имеет счетчик семафора.

Поддерживаются фьютексы двух типов:

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

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

  Значение фьютекса должно соответствовать специальному формату.

• Фьютекс, связанный с очередью заблокированных потоков исполнения, упорядоченных по принципу FIFO.

  Заблокированные потоки исполнения образуют очередь, упорядоченную по принципу FIFO, независимо от классов планирования и приоритетов.

  Значение фьютекса может быть произвольным целым неотрицательным числом.

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

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

Чтобы использовать фьютекс, связанный с очередью заблокированных потоков исполнения, упорядоченных по принципу FIFO, нужно создать только целочисленную переменную для хранения его значения. Функции KnFutexWait() и KnFutexWake() принимают указатель на эту переменную через параметр ftx. Создание и удаление объекта ядра, связанного с этой переменной, выполняется автоматически при использовании этих функций.

Функция KnFutexWait() блокирует вызывающий поток исполнения, если значение фьютекса совпадает со значением параметра val. (Значение фьютекса может быть изменено другим потоком исполнения во время выполнения функции.) Поток исполнения блокируется на время mdelay, но исполнение этого потока может быть возобновлено до истечения времени mdelay вызовом функции KnFutexWake() из другого потока исполнения. Функция KnFutexWake() возобновляет исполнение потоков из связанной с фьютексом очереди заблокированных потоков исполнения. Число потоков, исполнение которых возобновляется, ограничено значением параметра nThreads. Возобновление исполнения потоков начинается с начала очереди.

При использовании фьютекса, связанного с очередью заблокированных потоков исполнения, упорядоченных по приоритету, блокирование и возобновление исполнения потоков осуществляют функции KnFutexPiWait() и KnFutexPiWake() соответственно. Эти функции предназначены для использования библиотекой libkos. Используя их, библиотека libkos реализует функции для синхронизации потоков исполнения на основе мьютексов с поддержкой наследования приоритета (функции KosRtMutex*() из API mutex.h).

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

Функции sync.h

Функция	Сведения о функции
KnFutexWait()	Назначение Блокирует вызывающий поток исполнения, если значение фьютекса равно ожидаемому. Параметры [in] ftx – указатель на переменную со значением фьютекса. [in] val – ожидаемое значение фьютекса. [in] mdelay – максимальное время блокировки (в миллисекундах) или INFINITE_TIMEOUT, чтобы задать неограниченное время блокировки. Константа INFINITE_TIMEOUT определена в заголовочном файле sysroot-*-kos/include/rtl/rtc.h из состава KasperskyOS SDK. [out,optional] outDelay – фактическое время блокировки (в миллисекундах) или RTL_NULL, если эти сведения не требуются. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки. Если время блокировки потока исполнения истекло, возвращает rcTimeout. Если значение фьютекса не равно ожидаемому, возвращает rcFutexWouldBlock. Дополнительные сведения Неблокирующий вызов, если в параметре mdelay указан 0.
KnFutexWake()	Назначение Возобновляет исполнение потоков, которые является первыми в очереди потоков исполнения, заблокированных вызовами функции KnFutexWait() с заданным фьютексом. Параметры [in] ftx – указатель на переменную со значением фьютекса. [in] nThreads – максимальное число потоков, исполнение которых будет возобновлено. [out,optional] wokenCnt – фактическое число потоков, исполнение которых возобновлено, или RTL_NULL, если эти сведения не требуются. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KnFutexPiWait()	Назначение Блокирует вызывающий поток исполнения. Параметры [in] ftx – указатель на переменную со значением фьютекса. Тип переменной определен в заголовочном файле sysroot-*-kos/include/rtl/atomic.h из состава KasperskyOS SDK. [in] mdelay – максимальное время блокировки (в миллисекундах) или INFINITE_TIMEOUT, чтобы задать неограниченное время блокировки. Константа INFINITE_TIMEOUT определена в заголовочном файле sysroot-*-kos/include/rtl/rtc.h из состава KasperskyOS SDK. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки. Дополнительные сведения Неблокирующий вызов, если в параметре mdelay указан 0.
KnFutexPiWake()	Назначение Возобновляет исполнение потока, который является первым в очереди потоков исполнения, заблокированных вызовами функции KnFutexPiWait() с заданным фьютексом. Параметры [in] ftx – указатель на переменную со значением фьютекса. Тип переменной определен в заголовочном файле sysroot-*-kos/include/rtl/atomic.h из состава KasperskyOS SDK. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.

В начало