1# Requesting Efficiency Resources (ArkTS) (for Privileged System Applications Only)
2
3## Overview
4
5### Introduction
6
7Some system applications need to run for an extended period of time to provide basic system functions. For example, to maintain the connection between the system and server, the application that provides the default persistent connection push service must send heartbeat messages to the server at a short interval. To prevent the application process from being suspended, the application can request efficiency resources.
8
9### Basic Concepts
10
11- **APIs for requesting efficiency resources**: APIs used by a system application to request energy resources for its processes. An application or process can request CPU resources to prevent itself from being suspended.
12
13- **Privileged system application**: a system application that is configured with the [runningResourcesApply privilege](../../device-dev/subsystems/subsys-app-privilege-config-guide.md#device-specific-application-privileges).
14
15### Constraints
16
17- Efficiency resources can be used only by privileged system applications.
18
19- CPU resources can be requested by process or application. Other resources can be requested only by application.
20
21## Available APIs
22
23The table below lists the main APIs used for efficient resources. For details about more APIs and their usage, see [Background Task Management](../reference/apis-backgroundtasks-kit/js-apis-resourceschedule-backgroundTaskManager-sys.md).
24
25**Table 1** Main APIs for efficiency resources
26
27| API| Description|
28| -------- | -------- |
29| applyEfficiencyResources(request: EfficiencyResourcesRequest): void | Requests efficiency resources.|
30| resetAllEfficiencyResources(): void | Releases all efficiency resources.|
31
32**Table 2** Parameters for requesting efficiency resources
33| Name| Type| Mandatory| Description|
34| -------- | -------- | -------- | -------- |
35| resourceTypes | number | Yes| Type of the resource to request.|
36| isApply | boolean | Yes| Whether the request is used to apply for resources.<br>- **true**: The request is used to apply for resources.<br>- **false**: The request is used to release resources.|
37| timeOut | number | Yes| Duration for which the resource will be used, in milliseconds.|
38| isPersist | boolean | No| Whether the resource is permanently held. The default value is **false**.<br>- **true**: The resource is permanently held.<br>- **false**: The resource is held for a limited period of time.|
39| isProcess | boolean | No| Whether the request is initiated by a process. The default value is **false**.<br>- **true**: The request is initiated by a process.<br>- **false**: The request is initiated by an application.|
40| reason | string | Yes| Reason for requesting the resource.|
41
42**Table 3** Efficiency resource types
43| Name| Value| Description|
44| -------- | -------- | -------- |
45| CPU | 1 | CPU resource. Such type of resource prevents an application from being suspended.|
46| COMMON_EVENT | 2 | Common event resource. Such type of resource ensures that an application in the suspended state can receive common events.|
47| TIMER | 4 | Timer resource. Such type of resource ensures that an application in the suspended state can be woken up by system timers.|
48| WORK_SCHEDULER | 8 | Deferred task resource. Such type of resource provides a loose control policy for an application.|
49| BLUETOOTH | 16 | Bluetooth resource. Such type of resource ensures that an application in the suspended state can be woken up by Bluetooth-related events.|
50| GPS | 32 | GPS resource. Such type of resource ensures that an application in the suspended state can be woken up by GPS-related events.|
51| AUDIO | 64 | Audio resource. Such type of resource prevents an application from being suspended when the application has an audio being played.|
52| RUNNING_LOCK<sup>10+</sup> | 128 | RUNNING_LOCK resource. Such type of resources prevents locks running in the background from being temporarily released when the application is suspended.|
53| SENSOR<sup>10+</sup> | 256 | Sensor resource. Such type of resources prevents sensor callbacks from being intercepted.|
54
55## How to Develop
56
571. Import the module.
58
59   ```ts
60   import { backgroundTaskManager } from '@kit.BackgroundTasksKit';
61   ```
62
632. Request efficiency resources.
64
65   ```ts
66   // The application needs to remain active in the background.
67   let request: backgroundTaskManager.EfficiencyResourcesRequest = {
68     resourceTypes: backgroundTaskManager.ResourceType.CPU, // The resource type is CPU, which prevents the application process from being suspended.
69     isApply: true, // The request is used to apply for the resources.
70     timeOut: 0, // Timeout interval. Resources are automatically released when the timeout interval expires.
71     reason: "apply", // Reason for the request.
72     isPersist: true, // The resources are permanently held.
73     isProcess: false, // The request is initiated by an application.
74   };
75   backgroundTaskManager.applyEfficiencyResources(request);
76   console.info("Succeeded in invoking applyEfficiencyResources.");
77   ```
78
793. Release the efficiency resources. After completing work in the background, the application should release the resources in a timer manner. It can release some or all resources.
80
81   ```ts
82   // The application releases all the efficiency resources.
83   backgroundTaskManager.resetAllEfficiencyResources();
84   // The application releases some efficiency resources.
85   let request: backgroundTaskManager.EfficiencyResourcesRequest = {
86     resourceTypes: backgroundTaskManager.ResourceType.CPU,
87     isApply: false, // The request is used to release resources.
88     timeOut: 0,
89     reason: "apply",
90     isPersist: true,
91     isProcess: false, // The request is initiated by an application.
92   };
93   backgroundTaskManager.applyEfficiencyResources(request);
94   console.info("Succeeded in invoking applyEfficiencyResources.");
95   ```
96
97   > **NOTE**
98   > Applications can dynamically request efficiency resources. Therefore, it is recommended that the application proactively releases the resources after the task is complete so as to reduce power consumption and ensure smooth user experience.
99