From 93e275ac76dbebdb96013570ac883eeae46f103a Mon Sep 17 00:00:00 2001 From: Zhao-PengFei35 Date: Wed, 7 Sep 2022 12:57:25 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E6=94=B9EfficiencyResourcesApply?= =?UTF-8?q?=E7=9A=84api=E6=96=87=E6=A1=A3?= 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 | 31 ++++++++++++------- .../background-task-dev-guide.md | 4 ++- .../background-task-overview.md | 26 ++++++++-------- .../work-scheduler-overview.md | 6 ++-- 4 files changed, 38 insertions(+), 29 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 304d3520cc..d3657676da 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-backgroundTaskManager.md +++ b/zh-cn/application-dev/reference/apis/js-apis-backgroundTaskManager.md @@ -8,7 +8,7 @@ 应用中存在用户能够直观感受到的且需要一直在后台运行的业务时（如，后台播放音乐），可以使用长时任务机制。 -应用如果需要申请特定的能效资源，例如在被冻结期间仍然能够收到系统公共事件，可以使用能效资源申请机制。 +对于系统特权应用，提供独立的能效资源申请接口。系统特权应用如果需要使用特定的系统资源，例如在被挂起期间仍然能够收到系统公共事件，可以使用能效资源申请接口。 > **说明：** > 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 @@ -299,19 +299,21 @@ backgroundTaskManager.stopBackgroundRunning(featureAbility.getContext()).then(() ``` -## backgroundTaskManager.applyEfficiencyResources+ +## backgroundTaskManager.applyEfficiencyResources9+ applyEfficiencyResources(request: [EfficiencyResourcesRequest](#efficiencyresourcesrequest9)): boolean 向系统申请能效资源，使用boolean形式返回结果。 进程和他所属的应用可以同时申请某一类资源，例如CPU资源，但是应用释放资源的时候会将进程的资源一起释放。 -**系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply +**系统能力**: SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply +**系统API**: 此接口为系统接口。 **参数**： + | 参数名 | 类型 | 必填 | 说明 | | ------- | ------- | ---- | ---------------------------------------- | -| request | [EfficiencyResourcesRequest](#efficiencyresourcesrequest9) | 是 | 申请资源的必要信息。包括类型，时间，进程申请或者是应用申请等信息。详见[EfficiencyResourcesRequest](#efficiencyresourcesrequest9)。 | +| request | [EfficiencyResourcesRequest](#efficiencyresourcesrequest9) | 是 | 请求的必要信息。包括资源类型，超时时间等信息。详见[EfficiencyResourcesRequest](#efficiencyresourcesrequest9)。 | **返回值** | 类型 | 说明 | @@ -319,6 +321,7 @@ applyEfficiencyResources(request: [EfficiencyResourcesRequest](#efficiencyresour | boolean | true代表申请成功，false代表申请失败。 | **示例**： + ```js import backgroundTaskManager from '@ohos.backgroundTaskManager'; @@ -338,11 +341,13 @@ console.info("result of applyEfficiencyResources is: " + res) resetAllEfficiencyResources(): void -向系统申请释放能效资源, 释放当前应用申请的所有能效资源。 +释放所有已经申请的资源。 **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply +**系统API**: 此接口为系统接口。 **示例**： + ```js import backgroundTaskManager from '@ohos.backgroundTaskManager'; @@ -380,7 +385,7 @@ backgroundTaskManager.backgroundTaskManager.resetAllEfficiencyResources(); ## EfficiencyResourcesRequest9+ -能效资源申请。 +能效资源申请参数。 **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply @@ -395,14 +400,16 @@ backgroundTaskManager.backgroundTaskManager.resetAllEfficiencyResources(); ## ResourceType9+ +能效资源类型。 + **系统能力:** SystemCapability.ResourceSchedule.BackgroundTaskManager.EfficiencyResourcesApply | 参数名 | 参数值 | 描述 | | ----------------------- | ---- | --------------------- | -| CPU | 1 | CPU资源，申请后不被冻结 | -| COMMON_EVENT | 2 | 公共事件，申请后冻结状态下不被代理掉 | -| TIMER | 4 | 计时器，申请后冻结状态下不被代理掉 | +| 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 +| 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 2f61ea2415..aea43c4a66 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,9 @@ ## 场景介绍 -应用或业务模块处于后台（无可见界面）时，如果有需要继续执行或者后续执行的业务，可基于业务类型，申请短时任务延迟挂起（Suspend）或者长时任务避免进入挂起状态。如果应用在挂起时需要单独的某种资源不被代理或者需要更长的延时任务执行时间，可以申请所需的能效资源。 +应用或业务模块处于后台（无可见界面）时，如果有需要继续执行或者后续执行的业务，可基于业务类型，申请短时任务延迟挂起（Suspend）或者长时任务避免进入挂起状态。如果应用需要更加灵活的配置，可以申请能效资源。常见的使用能效资源的场景有：1.应用保证自己在一个时间段内不被挂起，直到任务完成；2.应用处于挂起状态时仍然需要系统的资源，例如闹钟需要计时器资源；3.延时任务需要不受到执行频率的限制，并且拥有更长的执行时间。 + +在挂起时需要单独的某种资源不被代理或者需要更长的延时任务执行时间，可以申请所需的能效资源。 ## 短时任务 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 3e1d2a1405..dbab0d037d 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,7 +13,7 @@ **3. 长时任务** ：如果是用户发起的可感知业务需要长时间后台运行，如后台播放音乐、导航、设备连接、VoIP等，则使用长时任务避免进入挂起（Suspend）状态。 - **4.能效资源**：如果应用或者进程申请了能效资源，那么更具能效类型的资源会拥有相应的特权，例如申请了CPU资源的可以不被冻结，申请了WORK_SCHEDULER可以在拥有更长的延时任务的超时时间。 + **4. 能效资源** ：能效资源包括CPU资源，WORK_SCHEDULER资源，软件资源(COMMON_EVENT, TIMER)，硬件资源(GPS, BLUETOOTH)。如果应用或者进程申请了能效资源，那么根据能效类型的资源会拥有相应的特权，例如申请了CPU资源的可以不被挂起，申请了WORK_SCHEDULER后延时任务可以拥有更长的执行时间。 ## 短时任务 @@ -64,23 +64,23 @@ OpenHarmony提供了九种后台模式，供需要在后台做长时任务的业 - 一个Ability同一时刻只能申请运行一个长时任务。 ## 能效资源申请 -能效资源可以分为四种，CPU资源，WORK_SCHEDULER资源，软件资源(COMMON_EVENT，TIMER)，硬件资源(GPS,BLOOTOOTH)。 -申请了能效资源的应用或者进程能够拥有着相应的特权，例如申请了CPU资源的可以不被冻结，申请了WORK_SCHEDULER资源的可以相应的拥有 -不受延迟任务执行频率约束，有更长的执行时间，申请了软件、硬件资源的可以在冻结状态下不被代理相应的资源。 +能效资源可以分为四种，CPU资源，WORK_SCHEDULER资源，软件资源(COMMON_EVENT，TIMER)，硬件资源(GPS,BLOOTOOTH,AUDIO)。 +应用或进程申请能效资源后能够获得相应特权，例如：申请CPU资源后可以不被挂起；申请WORK_SCHEDULER资源后不受延迟任务执行频率约束，且任务执行时间增加；申请软件、硬件资源后，相关资源在挂起状态下不被代理。 **表1** 能效资源种类 | 参数名 | 参数值 | 描述 | | ----------------------- | ---- | --------------------- | -| CPU | 1 | CPU资源，申请后不被冻结 | -| COMMON_EVENT | 2 | 公共事件，申请后冻结状态下不被代理掉 | -| TIMER | 4 | 计时器，申请后冻结状态下不被代理掉 | +| CPU | 1 | CPU资源，申请后不被挂起 | +| COMMON_EVENT | 2 | 公共事件，申请后挂起状态下不被代理掉 | +| TIMER | 4 | 计时器，申请后挂起状态下不被代理掉 | | WORK_SCHEDULER | 8 | 延迟任务，申请后有更长的执行时间 | -| BLUETOOTH | 16 | 蓝牙相关，申请后冻结状态下不被代理掉 | -| GPS | 32 | GPS相关，申请后冻结状态下不被代理掉 | -| AUDIO | 64 | 音频资源，申请后冻结状态下不被代理掉 | +| BLUETOOTH | 16 | 蓝牙相关，申请后挂起状态下不被代理掉 | +| GPS | 32 | GPS相关，申请后挂起状态下不被代理掉 | +| AUDIO | 64 | 音频资源，申请后挂起状态下不被代理掉 | ### 能效资源使用约束 -- 能效资源申请或者释放可以由进程或者应用发起，由应用发起的释放在释放的时候会释放所有资源，包括进程申请的资源。由进程发起的资源释放对应用申请的资源没有影响。 -- 同时申请同一类持久资源和非持久资源，持久资源会覆盖非持久资源。在超时时不会释放资源。 +- 能效资源申请或者释放可以由进程或者应用发起，由应用发起的资源释放在释放的时候会释放属于他的同类型的所有资源，包括进程申请的资源。例如应用申请了CPU资源,进程申请了CPU和WORK_SCHEDULER资源，当应用释放CPU资源的时候，会将进程的CPU资源一同释放，同时不同类型的WORK_SCHEDULER资源不受影响。由进程发起的资源释放对应用申请的资源没有影响，例如当应用和进程同时申请了CPU，进程发起了CPU资源释放，应用的CPU资源不会被释放。 +- 同时申请同一类持久资源和非持久资源，持久资源会覆盖非持久资源，在超时时不会释放资源。例如应用首先申请了10s的CPU资源，然后在第5s的时候申请了持久的CPU资源，那么资源会变成持久的，非持久的CPU资源记录会被持久化的CPU资源记录覆盖，到了第10s的时候资源不会被释放，如果在第8s的时候提前释放了资源，那么会将CPU资源释放，无法单独释放其中非持久的或者持久的CPU资源。 +- WORK_SCHEDULER资源只能由应用进行申请和释放，不能由进程申请和释放。 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 7895899037..75b3b8492f 100644 --- a/zh-cn/application-dev/task-management/work-scheduler-overview.md +++ b/zh-cn/application-dev/task-management/work-scheduler-overview.md @@ -10,8 +10,8 @@ 延迟调度任务的使用需要遵从如下约束和规则： -- **超时**：系统会设置超时机制，延迟任务回调只允许运行一段时间，超时之后，系统会主动停止。默认的超时限制为2分钟，如果应用申请了能效资源且手机处于插电状态，那么超时时间设置为20分钟，如果应用申请了能效资源且手机是未插电状态，那么超时时间是10分钟。 -- **执行频率**：系统会根据应用的活跃度对延迟任务做分级管控，限制延迟任务调度的执行频率。 +- **超时**：系统会设置超时机制，延迟任务回调只允许运行一段时间，超时之后，系统会主动停止。默认的超时限制为2分钟，对于系统应用，可以通过[能效资源申请接口](background-task-overview.md#能效资源申请)获取更长的执行时间（充电状态20分钟，非充电状态10分钟）。 +- **执行频率**：系统会根据应用的活跃度对延迟任务做分级管控，限制延迟任务调度的执行频率。对于通过能效资源接口申请了WORK_SCHEDULER资源的应用，在资源的有效期内，他的延迟任务执行频率不受限制。 应用分组 | 延迟任务执行频率约束 --------------------|------------------------- @@ -21,7 +21,7 @@ 不经常使用 | 最小间隔48小时 受限分组 | 禁止 未使用分组 | 禁止 -申请了WORK_SCHEDULER能效资源 | 不受执行频率限制 +[能效资源豁免分组](../reference/apis/js-apis-backgroundTaskManager.md#resourcetype9) | 执行频率不受限制 - **WorkInfo设置参数约束** -- GitLab