Using a working set (ws_api.h)

The API is defined in the header file sysroot-*-kos/include/coresrv/vmm/ws_api.h from the KasperskyOS SDK.

The API is intended for performing operations with a working set. Working set (WS) is an abstraction that describes the use of physical memory in a system. This is a KasperskyOS kernel object associated with data such as the total number of physical memory pages in the system, the number of occupied physical memory pages in the system, and threshold values for the amount of occupied physical memory in the system.

The working set contains two threshold values (upper and lower) for the amount of occupied physical memory in the system. The kernel tracks the number of occupied pages of physical memory and emits a signal when it reaches the defined thresholds. If the current number of occupied pages is below the upper threshold, attainment of the upper threshold is monitored. If the current number of occupied pages is not below the upper threshold, attainment of the lower threshold is monitored. When the upper threshold is reached, the kernel starts tracking attainment of the lower threshold, and vice versa.

If the number of occupied pages of physical memory in the system reaches a threshold value, the kernel associates the event with the working set by specifying the EVENT_WS_THRESHOLD flag in the event mask. To receive notifications about events related to the working set, use the notice_api.h API.

The API functions are thread-safe.

Information about API functions is provided in the table below.

Opening access to a working set

To open access to a working set, call the KnPmmWsOpen() function. Access to a working set can be opened multiple times in one or more processes. The KnPmmWsOpen() function uses the outHandle output parameter to pass the handle of the working set. This handle is an input parameter not only for all other functions of this API, but also for the notice_api.h API functions that are used to configure the notification receiver.

If access to the working set is no longer required, its handle must be closed.

Getting the characteristics of a working set

To get the characteristics of a working set, call the KnPmmWsGetInfo() function.

A working set has the following characteristics:

• Total number of pages of physical memory in the system (maxSize)
• Number of occupied pages of physical memory in the system (currentSize)
• Lower threshold value for the amount of occupied physical memory in the system (lowThreshold)
• Upper threshold value for the amount of occupied physical memory in the system (highThreshold)
• Characteristic that indicates whether threshold values are set for the amount of occupied physical memory in the system (nextThresholdToBeTriggered)

The nextThresholdToBeTriggered characteristic can have the following values:

• WsNoThresholdIsActive – no threshold values have been set.
• WsThresholdHighIsNext – the upper threshold value is being monitored.
• WsThresholdLowIsNext – the lower threshold value is being monitored.

Setting and removing threshold values for the amount of occupied physical memory in the system

To set the threshold values for the amount of occupied physical memory in the system, call the KnPmmWsSetThreshold() function. Prior to the first call to this function, the threshold values are zero. As a result of this call, the kernel begins to track the attainment of the set threshold values. Threshold values cannot be set until the previously set values are removed.

To remove the threshold values for the amount of occupied physical memory in the system, call the KnPmmWsClearThreshold() function. As a result of this call, the kernel stops tracking the attainment of the previously set threshold values and these threshold values are cleared.

Threshold values for the amount of occupied physical memory in the system may be removed and re-set by another process or by different code in the same process.

Information about API functions

ws_api.h functions

Function	Information about the function
KnPmmWsOpen()	Purpose Provides access to the working set. Parameters [out] outHandle‍‍‍‍‍‍‍‍ ‍‍‍‍‍‍‍‍–‍‍‍‍‍‍‍‍‍ ‍‍‍‍‍‍‍‍‍pointer to the working set handle. Returned values If successful, the function returns rcOk, otherwise it returns an error code.
KnPmmWsGetInfo()	Purpose Gets the characteristics of the working set. Parameters [in] ws – working set handle. [out] info – pointer to the structure for storing the characteristics of the working set. Returned values If successful, the function returns rcOk, otherwise it returns an error code.
KnPmmWsSetThreshold()	Purpose Sets the threshold values for the amount of used physical memory in the system. Parameters [in] ws – working set handle. [in] threshold – the lower threshold value, in memory pages. [in] width – the offset of the upper threshold value relative to the lower one, in memory pages. The sum of threshold and width gives the upper threshold value. Returned values If successful, the function returns rcOk, otherwise it returns an error code. If threshold values have already been set, the function returns rcAlreadyDone.
KnPmmWsClearThreshold()	Purpose Delete the threshold values for the amount of used physical memory in the system. Parameters [in] ws – working set handle. Returned values If successful, the function returns rcOk, otherwise it returns an error code.

Page top