The API is defined in the header file sysroot-*-kos/include/kos/dispatch_pool.h from the KasperskyOS SDK.
The API lets you create a pool of threads that handle IPC requests on the server side to enhance the productivity of IPC request processing when compared to processing them in a single thread. The threads in the pool process the IPC requests received over the IPC channels associated with the server IPC handle that was defined when the pool was created.
To use a thread pool to process IPC requests, you must employ a thread-safe implementation of endpoint methods.
Information about API functions is provided in the table below.
Creating a pool
To create a pool, call one of the KosDispatchPoolStart*() functions. Functions without the Ex postfix create a pool with the default parameters, while functions with the Ex postfix let you create a pool with parameters different from the default parameters. Functions with the Attached suffix do not return control throughout the entire lifetime of the created pool, while functions with the Detached suffix return control immediately after the pool is created. This is because the calling thread manages the pool (creates and terminates threads) in the first case, while a specially created thread manages the pool in the second case.
The fields of the KosDispatchPoolParams structure are intended for setting the pool parameters. A pool includes minThreadCount threads immediately after the pool is created. As the load on the server increases, the number of threads may increase to maxThreadCount. A message about reaching maxThreadCount is put into diagnostic output every exhaustionReportPeriod ms. Reducing the load on the server may cause the number of threads to decrease to minThreadCount because the pool is cleared of idle threads every shrinkPeriod ms. No more than shrinkCount threads are terminated as a result of each clearing iteration. If the shrinkPeriod parameter has the KOS_DISPATCH_POOL_NO_SHRINK symbolic constant value, the pool is not cleared of idle threads and the number of threads in a pool that has reached the maxThreadCount remains unchanged.
If you specify RTL_NULL in the threadApi field of the KosDispatchPoolParams structure, the libkos library will use the default functions (API thread.h) to manage the pool and the pool will consist of standard threads with a priority of 10. (For details about standard threads, see Managing threads (low-level API thread_api.h).) You can replace the default functions with your own if necessary. For example, this may be required if you need to define a standard thread priority higher than 10 or if you need to use the API Pthreads for pool management. To do so, in the threadApi field of the KosDispatchPoolParams structure, you must specify the pointer to the KosDispatchPoolThreadApi structure that contains the ID of the callback function for creating a thread (create) and the ID of the callback function that waits for the thread to terminate (wait).
The callback function corresponding to the create identifier accepts the thread stack size in bytes (the stackSize input parameter), the identifier of the function to be executed by the thread (the routine input parameter), and the parameters to be passed to the function being executed by the thread (the arg input parameter). (The function executed by the thread starts the IPC request processing loop.) The handle output parameter is used to pass the identifier of the created thread (for example: handle). If successful, the function returns rcOk, otherwise it returns an error code.
The callback function corresponding to the wait identifier accepts the thread identifier (the handle input parameter) and the time to wait for the thread to terminate (the timeout input parameter). It frees up the resources of the terminated thread. Returns rcOk if successful. If the thread termination timeout has elapsed, it returns rcTimeout. To allow the thread to terminate, the libkos library uses the ipc_api.h API to interrupt the Recv() system call that is executed by this thread for the purpose of exiting the IPC request processing loop. The maximum time to wait for termination of an idle thread is defined by the shrinkThreadWaitTimeout pool parameter (in milliseconds). The maximum time to wait for termination of a thread when deleting a pool is defined by the stopThreadWaitTimeout pool parameter (in milliseconds). To set an unlimited timeout, the INFINITE_TIMEOUT constant can be specified for these pool parameters. (The INFINITE_TIMEOUT constant is defined in the header file sysroot-*-kos/include/rtl/rtc.h from the KasperskyOS SDK.)
The functions for creating a pool without the Ex postfix use the KosDispatchPoolDefaultParams macro to initialize the KosDispatchPoolParams structure within these functions. The definition of this macro for initializing the KosDispatchPoolParams structure uses symbolic constants in the format KOS_DISPATCH_POOL_*_DEFAULT whose values correspond to the values of the default pool parameters.
Functions for creating a pool with the Ex postfix receive the KosDispatchPoolParams structure via the params parameter. The values of pool parameters must not be less than the values of symbolic constants in the format KOS_DISPATCH_POOL_*_MIN.
All pool creation functions receive the server IPC handle via the endpoint parameter. The threads of the created pool will process IPC requests received over the IPC channels associated with this IPC handle.
Each thread of the pool starts an IPC request processing loop by calling the NkKosDoDispatchEx() function from the API transport-kos-dispatch.h. This function requires the NkKosDispatchInfo structure whose type is defined in the header file sysroot-*-kos/include/coresrv/nk/transport-kos-dispatch.h from the KasperskyOS SDK. Therefore, all pool creation functions receive the pointer to the NkKosDispatchInfo structure via the info parameter. To initialize this structure, you can use the macros defined in the header file sysroot-*-kos/include/coresrv/nk/transport-kos-dispatch.h from the KasperskyOS SDK (for example: NK_TASK_DISPATCH_INFO_INITIALIZER()).
All pool creation functions receive the thread stack limit via the stackSize parameter, which means that each thread in the pool will have a stack of the defined size. The thread stack limit can be specified by the ThreadStackSizeDefault constant that is defined in the header file sysroot-*-kos/include/coresrv/thread/thread_api.h from the KasperskyOS SDK. However, you should also keep in mind that the NkKosDoDispatchEx() function attempts to create buffers for IPC requests and IPC responses in the stack, and the sizes of these buffers may be a multiple larger than the value of the ThreadStackSizeDefault constant. (If the attempt to create a buffer in the stack is unsuccessful, the NkKosDoDispatchEx() function attempts to create this buffer in the heap.) If it is more preferable to place buffers for IPC requests and IPC responses in the stack, you must increase the stack limit according to the total size of these buffers.
Deleting a pool
When a pool is deleted, all of its threads are terminated and the resources of the terminated threads are freed. To delete a pool that was created by calling a function with the Detached suffix, call the KosDispatchPoolStop() function. (When using a function with the Attached suffix, you do not need to delete the pool prior to server termination.)
Irrespective of which specific API function was used to create a pool, the pool may be deleted due to an error that occurs when processing an IPC request or when managing the pool.
Information about API functions
dispatch_pool.h functions
Function |
Information about the function |
|---|---|
|
Purpose Creates a pool of threads that process IPC requests. The pool is managed by the calling thread. Parameters
Returned values If successful, the function returns |
|
Purpose Creates a pool of threads that process IPC requests. The pool is managed by the calling thread. Parameters
Returned values If successful, the function returns |
|
Purpose Creates a pool of threads that process IPC requests. The pool is managed by a specially created thread. Parameters
Returned values If successful, the function returns |
|
Purpose Creates a pool of threads that process IPC requests. The pool is managed by a specially created thread. Parameters
Returned values If successful, the function returns |
|
Purpose Deletes a pool of threads that process IPC requests. The deleted pool was created by calling the Parameters
Returned values If successful, the function returns |