Managing threads (high-level API thread.h)

The API is defined in the header file sysroot-*-kos/include/kos/thread.h from the KasperskyOS SDK.

Main capabilities of the API:

Create, terminate, and lock threads.
Resume execution of locked threads.
Get information about threads.

Information about API functions is provided in the table below.

The libkos library also provides a low-level API for thread management. The low-level API should be used only if the high-level API does not have sufficient capabilities.

Creating a thread

To create a thread, call the KosThreadCreate() or KosThreadCreateDetached() function. These functions create a standard thread with priority ranging from 0–15. (For details about standard threads, see Managing threads (low-level API thread_api.h)).

Terminating a thread

When a thread is terminated, it is permanently deleted from the scheduler. A thread is terminated in the following cases:

The function executed by the thread is exited.
The root function (not a nested function) performed by the thread must be exited by the return operator.
The KosThreadTerminate() or KosThreadExit() function is called.
The KosThreadTerminate() function terminates the thread only if this thread was locked by calling the KosThreadSuspend() function or if it has been in a locked state since it was created.

The KosThreadExit() function terminates the thread even if the function is called from a nested function instead of the root function executed by the thread.
The process was terminated or switched to the "frozen" state.
For details about the "frozen" state, see Managing processes (low-level API task_api.h).

Thread exit codes are defined by the developer. These codes should be specified in the exitCode parameter of the KosThreadTerminate() and KosThreadExit() functions, and when calling the return operator in the function executed by the thread. To get the thread exit code, call the KosThreadWait() function. If successful, this function returns the thread exit code. Otherwise, it returns -1. Therefore, thread exit codes must differ from -1 to avoid ambiguity.

Locking and resuming a thread

To lock a thread, call the KosThreadSuspend() function. This function lets you lock only the calling thread.

To resume a thread that has been locked since it was created or was locked due to a call of the KosThreadSuspend() function, call the KosThreadResume() function.

To lock a thread until another thread completes, call the KosThreadWait() function.

To lock a thread for a defined amount of time, call the KosThreadSleep() function. A call of the KosThreadSleep() function with a 0 value for the mdelay parameter is identical to a call of the KosThreadYield() function that gives up the quantum of the calling thread to other threads until the next time the calling thread appears in the queue.

Guaranteeing that a function can only be called once

The callback function defined through the initRoutine parameter is called only when the KosThreadOnce() function is called for the first time. This does not occur on repeated calls of the KosThreadOnce() function (even from other threads), and the KosThreadOnce() function simply returns control. For example, this ensures that a driver is initialized only once when multiple software components use this driver and start its initialization irrespective of each other.

Special considerations for a thread attached to an interrupt

After a thread is attached to an interrupt, the thread becomes a real-time thread with a FIFO scheduler class and a priority higher than 31. (For details about attaching a thread to an interrupt, see Managing interrupt processing (irq.h). For details about the FIFO real-time thread scheduler class, see Managing threads (low-level API thread_api.h)).

Some functions of this API and other APIs of the libkos library cannot be called from a thread that is attached to an interrupt. These functions include KosThreadSuspend(), KosThreadWait(), KosThreadSleep(), KosThreadYield(), KnFutexWait(), KnNoticeGetEvent(), KnCmConnect(), KnCmListen(), KnAuRead(), and KnSamplingProfiler*().

Getting the base address of the TLS

A thread local storage (TLS) is process memory in which a thread can store data in isolation from other threads. The KosThreadTlsGet() function gets the base address of the TLS. This function is intended for use by the libc library.

Getting the base address and stack limit of the thread

The KosThreadGetStack() function gets the base address and stack limit of the thread. This function is intended for use by the libc library.

Getting a TID

The KasperskyOS kernel assigns an ID to each thread. Thread identifier (TID) is an integer value that is unique for each thread within an entire solution. TIDs are not used to manage threads but instead are used to identify them – for example, in the task_api.h and value_api.h APIs, and also when debugging and logging programs.

To get the current thread's TID, call the KosThreadCurrentId() function. This function lets you get the TID only for the calling thread.

Freeing resources of a terminated thread

Resources of a thread include its stack, context, and TCB. To ensure that the resources of a thread are freed after the thread is terminated, you must close its handle before or after termination of the thread except for the following cases:

