API определен в заголовочном файле sysroot-*-kos/include/kos/dispatch_pool.h из состава KasperskyOS SDK.
API позволяет создать на стороне сервера пул потоков исполнения, обрабатывающих IPC-запросы, чтобы обеспечить повышение производительности обработки IPC-запросов по сравнению с обработкой в одном потоке исполнения. Потоки исполнения в пуле обрабатывают IPC-запросы, поступающие по IPC-каналам, ассоциированным с серверным IPC-дескриптором, заданным при создании пула.
Чтобы использовать пул потоков исполнения для обработки IPC-запросов, реализация методов служб должна быть потокобезопасной.
Сведения о функциях API приведены в таблице ниже.
Создание пула
Чтобы создать пул, нужно вызвать одну из функций KosDispatchPoolStart*(). Функции без постфикса Ex создают пул с параметрами по умолчанию, функции с постфиксом Ex позволяют создать пул с параметрами, отличными от параметров по умолчанию. Функции с суффиксом Attached не возвращают управление на протяжении всего времени жизни созданного пула, функции с суффиксом Detached возвращают управление сразу после создания пула, поскольку в первом случае управление пулом (создание и завершение потоков) осуществляет вызывающий поток, во втором случае управление пулом осуществляет специально созданный поток.
Поля структуры KosDispatchPoolParams предназначены для установки параметров пула. Сразу после создания пул включает minThreadCount потоков. Затем при росте нагрузки на сервер число потоков может увеличиться до maxThreadCount. Сообщение о достижении maxThreadCount помещается в диагностический вывод с периодичностью exhaustionReportPeriod мс. Снижение нагрузки на сервер может повлечь за собой уменьшение числа потоков до minThreadCount, поскольку с периодичностью shrinkPeriod мс выполняется очистка пула от простаивающих потоков. В результате каждой итерации очистки завершается не более shrinkCount потоков. Если параметр shrinkPeriod имеет значение символьной константы KOS_DISPATCH_POOL_NO_SHRINK, то очистка пула от простаивающих потоков не выполняется, и число потоков в пуле, достигнув maxThreadCount, остается неизменным.
Если указать RTL_NULL в поле threadApi структуры KosDispatchPoolParams, то для управления пулом библиотека libkos будет использовать функции по умолчанию (API thread.h), и пул будет состоять из стандартных потоков с приоритетом 10. (О стандартных потоках исполнения см. "Управление потоками исполнения (низкоуровневый API thread_api.h)".) Функции по умолчанию можно заменить собственными, если, например, нужно задать приоритет стандартных потоков выше 10 или для управления пулом требуется использовать API Pthreads. Для этого необходимо указать в поле threadApi структуры KosDispatchPoolParams указатель на структуру KosDispatchPoolThreadApi, которая содержит идентификатор callback-функции для создания потока (create) и идентификатор callback-функции, выполняющей ожидание завершения потока (wait).
Callback-функция, соответствующая идентификатору create, принимает размер стека потока в байтах (входной параметр stackSize), идентификатор выполняемой потоком функции (входной параметр routine) и параметры, которые нужно передать выполняемой потоком функции (входной параметр arg). (Функция, выполняемая потоком, запускает цикл обработки IPC-запросов.) Через выходной параметр handle передает идентификатор созданного потока (например, дескриптор). В случае успеха возвращает rcOk, иначе возвращает код ошибки.
Callback-функция, соответствующая идентификатору wait, принимает идентификатор потока (входной параметр handle) и время ожидания завершения потока (входной параметр timeout). Освобождает ресурсы завершившегося потока. В случае успеха возвращает rcOk. Если время ожидания завершения потока истекло, возвращает rcTimeout. Чтобы поток завершился, библиотека libkos прерывает с помощью API ipc_api.h выполняемый этим потоком системный вызов Recv() с целью выхода из цикла обработки IPC-запросов. Максимальное время ожидания завершения простаивающего потока задает параметр пула shrinkThreadWaitTimeout (в миллисекундах). Максимальное время ожидания завершения потока при удалении пула задает параметр пула stopThreadWaitTimeout (в миллисекундах). В качестве значения этих параметров пула можно указать константу INFINITE_TIMEOUT, чтобы задать неограниченное время ожидания. (Константа INFINITE_TIMEOUT определена в заголовочном файле sysroot-*-kos/include/rtl/rtc.h из состава KasperskyOS SDK.)
Функции создания пула без постфикса Ex инициализируют внутри себя структуру KosDispatchPoolParams с помощью макроса KosDispatchPoolDefaultParams. В определении этого макроса для инициализации структуры KosDispatchPoolParams используются символьные константы вида KOS_DISPATCH_POOL_*_DEFAULT, значения которых соответствуют значениям параметров пула по умолчанию.
Функции создания пула с постфиксом Ex через параметр params принимают структуру KosDispatchPoolParams. Значения параметров пула не должны быть меньше значений символьных констант вида KOS_DISPATCH_POOL_*_MIN.
Все функции создания пула принимают через параметр endpoint серверный IPC-дескриптор. Потоки созданного пула будут обрабатывать IPC-запросы, поступающие по IPC-каналам, ассоциированным с этим IPC-дескриптором.
Каждый поток пула запускает цикл обработки IPC-запросов вызовом функции NkKosDoDispatchEx() из API transport-kos-dispatch.h. Этой функции требуется структура NkKosDispatchInfo, тип которой определен в заголовочном файле sysroot-*-kos/include/coresrv/nk/transport-kos-dispatch.h из состава KasperskyOS SDK. Поэтому все функции создания пула принимают указатель на структуру NkKosDispatchInfo через параметр info. Для инициализации этой структуры можно использовать макросы, определенные в заголовочном файле sysroot-*-kos/include/coresrv/nk/transport-kos-dispatch.h из состава KasperskyOS SDK (например, NK_TASK_DISPATCH_INFO_INITIALIZER()).
Все функции создания пула принимают через параметр stackSize размер стека потоков, то есть каждый поток в пуле будет иметь стек заданного размера. Размер стека потоков можно задать константой ThreadStackSizeDefault, определенной в заголовочном файле sysroot-*-kos/include/coresrv/thread/thread_api.h из состава KasperskyOS SDK. Но также следует учитывать, что функция NkKosDoDispatchEx() выполняет попытку создать буферы для IPC-запросов и IPC-ответов в стеке, и размеры этих буферов могут быть кратно больше значения константы ThreadStackSizeDefault. (В случае неуспешной попытки создать буфер в стеке функция NkKosDoDispatchEx() пытается создать этот буфер в куче.) Если предпочтительнее разместить буферы для IPC-запросов и IPC-ответов в стеке, нужно увеличить размер стека с учетом общего размера этих буферов.
Удаление пула
Удаление пула завершает все его потоки и освобождает ресурсы завершенных потоков. Чтобы удалить пул, созданный вызовом функции с суффиксом Detached, нужно вызвать функцию KosDispatchPoolStop(). (Использование функции с суффиксом Attached предполагает, что нет необходимости удалять пул до завершения сервера.)
Независимо от того, какая из функций API использовалась для создания пула, удаление может произойти в результате ошибки, произошедшей при обработке IPC-запроса или при управлении пулом.
Сведения о функциях API
Функции dispatch_pool.h
Функция |
Сведения о функции |
|---|---|
|
Назначение Создает пул потоков исполнения, обрабатывающих IPC-запросы. Управление пулом осуществляет вызывающий поток исполнения. Параметры
Возвращаемые значения В случае успеха возвращает |
|
Назначение Создает пул потоков исполнения, обрабатывающих IPC-запросы. Управление пулом осуществляет вызывающий поток исполнения. Параметры
Возвращаемые значения В случае успеха возвращает |
|
Назначение Создает пул потоков исполнения, обрабатывающих IPC-запросы. Управление пулом осуществляет специально созданный поток исполнения. Параметры
Возвращаемые значения В случае успеха возвращает |
|
Назначение Создает пул потоков исполнения, обрабатывающих IPC-запросы. Управление пулом осуществляет специально созданный поток исполнения. Параметры
Возвращаемые значения В случае успеха возвращает |
|
Назначение Удаляет пул потоков исполнения, обрабатывающих IPC-запросы. Удаляемый пул создан вызовом функции Параметры
Возвращаемые значения В случае успеха возвращает |