1# @ohos.resourceschedule.backgroundProcessManager (后台子进程管控) 2 3<!--Kit: Background Tasks Kit--> 4<!--Subsystem: Resourceschedule--> 5<!--Owner: @hongjianfeng--> 6<!--Designer: @zhouben25--> 7<!--Tester: @fenglili18--> 8<!--Adviser: @Brilliantry_Rui--> 9 10本模块提供了后台子进程管控接口。开发者可以通过本模块接口对子进程进行压制、解压制，避免子进程过多占用系统资源，导致系统使用卡顿。本模块接口仅对通过[OH_Ability_StartNativeChildProcess](../apis-ability-kit/capi-native-child-process-h.md#oh_ability_startnativechildprocess)接口创建的子进程生效。 11 12> **说明：** 13> 14> 本模块首批接口从API version 17开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 15 16## 导入模块 17 18```ts 19import { backgroundProcessManager } from '@kit.BackgroundTasksKit'; 20``` 21 22## backgroundProcessManager.setProcessPriority 23 24setProcessPriority(pid: number, priority: ProcessPriority): Promise<void> 25 26设置子进程的压制档位，子进程被压制后可获得的CPU资源将会受到限制。如果主进程调度策略发生变化，如从后台切至前台等，子进程会跟随主进程一同变化，子进程如需继续压制，需要重新调用本接口。 27 28**系统能力**： SystemCapability.Resourceschedule.BackgroundProcessManager 29 30**参数**： 31 32| 参数名 | 类型 | 必填 | 说明 | 33|----------|-------------------------------------| ---- |-------------------------------------------------------------------------------------------------------------------------------| 34| pid | number | 是 | 需要被压制子进程的进程号，[OH_Ability_StartNativeChildProcess](../apis-ability-kit/capi-native-child-process-h.md#oh_ability_startnativechildprocess)接口创建子进程后的pid参数，即为子进程进程号。 | 35| priority | [ProcessPriority](#processpriority) | 是 | 压制档位。 | 36 37**返回值**： 38 39| 类型 | 说明 | 40| -------------- | ---------------- | 41| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 42 43**错误码**： 44 45以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 46 47| 错误码ID | 错误信息 | 48|----------|------------------| 49| 401 | Parameter error. Possible causes: priority is out of range. | 50 51**示例**： 52 53```ts 54import { BusinessError } from '@kit.BasicServicesKit'; 55import { backgroundProcessManager } from '@kit.BackgroundTasksKit'; 56 57let childProcessPid = 33333; 58try { 59 backgroundProcessManager.setProcessPriority(childProcessPid, 60 backgroundProcessManager.ProcessPriority.PROCESS_INACTIVE); 61} catch (error) { 62 console.error(`setProcessPriority failed, errCode: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 63} 64``` 65 66## backgroundProcessManager.resetProcessPriority 67 68resetProcessPriority(pid: number): Promise<void> 69 70为子进程解压制，即子进程策略恢复为主进程调度策略。若主进程调度策略发生变化，如从后台切至前台等， 子进程会跟随主进程一同变化，等效于执行一次resetProcessPriority动作。 71 72**系统能力**： SystemCapability.Resourceschedule.BackgroundProcessManager 73 74**参数**： 75 76| 参数名 | 类型 | 必填 | 说明 | 77|----------|--------------------| ---- |---------------------------------------------------------------------------------------------------------------------------| 78| pid | number | 是 | 子进程的进程号，[OH_Ability_StartNativeChildProcess](../apis-ability-kit/capi-native-child-process-h.md#oh_ability_startnativechildprocess)接口创建子进程后的pid参数，即为子进程进程号。 | 79 80**返回值**： 81 82| 类型 | 说明 | 83| -------------- | ---------------- | 84| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 85 86**示例**： 87 88```ts 89import { BusinessError } from '@kit.BasicServicesKit'; 90import { backgroundProcessManager } from '@kit.BackgroundTasksKit'; 91 92let childProcessPid = 33333; 93try { 94 backgroundProcessManager.resetProcessPriority(childProcessPid); 95} catch (error) { 96 console.error(`setProcessPriority failed, errCode: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 97} 98``` 99 100## backgroundProcessManager.setPowerSaveMode<sup>20+</sup> 101 102setPowerSaveMode(pid: number, powerSaveMode: PowerSaveMode): Promise<void> 103 104设置进程的能效模式，使用Promise异步回调。 105 106当应用满足以下条件时，可以设置自身是否进入能效模式： 107- 应用未获取系统焦点，未执行音频或界面刷新操作。 108- 无法通过框架层获取电源锁。 109- 应用需要执行压缩、解压缩、编译等耗时较长的计算任务，不希望这些任务受到显著的CPU资源限制（即被迫进入能效模式）。 110 111**设备行为差异**：该接口在PC/2in1中可正常调用，在其他设备类型中返回801错误码。 112 113**需要权限**： ohos.permission.BACKGROUND_MANAGER_POWER_SAVE_MODE 114 115**系统能力**： SystemCapability.Resourceschedule.BackgroundProcessManager 116 117**参数**： 118 119| 参数名 | 类型 | 必填 | 说明 | 120|-------------|-----------|-----------|-----------| 121| pid | number | 是 | 进程号。 | 122| powerSaveMode | [PowerSaveMode](#powersavemode20) | 是 | 能效模式。 | 123 124**返回值**： 125 126| 类型 | 说明 | 127| -------------- | ---------------- | 128| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 129 130**错误码**： 131 132以下错误码的详细介绍请参见[backgroundProcessManager错误码](errorcode-backgroundProcessManager.md)和[通用错误码](../errorcode-universal.md)。 133 134| 错误码ID | 错误信息 | 135|----------|------------------| 136| 201 | Permission denied. | 137| 801 | Capability not supported. | 138| 31800002 | Parameter error. Possible causes: <br> 1. Mandatory parameters are left unspecified; <br> 2. Incorrect parameter types; 3. PowerSaveMode status is out of range. | 139| 31800003 | Setup error, This setting is overridden by setting in Task Manager. | 140| 31800004 | The setting failed due to system scheduling reasons. | 141 142**示例**： 143 144```ts 145import { BusinessError } from '@kit.BasicServicesKit'; 146import { backgroundProcessManager } from '@kit.BackgroundTasksKit'; 147 148let pid = 33333; 149try { 150 backgroundProcessManager.setPowerSaveMode(pid, backgroundProcessManager.PowerSaveMode.EFFICIENCY_MODE); 151} catch (error) { 152 console.error(`setPowerSaveMode failed, errCode: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 153} 154``` 155 156## backgroundProcessManager.isPowerSaveMode<sup>20+</sup> 157 158isPowerSaveMode(pid: number): Promise<boolean> 159 160查询进程是否处于能效模式，使用Promise异步回调。 161 162**设备行为差异**：该接口在PC/2in1中可正常调用，在其他设备类型中返回801错误码。 163 164**需要权限**： ohos.permission.BACKGROUND_MANAGER_POWER_SAVE_MODE 165 166**系统能力**： SystemCapability.Resourceschedule.BackgroundProcessManager 167 168**参数**： 169 170| 参数名 | 类型 | 必填 | 说明 | 171|-------------|-----------|-----------|-----------| 172| pid | number | 是 | 进程号。 | 173 174**返回值**： 175 176| 类型 | 说明 | 177| -------------- | ---------------- | 178| Promise\<boolean> | Promise对象。返回进程PID是否处于能效模式，返回true表示进程处于能效模式，返回false表示进程未处于能效模式。 | 179 180**错误码**： 181 182以下错误码的详细介绍请参见[backgroundProcessManager错误码](errorcode-backgroundProcessManager.md)和[通用错误码](../errorcode-universal.md)。 183 184| 错误码ID | 错误信息 | 185|----------|------------------| 186| 201 | Permission denied. | 187| 801 | Capability not supported. | 188| 31800002 | Parameter error. Possible causes: <br> 1. Mandatory parameters are left unspecified; <br> 2. Incorrect parameter types. | 189 190**示例**： 191 192```ts 193import { BusinessError } from '@kit.BasicServicesKit'; 194import { backgroundProcessManager } from '@kit.BackgroundTasksKit'; 195 196let pid = 33333; 197try { 198 backgroundProcessManager.isPowerSaveMode(pid).then((result: boolean) => { 199 console.info("isPowerSaveMode: " + result.toString()); 200 }); 201} catch (error) { 202 console.error(`isPowerSaveMode failed, errCode: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 203} 204``` 205 206## ProcessPriority 207 208子进程压制档位。 209 210**系统能力**： SystemCapability.Resourceschedule.BackgroundProcessManager 211 212| 名称 | 值 | 说明 | 213|----------------------| -------- |--------------------------------------------------------------------------------| 214| PROCESS_BACKGROUND | 1 | 该档位相较PROCESS_INACTIVE压制效果更显著，获取到的CPU资源更少。推荐执行处于后台的图文页面等用户无感知业务的后台子进程时设置该档位。 | 215| PROCESS_INACTIVE | 2 | 推荐正在执行播放音频、导航等用户可感知业务的后台子进程时设置该档位。 | 216 217## PowerSaveMode<sup>20+</sup> 218 219能效模式。 220 221**系统能力**： SystemCapability.Resourceschedule.BackgroundProcessManager 222 223| 名称 | 值 | 说明 | 224|-----|----|-------| 225| EFFICIENCY_MODE | 1 | 效率模式，不会跟随系统进入能效模式，进入能效模式后获取到的CPU资源更少。 | 226| DEFAULT_MODE | 2 | 跟随系统，可能会进入能效模式。 | 227 228