Using semaphores (semaphore.h)

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

The API facilitates using semaphores to synchronize threads. A semaphore is a synchronization primitive that is based on a counter whose value can be atomically modified. The value of the counter normally reflects the number of available resources shared between threads. To execute a critical section, the thread waits until the counter value becomes greater than zero. If the counter value is greater than zero, it is decremented by one and the thread executes the critical section. After the critical section is executed, the thread signals the semaphore and the counter value is increased.

Information about API functions is provided in the table below.

Using the API

The standard scenario for API usage includes the following steps:

A semaphore is initialized via the KosSemaphoreInit() function call.
The semaphore is used by threads:
1. They wait for the semaphore via the KosSemaphoreWait(), KosSemaphoreWaitTimeout() or KosSemaphoreTryWait() function call.
2. The semaphore is signaled via the KosSemaphoreSignal() or KosSemaphoreSignalN() function call.
Deallocating semaphore resources by calling the KosSemaphoreDeinit() function.

Information about API functions

semaphore.h functions

Function	Information about the function
`KosSemaphoreInit()`	Purpose Initializes a semaphore. Parameters [out] `semaphore` – pointer to the semaphore. The semaphore type is defined in the `sysroot--kos/include/kos/sync_types.h` header file from the KasperskyOS SDK. [in] `count` – counter value. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. If the value of the `count` parameter exceeds the `KOS_SEMAPHORE_VALUE_MAX` constant, returns `rcInvalidArgument`. (The `KOS_SEMAPHORE_VALUE_MAX` constant is defined in the `sysroot--kos/include/kos/sync_types.h` header file from the KasperskyOS SDK.)
`KosSemaphoreDeinit()`	Purpose Deallocates semaphore resources. Parameters [in] `semaphore` – pointer to the semaphore. The semaphore 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 there are threads waiting on the semaphore, returns `rcBusy`.
`KosSemaphoreSignal()`	Purpose Signals the semaphore and increases the counter by one. Parameters [in, out] `semaphore` – pointer to the semaphore. The semaphore 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.
`KosSemaphoreSignalN()`	Purpose Signals the semaphore and increases the counter by the specified number. Parameters [in, out] `semaphore` – pointer to the semaphore. The semaphore type is defined in the `sysroot-*-kos/include/kos/sync_types.h` header file from the KasperskyOS SDK. [in] `n` – natural number by which to increase the counter. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KosSemaphoreWaitTimeout()`	Purpose Waits on the semaphore for a period that does not exceed the specified time. Parameters [in, out] `semaphore` – pointer to the semaphore. The semaphore type is defined in the `sysroot--kos/include/kos/sync_types.h` header file from the KasperskyOS SDK. [in] `mdelay` – semaphore 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`.
`KosSemaphoreWait()`	Purpose Waits on the semaphore indefinitely. Parameters [in, out] `semaphore` – pointer to the semaphore. The semaphore 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.
`KosSemaphoreTryWait()`	Purpose Waits on the semaphore. If the semaphore counter is zero, returns control, rather than waits for the semaphore counter to increase. Parameters [in, out] `semaphore` – pointer to the semaphore. The semaphore 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 semaphore counter has a zero value, returns `rcBusy`.

Page top