Управление потоками исполнения (высокоуровневый API thread.h)

API определен в заголовочном файле sysroot-*-kos/include/kos/thread.h из состава KasperskyOS SDK.

Основные возможности API:

• создавать, завершать, блокировать потоки исполнения;
• возобновлять исполнение заблокированных потоков;
• получать сведения о потоках исполнения.

Сведения о функциях API приведены в таблице ниже.

Библиотека libkos также предоставляет низкоуровневый API для управления потоками исполнения. Низкоуровневый API следует использовать, если недостаточно возможностей высокоуровневого API.

Создание потока исполнения

Чтобы создать поток исполнения, нужно вызвать функцию KosThreadCreate() или KosThreadCreateDetached(). Эти функции создают стандартный поток исполнения, приоритет которого может принимать значения от 0 до 15. (О стандартных потоках исполнения см. "Управление потоками исполнения (низкоуровневый API thread_api.h)".)

Завершение потока исполнения

Завершение потока исполнения представляет собой его перманентное удаление из планировщика. Поток исполнения завершается в следующих случаях:

• Осуществлен выход из функции, выполняемой потоком исполнения.

  Должен быть осуществлен выход оператором return из корневой (не из вложенной) функции, выполняемой потоком исполнения.

• Вызвана функция KosThreadTerminate() или KosThreadExit().

  Функция KosThreadTerminate() завершает поток исполнения только в том случае, если этот поток заблокирован вызовом функции KosThreadSuspend() или находится в заблокированном состоянии с момента создания.

  Функция KosThreadExit() завершает поток исполнения, даже если вызвана не из корневой функции, выполняемой потоком исполнения, а из вложенной.

• Завершился или перешел в "замороженное" состояние процесс.

  О "замороженном" состоянии процесса см. "Управление процессами (низкоуровневый API task_api.h)".

Коды завершения потоков исполнения определяются разработчиком решения. Эти коды нужно указывать в параметре exitCode функций KosThreadTerminate() и KosThreadExit(), а также при вызове оператора return в функции, выполняемой потоком исполнения. Чтобы получить код завершения потока исполнения, нужно вызвать функцию KosThreadWait(). В случае успеха эта функция возвращает код завершения потока исполнения, иначе возвращает -1, поэтому коды завершения потоков исполнения должны быть отличными от -1, чтобы избежать неоднозначности.

Блокирование и возобновление исполнения потока исполнения

Чтобы заблокировать поток исполнения, нужно вызвать функцию KosThreadSuspend(). Эту функция позволяет заблокировать только вызывающий поток исполнения.

Чтобы возобновить исполнение потока, заблокированного с момента создания или в результате вызова функции KosThreadSuspend(), нужно вызвать функцию KosThreadResume().

Чтобы заблокировать поток исполнения до завершения другого, нужно вызвать функцию KosThreadWait().

Чтобы заблокировать поток исполнения на заданное время, нужно вызвать функцию KosThreadSleep(). Вызов функции KosThreadSleep() с нулевым значением параметра mdelay идентичен вызову функции KosThreadYield(), которая отдает квант времени вызывающего потока исполнения другим потокам исполнения в до следующего появления вызывающего потока исполнения в очереди.

Гарантирование невозможности вызвать функцию несколько раз

Только при первом вызове функции KosThreadOnce() вызывается заданная через параметр initRoutine callback-функция. При повторных вызовах функции KosThreadOnce() (даже из других потоков исполнения) этого не происходит, и функция KosThreadOnce() просто возвращает управление. Например, это обеспечивает однократную инициализацию драйвера, в том случае, когда несколько программных компонентов используют этот драйвер и запускают его инициализацию независимо друг от друга.

Особенности потока исполнения, привязанного к прерыванию

После привязки к прерыванию поток исполнения становится потоком исполнения реального времени с классом планирования FIFO и приоритетом выше 31. (О привязке потока исполнения к прерыванию см. "Управление обработкой прерываний (irq.h)". О классе планирования потоков реального времени FIFO см. "Управление потоками исполнения (низкоуровневый API thread_api.h)".)

Из потока исполнения, привязанного к прерыванию, нельзя вызывать некоторые функции этого и других API библиотеки libkos, включая KosThreadSuspend(), KosThreadWait(), KosThreadSleep(), KosThreadYield(), KnFutexWait(), KnNoticeGetEvent(), KnCmConnect(), KnCmListen(), KnAuRead(), KnSamplingProfiler*().

Получение базового адреса TLS

Локальная память потока исполнения (англ. Thread Local Storage, TLS) – это память процесса, где поток исполнения может хранить данные изолированно от других потоков исполнения. Получить базовый адрес TLS позволяет функция KosThreadTlsGet(). Эта функция предназначена для использования библиотекой libc.

Получение базового адреса и размера стека потока исполнения

Получить базовый адрес и размер стека потока исполнения позволяет функция KosThreadGetStack(). Эта функция предназначена для использования библиотекой libc.

Получение TID

Ядро KasperskyOS назначает каждому потоку исполнения идентификатор. Идентификатор потока исполнения (англ. Thread Identifier, TID) представляет собой целочисленное значение, уникальное для каждого потока исполнения в рамках всего решения. Идентификаторы TID не используются для управления потоками исполнения, а применяются для их идентификации, например, в API task_api.h, value_api.h, а также при отладке и журналировании программ.

Чтобы получить TID, нужно вызвать функцию KosThreadCurrentId(). Эта функция позволяет получить TID только для вызывающего потока исполнения.

Освобождение ресурсов завершившегося потока исполнения