The KosThreadCreateDetached() function automatically closes the handle of the created thread.
The KosThreadCreate() function automatically closes the handle of the created thread if it is called with the RTL_NULL value in the handle parameter.
The KosThreadWait() function closes the handle of a thread whose termination it anticipates.
The initial thread has no handle (if this handle was not created by calling the KnThreadOpenCurrent() function from the thread_api.h API).

Resources of threads are also freed upon termination of the process that includes these threads.

Information about API functions

thread.h functions

Function	Information about the function
`KosThreadCreate()`	Purpose Creates a thread. Parameters [out,optional] `handle` – pointer to the thread handle. Specifying `RTL_NULL` closes the handle automatically after the thread is created. [in] `priority` – thread priority. [in,optional] `stackSize` – thread stack limit (in bytes), or `0` to use the default size that was defined when the process was created. [in] `routine` – pointer to the function executed by the thread. The parameter type is defined in the header file `sysroot-*-kos/include/coresrv/thread/thread_api.h` from the KasperskyOS SDK. [in,optional] `context` – pointer to the parameters passed to the function defined through the `routine` parameter, or `RTL_NULL` if parameters do not need to be passed to this function. [in] `suspended` – value defining whether the thread will be created in a suspended (`1`) or running (`0`) state. You cannot specify `1` if the `handle` parameter is set to `RTL_NULL`. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KosThreadCreateDetached()`	Purpose Creates an unlocked thread and closes its handle. Parameters [in] `priority` – thread priority. [in,optional] `stackSize` – thread stack limit (in bytes), or `0` to use the default size that was defined when the process was created. [in] `routine` – pointer to the function executed by the thread. The parameter type is defined in the header file `sysroot-*-kos/include/coresrv/thread/thread_api.h` from the KasperskyOS SDK. [in,optional] `context` – pointer to the parameters passed to the function defined through the `routine` parameter, or `RTL_NULL` if parameters do not need to be passed to this function. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KosThreadCurrentId()`	Purpose Gets the TID for the calling thread. Parameters N/A Returned values TID for the calling thread. The type of returned value is defined in the header file `sysroot-*-kos/include/thread/tidtype.h` from the KasperskyOS SDK.
`KosThreadSuspend()`	Purpose Locks the calling thread. Parameters [in] `handle` – thread handle. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KosThreadResume()`	Purpose Resumes execution of a locked thread. Parameters [in] `handle` – thread handle. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KosThreadExit()`	Purpose Terminates the calling thread. Parameters [in] `exitCode` – thread exit code. Returned values N/A
`KosThreadWait()`	Purpose Locks the calling thread until the defined thread is terminated. Parameters [in] `handle` – thread handle. [in] `timeout` – timeout (in milliseconds) for the termination of a thread, or `INFINITE_TIMEOUT` to define 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 the thread exit code, otherwise it returns `-1`. Additional information Non-blocking call if the `timeout` parameter is set to `0`.
`KosThreadSleep()`	Purpose Locks the calling thread for the specified duration. Parameters [in] `mdelay` – locking time of a thread (in milliseconds), or `INFINITE_TIMEOUT` to set an unlimited locking time. 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`.
`KosThreadYield()`	Purpose Gives up the quantum of the calling thread to other threads until the next time the calling thread appears in the queue. Parameters N/A Returned values N/A
`KosThreadTerminate()`	Purpose Terminates the locked thread. Parameters [in] `handle` – thread handle. [in] `exitCode` – thread exit code. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KosThreadTlsGet()`	Purpose Gets the base address of the TLS for the calling thread. Parameters N/A Returned values Pointer to the TLS for the calling thread, or `RTL_NULL` if the thread does not have a TLS.
`KosThreadGetStack()`	Purpose Gets the base address and stack limit of the thread. Parameters [in] `handle` – thread handle. [out] `size` – pointer to the stack limit (in bytes). Returned values Pointer to the thread stack.
`KosThreadOnce()`	Purpose Guarantees that the defined function will be called only once. Parameters [in] `onceControl` – pointer to the variable that indicates whether or not the defined function was already called. This variable must be initialized with the `KOS_THREAD_ONCE_INIT` value. [in] `initRoutine` – pointer to the function that must be called only one time. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.

Page top