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![qosfigure1.png](./figures/qosfigure1.png)
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![qosfigure2.png](./figures/qosfigure2.png)
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