From fb7ab436586f79e40670bd7be1f57374124878be Mon Sep 17 00:00:00 2001 From: Zhao-PengFei35 Date: Mon, 5 Sep 2022 14:54:53 +0800 Subject: [PATCH] =?UTF-8?q?=E5=A2=9E=E5=8A=A0=E8=83=BD=E6=95=88=E8=B5=84?= =?UTF-8?q?=E6=BA=90=E7=9A=84api=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Zhao-PengFei35 --- .../apis/js-apis-backgroundTaskManager.md | 84 ++++++++++++++++- .../background-task-dev-guide.md | 89 ++++++++++++++++++- .../background-task-overview.md | 28 +++++- .../work-scheduler-overview.md | 3 +- 4 files changed, 199 insertions(+), 5 deletions(-) diff --git a/zh-cn/application-dev/reference/apis/js-apis-backgroundTaskManager.md b/zh-cn/application-dev/reference/apis/js-apis-backgroundTaskManager.md index 9ca31d90c8..304d3520cc 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-backgroundTaskManager.md +++ b/zh-cn/application-dev/reference/apis/js-apis-backgroundTaskManager.md @@ -8,6 +8,8 @@ 应用中存在用户能够直观感受到的且需要一直在后台运行的业务时（如，后台播放音乐），可以使用长时任务机制。 +应用如果需要申请特定的能效资源，例如在被冻结期间仍然能够收到系统公共事件，可以使用能效资源申请机制。 + > **说明：** > 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 @@ -297,6 +299,57 @@ backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() ``` +## backgroundTaskManager.applyEfficiencyResources+ + +applyEfficiencyResources(request: [EfficiencyResourcesRequest](#efficiencyresourcesrequest9)): boolean + +向系统申请能效资源，使用boolean形式返回结果。 +进程和他所属的应用可以同时申请某一类资源，例如CPU资源，但是应用释放资源的时候会将进程的资源一起释放。 + +**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply + +**参数**： +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------- | ---- | ---------------------------------------- | +| request | [EfficiencyResourcesRequest](#efficiencyresourcesrequest9) | 是 | 申请资源的必要信息。包括类型，时间，进程申请或者是应用申请等信息。详见[EfficiencyResourcesRequest](#efficiencyresourcesrequest9)。 | + +**返回值** +| 类型 | 说明 | +| -------------- | ---------------- | +| boolean | true代表申请成功，false代表申请失败。 | + +**示例**： +```js +import backgroundTaskManager from '@ohos.backgroundTaskManager'; + +let request = { + resourceTypes: backgroundTaskManager.ResourceType.CPU, + isApply: true, + timeOut: 0, + reason: "apply", + isPersist: true, + isProcess: false, +}; +let res = backgroundTaskManager.applyEfficiencyResources(request); +console.info("result of applyEfficiencyResources is: " + res) +``` + +## backgroundTaskManager.resetAllEfficiencyResources9+ + +resetAllEfficiencyResources(): void + +向系统申请释放能效资源, 释放当前应用申请的所有能效资源。 + +**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply + +**示例**： +```js +import backgroundTaskManager from '@ohos.backgroundTaskManager'; + +backgroundTaskManager.backgroundTaskManager.resetAllEfficiencyResources(); + +``` + ## DelaySuspendInfo 延迟挂起信息。 @@ -323,4 +376,33 @@ backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() | MULTI_DEVICE_CONNECTION | 6 | 多设备互联 | | WIFI_INTERACTION | 7 | WLAN相关
此接口为系统接口。 | | VOIP | 8 | 音视频通话
此接口为系统接口。 | -| TASK_KEEPING | 9 | 计算任务（仅在特定设备生效） | \ No newline at end of file +| TASK_KEEPING | 9 | 计算任务（仅在特定设备生效） | + +## EfficiencyResourcesRequest9+ + +能效资源申请。 + +**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply + +| 参数名 | 类型 | 必填 | 说明 | +| --------------- | ------ | ---- | ---------------------------------------- | +| resourceTypes | number | 是 | 申请的资源类型。 | +| isApply | boolean | 是 | 申请资源或者是释放资源。 | +| timeOut | number | 是 | 资源的使用时间，以ms为单位。 | +| isPersist | boolean | 否 | 是否永久持有资源，如果是true，那么timeOut就无效。 | +| isProcess | boolean | 否 | 应用申请或者是进程申请。 | +| reason | string | 是 | 申请资源的原因。 | + +## ResourceType9+ + +**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply + +| 参数名 | 参数值 | 描述 | +| ----------------------- | ---- | --------------------- | +| CPU | 1 | CPU资源，申请后不被冻结 | +| COMMON_EVENT | 2 | 公共事件，申请后冻结状态下不被代理掉 | +| TIMER | 4 | 计时器，申请后冻结状态下不被代理掉 | +| WORK_SCHEDULER | 8 | 延迟任务，申请后有更长的执行时间 | +| BLUETOOTH | 16 | 蓝牙相关，申请后冻结状态下不被代理掉 | +| GPS | 32 | GPS相关，申请后冻结状态下不被代理掉z | +| AUDIO | 64 | 音频资源，申请后冻结状态下不被代理掉 | \ No newline at end of file diff --git a/zh-cn/application-dev/task-management/background-task-dev-guide.md b/zh-cn/application-dev/task-management/background-task-dev-guide.md index 67c1704681..2f61ea2415 100644 --- a/zh-cn/application-dev/task-management/background-task-dev-guide.md +++ b/zh-cn/application-dev/task-management/background-task-dev-guide.md @@ -2,7 +2,7 @@ ## 场景介绍 -应用或业务模块处于后台（无可见界面）时，如果有需要继续执行或者后续执行的业务，可基于业务类型，申请短时任务延迟挂起（Suspend）或者长时任务避免进入挂起状态。 +应用或业务模块处于后台（无可见界面）时，如果有需要继续执行或者后续执行的业务，可基于业务类型，申请短时任务延迟挂起（Suspend）或者长时任务避免进入挂起状态。如果应用在挂起时需要单独的某种资源不被代理或者需要更长的延时任务执行时间，可以申请所需的能效资源。 ## 短时任务 @@ -479,6 +479,93 @@ export default class BgTaskAbility extends Ability { }; ``` +## 能效资源申请 + +### 接口说明 + +**表1** 能效资源申请主要接口 + +| 接口名 | 描述 | +| ---------------------------------------- | ---------------------------------------- | +| applyEfficiencyResources(request: [EfficiencyResourcesRequest](../reference/apis/js-apis-backgroundTaskManager.md#efficiencyresourcesrequest9)): boolean | 申请能效资源。 | +| resetAllEfficiencyResources():void | 释放申请的能效资源 | + + +### 开发步骤 + + +1. 申请能效资源 + +```js +import backgroundTaskManager from '@ohos.backgroundTaskManager'; + +let request = { + resourceTypes: backgroundTaskManager.ResourceType.CPU, + isApply: true, + timeOut: 0, + reason: "apply", + isPersist: true, + isProcess: true, +}; +let res = backgroundTaskManager.applyEfficiencyResources(request); +console.info("the result of request is: " + res); +``` + +2. 释放申请的部分资源 + +```js +import backgroundTaskManager from '@ohos.backgroundTaskManager'; + +let request = { + resourceTypes: backgroundTaskManager.ResourceType.CPU, + isApply: false, + timeOut: 0, + reason: "reset", +}; +let res = backgroundTaskManager.applyEfficiencyResources(request); +console.info("the result of request is: " + res); +``` + +3. 释放申请的所有资源 + +```js +import backgroundTaskManager from '@ohos.backgroundTaskManager'; + +backgroundTaskManager.backgroundTaskManager.resetAllEfficiencyResources(); +``` + +### 开发实例 + +```js +import backgroundTaskManager from '@ohos.backgroundTaskManager'; + +// 申请能效资源 +let request = { + resourceTypes: backgroundTaskManager.ResourceType.COMMON_EVENT | + backgroundTaskManager.ResourceType.TIMER, + isApply: true, + timeOut: 0, + reason: "apply", + isPersist: true, + isProcess: true, +}; +let res = backgroundTaskManager.applyEfficiencyResources(request); +console.info("the result of request is: " + res); + +// 释放部分资源 +request = { + resourceTypes: backgroundTaskManager.ResourceType.COMMON_EVENT, + isApply: false, + timeOut: 0, + reason: "reset", +}; +res = backgroundTaskManager.applyEfficiencyResources(request); +console.info("the result of request is: " + res); + +// 释放全部资源 +backgroundTaskManager.backgroundTaskManager.resetAllEfficiencyResources(); +``` + ## 相关实例 基于后台任务管理，有以下相关实例可供参考： diff --git a/zh-cn/application-dev/task-management/background-task-overview.md b/zh-cn/application-dev/task-management/background-task-overview.md index da236b2c07..3e1d2a1405 100644 --- a/zh-cn/application-dev/task-management/background-task-overview.md +++ b/zh-cn/application-dev/task-management/background-task-overview.md @@ -1,6 +1,6 @@ # 后台任务概述 -后台应用频繁活动，会造成用户设备耗电快、卡顿等现象。因此，为了支撑性能、功耗诉求，系统仅允许应用在后台执行规范内的活动，规范外的活动默认会被挂起，当资源不足时会被回收。 +后台应用频繁活动，会造成用户设备耗电快、卡顿等现象。因此，为了支撑性能、功耗诉求，系统仅允许应用在后台执行规范内的活动，规范外的活动默认会被挂起，当资源不足时会被回收。同时，应用可以申请能效资源，保证自己在一段时间内不会被挂起，或者在被冻结状态能够正常使用一些资源，例如公共事件，计时器等。 ## 后台任务类型 @@ -13,6 +13,8 @@ **3. 长时任务** ：如果是用户发起的可感知业务需要长时间后台运行，如后台播放音乐、导航、设备连接、VoIP等，则使用长时任务避免进入挂起（Suspend）状态。 + **4.能效资源**：如果应用或者进程申请了能效资源，那么更具能效类型的资源会拥有相应的特权，例如申请了CPU资源的可以不被冻结，申请了WORK_SCHEDULER可以在拥有更长的延时任务的超时时间。 + ## 短时任务 @@ -59,4 +61,26 @@ OpenHarmony提供了九种后台模式，供需要在后台做长时任务的业 - 如果任务结束，应用应主动退出后台模式。若在后台运行期间，系统检测到应用并未使用对应后台模式的资源，则会被挂起（Suspend）。 - 避免不合理地申请后台长时任务，长时任务类型要与应用的业务类型匹配。如果执行的任务和申请的类型不匹配，也会被系统检测到并被挂起（Suspend）。 - 长时任务是为了真正在后台长时间执行某个任务，如果一个应用申请了长时任务，但在实际运行过程中，并未真正运行或执行此类任务时，也会被系统检测到并被挂起（Suspend）。 -- 一个Ability同一时刻只能申请运行一个长时任务。 \ No newline at end of file +- 一个Ability同一时刻只能申请运行一个长时任务。 + +## 能效资源申请 +能效资源可以分为四种，CPU资源，WORK_SCHEDULER资源，软件资源(COMMON_EVENT，TIMER)，硬件资源(GPS,BLOOTOOTH)。 +申请了能效资源的应用或者进程能够拥有着相应的特权，例如申请了CPU资源的可以不被冻结，申请了WORK_SCHEDULER资源的可以相应的拥有 +不受延迟任务执行频率约束，有更长的执行时间，申请了软件、硬件资源的可以在冻结状态下不被代理相应的资源。 + + +**表1** 能效资源种类 + +| 参数名 | 参数值 | 描述 | +| ----------------------- | ---- | --------------------- | +| CPU | 1 | CPU资源，申请后不被冻结 | +| COMMON_EVENT | 2 | 公共事件，申请后冻结状态下不被代理掉 | +| TIMER | 4 | 计时器，申请后冻结状态下不被代理掉 | +| WORK_SCHEDULER | 8 | 延迟任务，申请后有更长的执行时间 | +| BLUETOOTH | 16 | 蓝牙相关，申请后冻结状态下不被代理掉 | +| GPS | 32 | GPS相关，申请后冻结状态下不被代理掉 | +| AUDIO | 64 | 音频资源，申请后冻结状态下不被代理掉 | + +### 能效资源使用约束 +- 能效资源申请或者释放可以由进程或者应用发起，由应用发起的释放在释放的时候会释放所有资源，包括进程申请的资源。由进程发起的资源释放对应用申请的资源没有影响。 +- 同时申请同一类持久资源和非持久资源，持久资源会覆盖非持久资源。在超时时不会释放资源。 diff --git a/zh-cn/application-dev/task-management/work-scheduler-overview.md b/zh-cn/application-dev/task-management/work-scheduler-overview.md index e4b8d34943..7895899037 100644 --- a/zh-cn/application-dev/task-management/work-scheduler-overview.md +++ b/zh-cn/application-dev/task-management/work-scheduler-overview.md @@ -10,7 +10,7 @@ 延迟调度任务的使用需要遵从如下约束和规则： -- **超时**：系统会设置超时机制，延迟任务回调只允许运行一段时间，超时之后，系统会主动停止。 +- **超时**：系统会设置超时机制，延迟任务回调只允许运行一段时间，超时之后，系统会主动停止。默认的超时限制为2分钟，如果应用申请了能效资源且手机处于插电状态，那么超时时间设置为20分钟，如果应用申请了能效资源且手机是未插电状态，那么超时时间是10分钟。 - **执行频率**：系统会根据应用的活跃度对延迟任务做分级管控，限制延迟任务调度的执行频率。 应用分组 | 延迟任务执行频率约束 @@ -21,6 +21,7 @@ 不经常使用 | 最小间隔48小时 受限分组 | 禁止 未使用分组 | 禁止 +申请了WORK_SCHEDULER能效资源 | 不受执行频率限制 - **WorkInfo设置参数约束** -- GitLab