KasperskyOS Community Edition 1.3

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 for working with futexes and is used in code of the API functions in 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. The futex value determines whether to lock a thread that attempts to obtain access to shared resources.

Information about API functions is provided in the table below.

Using the API

To use a futex, you must create only an integer variable for storing its value. The API 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 the API 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.

Information about API functions

sync.h functions

Function

Information about the function

KnFutexWait()

Purpose

Locks 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 lockout duration in milliseconds, or INFINITE_TIMEOUT to set an unlimited lockout duration.
  • [out,optional] outDelay – actual lockout 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 lockout duration has expired, the function returns rcTimeout.

If the futex value is not equal to the expected value, the function returns rcFutexWouldBlock.

KnFutexWake()

Purpose

Resumes execution of threads that were blocked by KnFutexWait() function calls with the defined futex.

Parameters

  • [in] ftx – pointer to the variable containing the futex value.
  • [in] nThreads – maximum number of threads whose execution can 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.