The API is defined in the header file sysroot-*-kos/include/kos/mutex.h from the KasperskyOS SDK. The KasperskyOS SDK also provides the header file sysroot-*-kos/include/kos/sync_api.h, which lets you transitively include the header file mutex.h and the header files for using other synchronization primitives into the application source code.
The API facilitates using mutexes to synchronize threads.A mutex is a synchronization primitive that ensures mutually exclusive execution of critical sections (areas of code where resources shared between threads are queried). One thread captures the mutex and executes a critical section. Meanwhile, other threads wait for the mutex to be freed and attempt to capture this mutex to execute other critical sections. A mutex can be freed only by the specific thread that captured it. A recursive mutex can be captured by a single thread multiple times.
You can use mutexes without priority inheritance support and optionally (depending on the configuration of the KasperskyOS kernel) with priority inheritance support.
Mutexes with priority inheritance support have the following features:
Threads that are locked while waiting for the release of the mutex form a queue that consists of two parts. The initial part of the queue consists of real-time threads (scheduler classes FIFO and RR) arranged in the order of their priority. The final part of the queue consists of standard threads arranged according to the FIFO principle. The higher the priority of a real-time thread, the closer this thread is to the start of the queue. In this case, real-time threads with the same priority are ordered according to the FIFO principle. (For scheduler classes and thread priorities, see Managing threads (low-level API thread_api.h)).
Capturing a mutex can change the scheduler class and priority of a thread. The change is in effect until the mutex is released, after which the scheduler class and priority are restored to their previous values. The purpose of these changes is to prevent high-priority threads from being locked for prolonged periods while waiting for the release of mutexes captured by low-priority threads.
If the first in the queue is a real-time thread with a higher priority than that of the real-time thread that captured the mutex, the scheduler class of the thread that captured the mutex is changed to FIFO (if it was RR) while the priority of the thread is raised to the priority of the first thread in the queue.
If the first thread in the queue is a real-time thread, the scheduler class of the standard thread that has captured the mutex is changed to FIFO while the priority of the thread becomes equal to the priority of the first thread in the queue.
If the standard thread is the first in the queue, the scheduler class and priority of the thread that captured the mutex are not changed.
If a real-time thread whose scheduler class and/or priority has changed as a result of the capture of mutex 1 is locked while awaiting the release of mutex 2, and mutex 2 is captured by a real-time thread with a lower priority than the temporary priority of the thread that captured mutex 1, the scheduler class of the thread that captured mutex 2 is changed to FIFO (if it was RR) while the priority of the thread is raised to the temporary priority of the thread that captured mutex 1.
If a real-time thread whose scheduler class and/or priority has changed as a result of the capture of mutex 1 is locked while awaiting the release of mutex 2, and mutex 2 is captured by a standard thread, the scheduler class of the thread that captured mutex 2 is changed to FIFO while the priority of the thread becomes equal to the temporary priority of the thread that captured mutex 1.
Mutexes cannot be recursive.
Mutexes without priority inheritance support have the following special features:
Threads that are locked while waiting for the release of the mutex form a FIFO-ordered queue, regardless of scheduler classes and priorities.
The scheduler class and priority of a thread cannot be changed as a result of mutex capture.
Mutexes can be recursive.
Information about API functions is provided in the table below.
Using the API
A typical scenario for using the API for mutexes without priority inheritance support includes the following steps:
A mutex is initialized via the KosMutexInit() or KosMutexInitEx() function call.
The mutex is used by threads:
The mutex is captured via the KosMutexTryLock(), KosMutexLock() or KosMutexLockTimeout() function call.
The mutex is freed via the KosMutexUnlock() function call.
Checking the state of the mutex (whether it is acquired or not) by calling the KosMutexIsLocked() function.
This check is performed atomically and without acquiring the mutex. The state of the mutex may change immediately after the KosMutexIsLocked() function returns control. Therefore, this function can only be used to ensure that the mutex is in the expected state after being acquired (for example, in recursive captures).
A typical scenario for using the API for mutexes with priority inheritance support includes the following steps:
Initialize the mutex by calling the KosRtMutexInit() function.
Before performing this step, you must verify that the kernel version in use provides the capability to use mutexes with priority inheritance support. To do so, call the KosRtMutexIsSupported() function.
The mutex is used by threads:
Capture the mutex by calling the KosRtMutexLock() or KosRtMutexLockTimeout() function.
The mutex is freed via the KosRtMutexUnlock() function call.
Information about API functions
mutex.h functions
Function
Information about the function
KosMutexInit()
Purpose
Initializes a mutex that has no priority inheritance support and is not recursive.
Parameters
[out] mutex – pointer to the mutex. The mutex type is defined in the sysroot-*-kos/include/kos/sync_types.h header file from the KasperskyOS SDK.
Returned values
N/A
KosMutexInitEx()
Purpose
Initializes a mutex without priority inheritance support.
Parameters
[out] mutex – pointer to the mutex. The mutex type is defined in the sysroot-*-kos/include/kos/sync_types.h header file from the KasperskyOS SDK.
[in] recursive – value that defines whether the mutex should be recursive (1 – yes, 0 – no).
Returned values
N/A
KosMutexTryLock()
Purpose
Captures a mutex without priority inheritance support.
If the mutex is already acquired, returns control rather than waits for the mutex to be released.
Parameters
[in,out] mutex – pointer to the mutex. The mutex type is defined in the sysroot-*-kos/include/kos/sync_types.h header file from the KasperskyOS SDK.
Returned values
If successful, the function returns rcOk, otherwise it returns an error code.
If the mutex is already acquired, returns rcBusy.
KosMutexLock()
Purpose
Captures a mutex without priority inheritance support.
If the mutex is already acquired, waits indefinitely for it to be released.
Parameters
[in,out] mutex – pointer to the mutex. The mutex type is defined in the sysroot-*-kos/include/kos/sync_types.h header file from the KasperskyOS SDK.
Returned values
N/A
KosMutexUnlock()
Purpose
Frees a mutex that has no priority inheritance support.
Parameters
[in,out] mutex – pointer to the mutex. The mutex type is defined in the sysroot-*-kos/include/kos/sync_types.h header file from the KasperskyOS SDK.
Returned values
N/A
KosMutexLockTimeout()
Purpose
Captures a mutex without priority inheritance support.
If the mutex is already acquired, waits for it to be released for a period that does not exceed the specified time.
Parameters
[in,out] mutex – pointer to the mutex. The mutex type is defined in the sysroot-*-kos/include/kos/sync_types.h header file from the KasperskyOS SDK.
[in] mdelay – timeout (in milliseconds) or INFINITE_TIMEOUT to set an unlimited timeout. The constant INFINITE_TIMEOUT is defined in the header file sysroot-*-kos/include/rtl/rtc.h from the KasperskyOS SDK.
Returned values
If successful, the function returns rcOk, otherwise it returns an error code.
Returns rcTimeout if the timeout has elapsed.
Additional information
Non-blocking call if the mdelay parameter is set to 0.
KosMutexIsLocked()
Purpose
Checks whether a mutex without priority inheritance support has been captured.
Parameters
[in] mutex – pointer to the mutex. The mutex type is defined in the sysroot-*-kos/include/kos/sync_types.h header file from the KasperskyOS SDK.
Returned values
If the mutex has been acquired, the function returns rtl_true. Otherwise it returns rtl_false. The type of returned value is defined in the header file sysroot-*-kos/include/rtl/stdbool.h from the KasperskyOS SDK.
KosRtMutexIsSupported()
Purpose
Checks whether the version of the kernel in use provides the capability to use mutexes with priority inheritance support.
Parameters
N/A
Returned values
If the verification is successful, the function returns rtl_true, otherwise it returns rtl_false. The type of returned value is defined in the header file sysroot-*-kos/include/rtl/stdbool.h from the KasperskyOS SDK.
KosRtMutexInit()
Purpose
Initializes a mutex with priority inheritance support.
Parameters
[out] mutex – pointer to the mutex. The mutex type is defined in the sysroot-*-kos/include/kos/sync_types.h header file from the KasperskyOS SDK.
Returned values
N/A
KosRtMutexLock()
Purpose
Captures a mutex with priority inheritance support.
If the mutex is already acquired, waits indefinitely for it to be released.
Parameters
[in,out] mutex – pointer to the mutex. The mutex type is defined in the sysroot-*-kos/include/kos/sync_types.h header file from the KasperskyOS SDK.
Returned values
N/A
KosRtMutexUnlock()
Purpose
Frees a mutex with priority inheritance support.
Parameters
[in,out] mutex – pointer to the mutex. The mutex type is defined in the sysroot-*-kos/include/kos/sync_types.h header file from the KasperskyOS SDK.
Returned values
N/A
KosRtMutexLockTimeout()
Purpose
Captures a mutex with priority inheritance support.
If the mutex is already acquired, waits for it to be released for a period that does not exceed the specified time.
Parameters
[in,out] mutex – pointer to the mutex. The mutex type is defined in the sysroot-*-kos/include/kos/sync_types.h header file from the KasperskyOS SDK.
[in] mdelay – timeout (in milliseconds) or INFINITE_TIMEOUT to set an unlimited timeout. The constant INFINITE_TIMEOUT is defined in the header file sysroot-*-kos/include/rtl/rtc.h from the KasperskyOS SDK.
Returned values
If successful, the function returns rcOk, otherwise it returns an error code.
Returns rcTimeout if the timeout has elapsed.
Additional information
Non-blocking call if the mdelay parameter is set to 0.