KasperskyOS Community Edition 1.3

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.
• Register functions that are called when creating and terminating threads.

Information about API functions is provided in the table below.

Creating threads

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 threads

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 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 of the KasperskyOS-based solution. 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.

Registering functions that are called when creating and terminating threads

To register a function that is called when threads of a process are created and terminated, call the KosThreadCallbackRegister() function from this process.

The registered function is called in the following cases:

• A thread is created by calling the KosThreadCreate() function.
• The thread that was created by calling the KosThreadCreate() function is terminated as a result of exiting a function executed by this thread.
• The thread is terminated by calling the KosThreadExit() function.

You can register multiple functions, and each of them will be called when a thread is created and terminated. When a thread is created, the registered function is called with the KosThreadCallbackReasonCreate argument in the reason parameter. When the thread is terminated, the registered function is called with the KosThreadCallbackReasonDestroy argument in the reason parameter.

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 threads attached to interrupts

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)).

Defining and getting the base address of the TLS for threads

A thread local storage (TLS) is process memory in which a thread can store data in isolation from other threads. The base address for TLS is defined and received by the KosThreadTlsSet() and KosThreadTlsGet() functions, respectively. These functions are intended for use by the libc library.

Getting the base address and stack limit of threads

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

Freeing resources of terminated threads

Resources of a thread include its stack, context, and TCB (for details about a TCB, see Managing threads (low-level API thread_api.h)). To release thread resources after the thread terminates, call the KosThreadWait() function to wait for completion of the thread. (Exceptions to this case are the initial thread of a process and a thread created by the KosThreadCreateDetached() function.) Thread resources are also released upon termination of the process that includes these threads.

Information about API functions

thread.h functions