Ресурсами потока исполнения являются его стек, контекст и TCB. Чтобы ресурсы потока исполнения были освобождены после его завершения, нужно до или после завершения этого потока исполнения закрыть его дескриптор. Исключением являются следующие случаи:

• Функция KosThreadCreateDetached() автоматически закрывает дескриптор созданного потока исполнения.
• Функция KosThreadCreate() автоматически закрывает дескриптор созданного потока исполнения, если вызвана со значением RTL_NULL в параметре handle.
• Функция KosThreadWait() закрывает дескриптор потока исполнения, завершения которого ожидает.
• Начальный поток исполнения не имеет дескриптора (если этот дескриптор не создан вызовом функции KnThreadOpenCurrent() из API thread_api.h).

Также ресурсы потоков исполнения освобождаются при завершении процесса, в который они входят.

Сведения о функциях API

Функции thread.h

Функция	Сведения о функции
KosThreadCreate()	Назначение Создает поток исполнения. Параметры [out,optional] handle – указатель на дескриптор потока исполнения. Если указать RTL_NULL, дескриптор будет закрыт автоматически после создания потока исполнения. [in] priority – приоритет потока исполнения. [in,optional] stackSize – размер стека потока исполнения в байтах или 0, чтобы был использован размер по умолчанию, заданный при создании процесса. [in] routine – указатель на функцию, выполняемую потоком исполнения. Тип параметра определен в заголовочном файле sysroot-*-kos/include/coresrv/thread/thread_api.h из состава KasperskyOS SDK. [in,optional] context – указатель на параметры, передаваемые функции, заданной через параметр routine, или RTL_NULL, если этой функции не требуется передавать параметры. [in] suspended – значение, задающее, что поток исполнения будет создан заблокированным (1) или незаблокированным (0). Нельзя указывать 1, если в параметре handle указано значение RTL_NULL. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KosThreadCreateDetached()	Назначение Создает незаблокированный поток исполнения и закрывает его дескриптор. Параметры [in] priority – приоритет потока исполнения. [in,optional] stackSize – размер стека потока исполнения в байтах или 0, чтобы был использован размер по умолчанию, заданный при создании процесса. [in] routine – указатель на функцию, выполняемую потоком исполнения. Тип параметра определен в заголовочном файле sysroot-*-kos/include/coresrv/thread/thread_api.h из состава KasperskyOS SDK. [in,optional] context – указатель на параметры, передаваемые функции, заданной через параметр routine, или RTL_NULL, если этой функции не требуется передавать параметры. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KosThreadCurrentId()	Назначение Позволяет получить TID для вызывающего потока исполнения. Параметры Нет. Возвращаемые значения TID для вызывающего потока исполнения. Тип возвращаемого значения определен в заголовочном файле sysroot-*-kos/include/thread/tidtype.h из состава KasperskyOS SDK.
KosThreadSuspend()	Назначение Блокирует вызывающий поток исполнения. Параметры [in] handle – дескриптор потока исполнения. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KosThreadResume()	Назначение Возобновляет исполнение заблокированного потока. Параметры [in] handle – дескриптор потока исполнения. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KosThreadExit()	Назначение Завершает вызывающий поток исполнения. Параметры [in] exitCode – код завершения потока исполнения. Возвращаемые значения Нет.
KosThreadWait()	Назначение Блокирует вызывающий поток исполнения до завершения заданного потока исполнения. Параметры [in] handle – дескриптор потока исполнения. [in] timeout – время ожидания завершения потока исполнения в миллисекундах или INFINITE_TIMEOUT, чтобы задать неограниченное время ожидания. Константа INFINITE_TIMEOUT определена в заголовочном файле sysroot-*-kos/include/rtl/rtc.h из состава KasperskyOS SDK. Возвращаемые значения В случае успеха возвращает код завершения потока исполнения, иначе возвращает -1. Дополнительные сведения Неблокирующий вызов, если в параметре timeout указан 0.
KosThreadSleep()	Назначение Блокирует вызывающий поток исполнения на заданное время. Параметры [in] mdelay – время блокировки потока исполнения в миллисекундах или INFINITE_TIMEOUT, чтобы задать неограниченное время блокировки. Константа INFINITE_TIMEOUT определена в заголовочном файле sysroot-*-kos/include/rtl/rtc.h из состава KasperskyOS SDK. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки. Дополнительные сведения Неблокирующий вызов, если в параметре mdelay указан 0.
KosThreadYield()	Назначение Отдает квант времени вызывающего потока исполнения другим потокам исполнения до следующего появления вызывающего потока исполнения в очереди. Параметры Нет. Возвращаемые значения Нет.
KosThreadTerminate()	Назначение Завершает заблокированный поток исполнения. Параметры [in] handle – дескриптор потока исполнения. [in] exitCode – код завершения потока исполнения. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KosThreadTlsGet()	Назначение Позволяет получить базовый адрес TLS для вызывающего потока исполнения. Параметры Нет. Возвращаемые значения Указатель на TLS для вызывающего потока исполнения или RTL_NULL, если у потока исполнения нет TLS.
KosThreadGetStack()	Назначение Позволяет получить базовый адрес и размер стека потока исполнения. Параметры [in] handle – дескриптор потока исполнения. [out] size – указатель на размер стека в байтах. Возвращаемые значения Указатель на стек потока исполнения.
KosThreadOnce()	Назначение Гарантирует, что заданная функция будет вызвана только один раз. Параметры [in] onceControl – указатель на переменную, которая отражает, была ли уже вызвана заданная функция. Эту переменную нужно инициализировать значением KOS_THREAD_ONCE_INIT. [in] initRoutine – указатель на функцию, которая должна быть вызвана только один раз. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.

В начало