Using futexes (sync.h)

This API is defined in the header file sysroot-*-kos/include/coresrv/sync/sync.h from the KasperskyOS SDK.

The API is intended to perform futex-based thread synchronization and is used in the code of the API functions event.h, mutex.h, rwlock.h, semaphore.h, and condvar.h. A futex is a low-level synchronization primitive that supports two operations: lock a thread and add it to the futex-linked queue of locked threads, and resume execution of threads from the futex-linked queue of locked threads. A futex is a kernel object linked to an integer variable in the user space. The kernel object provides the capability to store a queue of locked threads linked to the futex. The value of the integer variable in the user space (futex value) is atomically modified by the synchronized threads to signal the changed state of shared resources. For example, the futex value may indicate the specific state of an event (signaling or non-signaling state), indicate whether the mutex has been captured or freed, and indicate the specific value of the semaphore counter.

Two types of futexes are supported:

• Futex linked to a queue of locked threads arranged in the order of their priority.

  Locked threads form a queue consisting 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)).

  The futex value must adhere to a special format.

• Futex linked to a queue of locked threads arranged according to the FIFO principle.

  Locked threads form a FIFO-ordered queue, regardless of scheduler classes and priorities.

  The futex value can be an arbitrary non-negative integer.

Information about API functions is provided in the table below.

Using the API

To use a futex linked to a queue of locked FIFO-ordered threads, you only need to create an integer variable to store its value. The KnFutexWait() and KnFutexWake() functions receive the pointer to this variable via the ftx parameter. The kernel object linked to this variable is created or deleted automatically when using these functions.

The KnFutexWait() function locks the calling thread if the futex value matches the value of the val parameter. (A futex value can be changed by another thread during execution of a function.) The thread is locked for the mdelay time period, but execution of this thread may be resumed before the mdelay period elapses by calling the KnFutexWake() function from another thread. The KnFutexWake() function resumes execution of threads from a futex-linked queue of locked threads. The number of threads whose execution is resumed is limited by the value of the nThreads parameter. Thread execution is resumed starting with the beginning of the queue.

When using a futex linked to a queue of locked threads ordered by priority, the KnFutexPiWait() and KnFutexPiWake() functions are used to lock and resume execution of threads, respectively. These functions are intended for use by the libkos library. The libkos library uses them to implement functions for synchronizing threads based on mutexes that support priority inheritance (KosRtMutex*() functions from the mutex.h API).

Information about API functions

sync.h functions

Function	Information about the function
KnFutexWait()	Purpose Blocks the calling thread if the futex value is equal to the expected value. Parameters [in] ftx – pointer to the variable containing the futex value. [in] val – expected value of the futex. [in] mdelay – maximum blocking duration (in milliseconds), or INFINITE_TIMEOUT to set an unlimited blocking duration. The constant INFINITE_TIMEOUT is defined in the header file sysroot-*-kos/include/rtl/rtc.h from the KasperskyOS SDK. [out,optional] outDelay – actual blocking duration (in milliseconds), or RTL_NULL if this information is not required. Returned values If successful, the function returns rcOk, otherwise it returns an error code. If the thread blocking duration has expired, the function returns rcTimeout. If the futex value is not equal to the expected value, the function returns rcFutexWouldBlock. Additional information Non-blocking call if the mdelay parameter is set to 0.
KnFutexWake()	Purpose Resumes execution of the threads that are the first in the queue of threads that were locked by calls of the KnFutexWait() function with the specified futex. Parameters [in] ftx – pointer to the variable containing the futex value. [in] nThreads – maximum number of threads whose execution will be resumed. [out,optional] wokenCnt – actual number of threads whose execution has been resumed, or RTL_NULL if this information is not required. Returned values If successful, the function returns rcOk, otherwise it returns an error code.
KnFutexPiWait()	Purpose Locks the calling thread. Parameters [in] ftx – pointer to the variable containing the futex value. The variable type is defined in the header file sysroot-*-kos/include/rtl/atomic.h from the KasperskyOS SDK. [in] mdelay – maximum blocking duration (in milliseconds), or INFINITE_TIMEOUT to set an unlimited blocking duration. 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. Additional information Non-blocking call if the mdelay parameter is set to 0.
KnFutexPiWake()	Purpose Resumes execution of the thread that is the first in the queue of threads that were locked by calls of the KnFutexPiWait() function with the specified futex. Parameters [in] ftx – pointer to the variable containing the futex value. The variable type is defined in the header file sysroot-*-kos/include/rtl/atomic.h from the KasperskyOS SDK. Returned values If successful, the function returns rcOk, otherwise it returns an error code.

Page top