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

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

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

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

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

Библиотека libkos также предоставляет низкоуровневый API для управления потоками исполнения, который определен в заголовочном файле sysroot-*-kos/include/coresrv/thread/thread_api.h из состава KasperskyOS SDK. Низкоуровневый API следует использовать, если только недостаточно возможностей высокоуровневого API.

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

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

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

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

Осуществлен выход из функции, выполняемой потоком исполнения.
Должен быть осуществлен выход оператором return из корневой (не из вложенной) функции, выполняемой потоком исполнения.
Вызвана функция KosThreadTerminate() или KosThreadExit().
Функция KosThreadExit() завершает поток исполнения, даже если вызвана не из корневой функции, выполняемой потоком исполнения, а из вложенной.
Завершился или перешел в "замороженное" состояние процесс.
О "замороженном" состоянии процесса см. "Управление процессами (низкоуровневый API task_api.h)".

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

Регистрация функций, вызываемых при создании и завершении потоков исполнения

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

Зарегистрированная функция вызывается в следующих случаях:

при создании потока исполнения вызовом функции KosThreadCreate();
при завершении потока исполнения, созданного вызовом функции KosThreadCreate(), в результате выхода из функции, выполняемой этим потоком;
при завершении потока исполнения вызовом функции KosThreadExit().

Можно зарегистрировать несколько функций, и каждая из них будет вызвана при создании и завершении потока исполнения. При создании потока исполнения зарегистрированная функция вызывается с аргументом KosThreadCallbackReasonCreate в параметре reason. При завершении потока исполнения зарегистрированная функция вызывается с аргументом KosThreadCallbackReasonDestroy в параметре reason.

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

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

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

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

Для потоков исполнения, привязанных к прерываниям, нельзя применять многие функции API, в том числе KosThreadCreate(), KosThreadSuspend(), KosThreadResume(), KosThreadTerminate(), KosThreadWait(), KosThreadSleep(), KosThreadYield().

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

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

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

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

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

Ресурсами потока исполнения являются его стек, контекст и TCB (о TCB см. "Управление потоками исполнения (низкоуровневый API thread_api.h)"). Чтобы ресурсы потока исполнения были освобождены после его завершения, нужно вызвать функцию KosThreadWait() для ожидания завершения этого потока исполнения. (Исключением являются начальный поток процесса и поток исполнения, созданный функцией KosThreadCreateDetached().) Также ресурсы потоков исполнения освобождаются при завершении процесса, в который они входят.

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

Функции thread.h

Функция	Сведения о функции
`KosThreadCallbackRegister()`	Назначение Регистрирует функцию, вызываемую при создании и завершении потоков исполнения вызывающего процесса. Параметры [in] `callback` – указатель на функцию. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosThreadCallbackUnregister()`	Назначение Дерегистрирует функцию, вызываемую при создании и завершении потоков исполнения вызывающего процесса. Параметры [in] `callback` – указатель на функцию. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosThreadCreate()`	Назначение Создает поток исполнения. Параметры [out] `handle` – указатель на дескриптор потока исполнения. [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`). Возвращаемые значения В случае успеха возвращает `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) вызывающего потока исполнения. Параметры Нет. Возвращаемые значения Идентификатор потока исполнения. Тип идентификатора определен в заголовочном файле `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`, чтобы задать неограниченное время ожидания. Возвращаемые значения В случае успеха возвращает код завершения потока исполнения, иначе возвращает `-1`.
`KosThreadSleep()`	Назначение Блокирует вызывающий поток исполнения на заданное время. Параметры [in] `mdelay` – время блокировки потока исполнения в миллисекундах. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosThreadYield()`	Назначение Отдает квант времени вызывающего потока исполнения следующему в очереди. Параметры Нет. Возвращаемые значения Нет. Дополнительные сведения Вызов функции `KosThreadYield()` идентичен вызову функции `KosThreadSleep()` с нулевым значением параметра `mdelay`.
`KosThreadTerminate()`	Назначение Завершает поток исполнения. Параметры [in] `handle` – дескриптор потока исполнения. [in] `exitCode` – код завершения потока исполнения. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosThreadTlsGet()`	Назначение Позволяет получить базовый адрес локальной памяти потока исполнения (TLS) для вызывающего потока исполнения. Параметры Нет. Возвращаемые значения Указатель на TLS или `RTL_NULL`, если у потока исполнения нет TLS.
`KosThreadTlsSet()`	Назначение Задает базовый адрес локальной памяти потока исполнения (TLS) для вызывающего потока исполнения. Параметры [in] `tls` – указатель на TLS. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KosThreadGetStack()`	Назначение Позволяет получить базовый адрес и размер стека потока исполнения. Параметры [in] `handle` – дескриптор потока исполнения. [out] `size` – указатель на размер стека в байтах. Возвращаемые значения Указатель на стек потока исполнения.
`KosThreadOnce()`	Назначение Гарантирует, что заданная функция будет вызвана только один раз. Параметры [in] `onceControl` – указатель на переменную, которая отражает, была ли уже вызвана заданная функция. Эту переменную нужно инициализировать значением `KOS_THREAD_ONCE_INIT`. [in] `initRoutine` – указатель на функцию, которая должна быть вызвана только один раз. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.

В начало