1# QoS Development 2 3## **Scenario** 4 5In a multi-processor or multi-tasking OS, resources such as CPUs and memory are shared among processes or tasks. Proper scheduling ensures fair distribution of resources, fast system response, and optimal resource utilization. Prioritizing tasks of applications based on their importance can help the system better schedule tasks. This topic describes how to use the quality-of-service (QoS) feature and related APIs to adjust the running time of tasks in the OpenHarmony system. 6 7You can customize the attributes for priority-based task scheduling based on the QoS feature. 8 9## Basic Concepts 10 11### QoS 12 13In OpenHarmony, the QoS feature allows critical tasks to receive necessary resources to meet performance requirements. You can prioritize tasks with different QoS levels based on their importance. The system then arranges the running time and sequence of each task based on their QoS level. For example, when multiple tasks need to be executed in the system, the tasks with less interaction with users, such as the background download tasks, can be executed later than the tasks perceived by users, such as animation drawing. 14 15### QoS Level 16Currently, OpenHarmony provides six QoS levels in ascending order based on the degree of system-user interaction. 17 18| QoS Level | Application Scenario | Load | 19| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | 20| QOS_BACKGROUND | Background tasks invisible to users, such as data synchronization and backup.| It takes several minutes or hours to complete the task.| 21| QOS_UTILITY | Tasks that do not require immediate response, such as data download and import.| It takes several seconds or minutes to complete the task.| 22| QOS_DEFAULT | Default level.| It takes a few seconds to complete the task.| 23| QOS_USER_INITIATED | Tasks triggered by users with observable progress, for example, opening a file.| The task is completed in seconds.| 24| QOS_DEADLINE_REQUEST | Tasks that require an immediate response, such as page loading.| The task is done immediately.| 25| QOS_USER_INTERACTIVE | User interaction tasks (UI thread, interface refreshing, and animation).| The task is instant.| 26 27The QoS level is specified by **QoS_level**, which is an enum defined as follows: 28### QoS_Level Declaration 29```{.c} 30typedef enum QoS_Level { 31 /** 32 * QoS level for background tasks, such as data synchronization. 33 */ 34 QOS_BACKGROUND, 35 /** 36 * QoS level for tasks that do not require immediate response, such as download. 37 */ 38 QOS_UTILITY, 39 /** 40 * Default QoS level. 41 */ 42 QOS_DEFAULT, 43 /** 44 * QoS level for tasks triggered by users with observable progress, such as opening a file. 45 */ 46 QOS_USER_INITIATED, 47 /** 48 * QoS level for tasks that require immediate response, such as page loading. 49 */ 50 QOS_DEADLINE_REQUEST, 51 /** 52 * QoS level for user interaction tasks, such as animation drawing. 53 */ 54 QOS_USER_INTERACTIVE, 55} QoS_Level; 56 57``` 58 59## Effect 60A task with a higher QoS level is allocated more CPU time than a task with a lower QoS level. 61 62The following shows how proper QoS accelerates application execution. 63 64### Optimization of Thread Execution by QoS 65 66#### Before Using QoS 67 68Thread 1 and thread 2 are two key threads of an application. During the running of thread 1, thread 2 is triggered. Then, thread 1 will be blocked until thread 2 is executed. Before the QoS levels of the two threads are marked, thread 3 and thread 4 take precedence over these two threads. The figure above illustrates the execution of thread 1 and thread 2 before QoS is used. 69 701. Thread 1 waits to be woken up by thread 2. However, thread 2 has a low priority and is always preempted for a long time. As a result, thread 1 sleeps for a long time. 71 722. Thread 1 also has a low priority and waits for a long period of time after being woken up. 73 743. Thread 1 has a low priority and is always preempted by other threads for a long period of time during running. 75 76#### After using QoS 77 78 79The figure above illustrates the thread execution after QoS levels are set for thread 1 and thread 2. 80 811. The ratio of thread 2 running time increases, which decreases the wait time of thread 1. 82 832. After thread 1 is woken up by thread 2, the wait time decreases. 84 853. The ratio of thread 1 running time increases, and the preemption proportion decreases. 86 87### Optimization of the RN Framework by QoS 88As indicated by the following table, the performance of the open-source benchmark test is improved by about 13% after the QoS levels are set for key threads in the RN framework. 89 90| Scenario | Test Environment| Hermes Engine Time| RN Common Time| Common Instruction Execution Time for RN Framework + ArkUI Native Rendering| Native Rendering Period| Total| 91| ----------- | ----------- | ----------- | ----------- | ----------- | ----------- | ----------- | 92| benchmark<br>1500view | Without QoS | 173.1 ms | 24.3 ms | 33.1 ms | 4.03 ms | 270.8 ms | 93| benchmark<br>1500view | With QoS | 144.8 ms | 23.4 ms | 33.7 ms | 34.8 ms | 236.6 ms | 94 95## Available APIs 96 97| API | Description | Parameter | Return Value | 98| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | 99| OH_QoS_SetThreadQoS(QoS_Level level) | Sets the QoS level for this task.| QoS_Level level | **0** or **–1**| 100| OH_QoS_ResetThreadQoS() | Removes the QoS level for this task.| N/A| **0** or **–1**| 101| OH_QoS_GetThreadQoS(QoS_Level *level) | Obtains the QoS level of this task.| QoS_Level *level | **0** or **–1**| 102 103### Constraints 104* The QoS APIs can be used only for the current task. 105 106## Function Description 107 108### OH_QoS_SetThreadQoS 109 110#### Function 111```{.c} 112int OH_QoS_SetThreadQoS(QoS_Level level); 113``` 114 115#### Parameters 116QoS_Level level 117* QoS level to set. 118 119#### Return Value 120* Returns **0** if the operation is successful; returns **-1** otherwise. 121 122#### Description 123Sets the QoS level for this task. 124 125#### Example 126``` 127#include <stdio.h> 128#include "qos/qos.h" 129 130int main() 131{ 132 // Set the QoS level of this task to QOS_USER_INITIATED. 133 int ret = OH_QoS_SetThreadQoS(QoS_Level::QOS_USER_INITIATED); 134 135 if (!ret) { // If ret is 0, the operation is successful. 136 printf("set QoS Success."); 137 } else { // If ret is not 0, the operation fails. 138 printf("set QoS failed."); 139 } 140 141 return 0; 142} 143``` 144 145### OH_QoS_ResetThreadQoS 146 147#### Function 148```{.c} 149int OH_QoS_ResetThreadQoS(); 150``` 151 152#### Parameters 153* N/A. 154 155#### Return Value 156* Returns **0** if the operation is successful; returns **-1** otherwise. 157 158#### Description 159Removes the QoS level of this task. 160 161#### Example 162``` 163#include <stdio.h> 164#include "qos/qos.h" 165 166int main() 167{ 168 // Removes the QoS level of this task. 169 int ret = OH_QoS_ResetThreadQoS(); 170 171 if (!ret) { // If ret is 0, the operation is successful. 172 printf("reset QoS Success."); 173 } else { // If ret is not 0, the operation fails. 174 printf("reset QoS failed."); 175 } 176 177 return 0; 178} 179``` 180 181### OH_QoS_GetThreadQoS 182 183#### Function 184```{.c} 185int OH_QoS_GetThreadQoS(QoS_Level *level); 186``` 187 188#### Parameters 189QoS_Level *level 190* QoS level set for a task. 191 192#### Return Value 193* Returns **0** if the operation is successful; returns **-1** otherwise. 194 195#### Description 196Obtains the latest QoS level of this task. If no QoS level is set, **-1** is returned. 197 198#### Example 199``` 200#include <stdio.h> 201#include "qos/qos.h" 202 203int main() 204{ 205 // Obtain the QoS level of this task. 206 QoS_Level level = QoS_Level::QOS_DEFAULT; 207 int ret = OH_QoS_GetThreadQoS(&level); 208 209 if (!ret) { // If ret is 0, the operation is successful. 210 printf("get QoS level %d Success.", level); 211 } else { // If ret is not 0, the operation fails. 212 printf("get QoS level failed."); 213 } 214 215 return 0; 216} 217``` 218 219## How to Develop 220The following walks you through on how to query and modify the QoS level of a task using Node-API interfaces. 221 222**Adding the Dynamic Link Library** 223 224Add the following library to **CMakeLists.txt**. 225```txt 226libqos.so 227``` 228 229#### Example 230```txt 231# the minimum version of CMake. 232cmake_minimum_required(VERSION 3.4.1) 233project(qos) 234 235set(NATIVERENDER_ROOT_PATH ${CMAKE_CURRENT_SOURCE_DIR}) 236 237include_directories(${NATIVERENDER_ROOT_PATH} 238 ${NATIVERENDER_ROOT_PATH}/include) 239 240add_library(entry SHARED hello.cpp) 241target_link_libraries(entry PUBLIC libqos.so) 242``` 243 244**Including the Header File** 245```c 246#include "qos/qos.h" 247``` 248**Calling QoS APIs** 249 250Use **OHQoSSetThreadQoS()** to set the QoS level for a task, use **OHQoSGetThreadQoS()** to obtain the QoS level set, and use **OHQoSResetThreadQoS()** to reset the QoS level to default. 251