Requesting Efficiency Resources (for Privileged System Applications Only)

Overview

Introduction

Some 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.

Basic Concepts

  • 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.

  • Privileged system application: a system application that is configured with the runningResourcesApply privilege.

Constraints

  • Efficiency resources can be used only by privileged system applications.

  • CPU resources can be requested by process or application. Other resources can be requested only by application.

Available APIs

The table below lists the main APIs used for efficient resources. For details about more APIs and their usage, see Background Task Management.

Table 1 Main APIs for efficiency resources

API Description
applyEfficiencyResources(request:EfficiencyResourcesRequest): void Requests efficiency resources.
resetAllEfficiencyResources():void Releases all efficiency resources.

Table 2 Parameters for requesting efficiency resources

Name Type Mandatory Description
resourceTypes number Yes Type of the resource to request.
isApply boolean Yes Whether the request is used to apply for resources.
- true: The request is used to apply for resources.
- false: The request is used to release resources.
timeOut number Yes Duration for which the resource will be used, in milliseconds.
isPersist boolean No Whether the resource is permanently held. The default value is false.
- true: The resource is permanently held.
- false: The resource is held for a limited period of time.
isProcess boolean No Whether the request is initiated by a process. The default value is false.
- true: The request is initiated by a process.
- false: The request is initiated by an application.
reason string Yes Reason for requesting the resource.

Table 3 Efficiency resource types

Name Value Description
CPU 1 CPU resource. Such type of resource prevents an application from being suspended.
COMMON_EVENT 2 Common event resource. Such type of resource ensures that an application in the suspended state can receive common events.
TIMER 4 Timer resource. Such type of resource ensures that an application in the suspended state can be woken up by system timers.
WORK_SCHEDULER 8 Deferred task resource. Such type of resource provides a loose control policy for an application.
BLUETOOTH 16 Bluetooth resource. Such type of resource ensures that an application in the suspended state can be woken up by Bluetooth-related events.
GPS 32 GPS resource. Such type of resource ensures that an application in the suspended state can be woken up by GPS-related events.
AUDIO 64 Audio resource. Such type of resource prevents an application from being suspended when the application has an audio being played.
RUNNING_LOCK10+ 128 RUNNING_LOCK resource. Such type of resources prevents locks running in the background from being temporarily released when the application is suspended.
SENSOR10+ 256 Sensor resource. Such type of resources prevents sensor callbacks from being intercepted.

How to Develop

  1. Import the module.

    import backgroundTaskManager from '@ohos.resourceschedule.backgroundTaskManager';

  2. Request efficiency resources.

    // The application needs to remain active in the background.
let request: backgroundTaskManager.EfficiencyResourcesRequest = {
  resourceTypes: backgroundTaskManager.ResourceType.CPU, // The resource type is CPU, which prevents the application process from being suspended.
  isApply: true, // The request is used to apply for the resources.
  timeOut: 0, // Timeout interval. Resources are automatically released when the timeout interval expires.
  reason: "apply", // Reason for the request.
  isPersist: true, // The resources are permanently held.
  isProcess: false, // The request is initiated by an application.
};
backgroundTaskManager.applyEfficiencyResources(request);
console.info("Succeeded in invoking applyEfficiencyResources.");

  3. 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.

    // The application releases all the efficiency resources.
backgroundTaskManager.resetAllEfficiencyResources();
// The application releases some efficiency resources.
let request: backgroundTaskManager.EfficiencyResourcesRequest = {
  resourceTypes: backgroundTaskManager.ResourceType.CPU,
  isApply: false, // The request is used to release resources.
  timeOut: 0,
  reason: "apply",
  isPersist: true,
  isProcess: false, // The request is initiated by an application.
};
backgroundTaskManager.applyEfficiencyResources(request);
console.info("Succeeded in invoking applyEfficiencyResources.");

    NOTE

    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.