Using condition variables (condvar.h)

The API is defined in the header file sysroot-*-kos/include/kos/condvar.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 condvar.h and the header files for using other synchronization primitives into the application source code.

The API facilitates using condition variables to synchronize threads. A condition variable is a synchronization primitive that is used to notify one or more threads about the fulfillment of a condition required by these threads. A condition variable is used in conjunction with a mutex (which has no priority inheritance support). The notifying and notified threads capture a mutex to execute critical sections. During execution of a critical section, the notified thread verifies that its required condition was fulfilled (for example, the data has been prepared by the notifying thread). If the condition is fulfilled, the notified thread executes the critical section and frees the mutex. If the condition is not fulfilled, the notified thread is locked at the condition variable and waits for the condition to be fulfilled. When this happens, the mutex is automatically freed. During execution of a critical section, the notifying thread verifies fulfillment of the condition required by the notified thread. If the condition is fulfilled, the notifying thread signals this fulfillment through the condition variable and frees the mutex. The notified thread that was locked and waiting for the fulfillment of its required condition resumes execution of the critical section while automatically capturing the mutex. After the critical section is executed, the notified thread frees the mutex.

Information about API functions is provided in the table below.

Using the API

The standard scenario for API usage includes the following steps:

1. The condition variable and mutex are initialized.

   To initialize a condition variable, you need to call the KosCondvarInit() function.

2. The condition variable and mutex are used by threads.

Use of a condition variable and mutex by notified threads includes the following steps:

1. The mutex is captured.
2. Condition fulfillment is verified.
3. The KosCondvarWait() or KosCondvarWaitTimeout() function is called to wait for condition fulfillment.

   After the KosCondvarWait() or KosCondvarWaitTimeout() function is returned, you normally need to re-verify that the condition is fulfilled because another notified thread also received the signal and may have voided this condition again. (For example, another thread could have extracted the data prepared by the notifying thread). To do so, you need to use the following construct:

   while(<condition>)

   <call of KosCondvarWait() or KosCondvarWaitTimeout()>

4. The mutex is freed.

Use of a condition variable and mutex by notifying threads includes the following steps:

1. The mutex is captured.
2. Condition fulfillment is verified.
3. Fulfillment of the condition is signaled via the KosCondvarSignal() or KosCondvarBroadcast() function call.
4. The mutex is freed.

Information about API functions

condvar.h functions

Function	Information about the function
KosCondvarInit()	Purpose Initializes a condition variable. Parameters [out] condvar – pointer to the condition variable. The condition variable type is defined in the sysroot-*-kos/include/kos/sync_types.h header file from the KasperskyOS SDK. Returned values N/A
KosCondvarWaitTimeout()	Purpose Waits for condition fulfillment for a period that does not exceed the specified time. Parameters [in] condvar – pointer to the condition variable. The conditional variable type is defined in the sysroot-*-kos/include/kos/sync_types.h header file from the KasperskyOS SDK. [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 – condition fulfillment 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 Returns rcOk if successful. Returns rcTimeout if the timeout has elapsed. Additional information Non-blocking call if the mdelay parameter is set to 0.
KosCondvarWait()	Purpose Waits indefinitely for condition fulfillment. Parameters [in] condvar – pointer to the condition variable. The conditional variable type is defined in the sysroot-*-kos/include/kos/sync_types.h header file from the KasperskyOS SDK. [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.
KosCondvarSignal()	Purpose Signals condition fulfillment to one of the threads waiting for it. Parameters [in, out] condvar – pointer to the condition variable. The condition variable type is defined in the sysroot-*-kos/include/kos/sync_types.h header file from the KasperskyOS SDK. Returned values N/A
KosCondvarBroadcast()	Purpose Signals condition fulfillment to all threads waiting for it. Parameters [in, out] condvar – pointer to the condition variable. The condition variable type is defined in the sysroot-*-kos/include/kos/sync_types.h header file from the KasperskyOS SDK. Returned values N/A

Page top