@ohos.resourceschedule.backgroundProcessManager (Background Child Process Management)

The backgroundProcessManager module provides APIs for background child process management. You can use these APIs to suppress and unsuppress child processes to prevent child processes from occupying too many system resources and causing system stuttering. The APIs take effect only for the child processes created through OH_Ability_StartNativeChildProcess.

NOTE

The initial APIs of this module are supported since API version 17. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import { backgroundProcessManager } from '@kit.BackgroundTasksKit';

backgroundProcessManager.setProcessPriority

setProcessPriority(pid: number, priority: ProcessPriority): Promise<void>

Sets the child process priority. After a child process is suppressed, the CPU resources that can be obtained will be limited. If the scheduling policy of the main process changes, for example, from the background to the foreground, the child process changes with the main process. To suppress the child process, call this API again.

System capability: SystemCapability.Resourceschedule.BackgroundProcessManager

Parameters

Name	Type	Mandatory	Description
pid	number	Yes	ID of the child process to be suppressed, which is the pid parameter after the child process is created through the OH_Ability_StartNativeChildProcess API.
priority	ProcessPriority	Yes	Suppression priority.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
401	Parameter error. Possible causes: priority is out of range.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { backgroundProcessManager } from '@kit.BackgroundTasksKit';

let childProcessPid = 33333;
try {
    backgroundProcessManager.setProcessPriority(childProcessPid,
        backgroundProcessManager.ProcessPriority.PROCESS_INACTIVE);
} catch (error) {
    console.error(`setProcessPriority failed, errCode: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

backgroundProcessManager.resetProcessPriority

resetProcessPriority(pid: number): Promise<void>

Unsuppresses the child process. In this case, the child process follows the scheduling policy of the main process. If the scheduling policy of the main process changes, for example, from the background to the foreground, the child process changes with the main process. The effect is the same as calling resetProcessPriority.

System capability: SystemCapability.Resourceschedule.BackgroundProcessManager

Parameters

Name	Type	Mandatory	Description
pid	number	Yes	ID of the child process, which is the pid parameter of the OH_Ability_StartNativeChildProcess API.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { backgroundProcessManager } from '@kit.BackgroundTasksKit';

let childProcessPid = 33333;
try {
    backgroundProcessManager.resetProcessPriority(childProcessPid); 
} catch (error) {
    console.error(`setProcessPriority failed, errCode: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

backgroundProcessManager.setPowerSaveMode²⁰⁺

setPowerSaveMode(pid: number, powerSaveMode: PowerSaveMode): Promise<void>

Sets the power saving mode for a process. This API uses a promise to return the result.

You can set to enter the power saving mode when:

• The application is not focused, and there are no audio operations or UI updates.
• The application cannot obtain the power lock through the system framework.
• The application needs to perform time-consuming computing tasks, such as compression, decompression, and compilation, which are significantly restricted by CPU resources. (In this case, the power saving mode will be enabled forcibly.)

Device behavior differences: This API can be properly called on PCs/2-in-1 devices. If it is called on other devices, error code 801 is returned.

Required permissions: ohos.permission.BACKGROUND_MANAGER_POWER_SAVE_MODE

System capability: SystemCapability.Resourceschedule.BackgroundProcessManager

Parameters

Name	Type	Mandatory	Description
pid	number	Yes	Process ID.
powerSaveMode	PowerSaveMode	Yes	Power saving mode.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see backgroundProcessManager Error Codes and Universal Error Codes.

ID	Error Message
201	Permission denied.
801	Capability not supported.
31800002	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. PowerSaveMode status is out of range.
31800003	Setup error, this setting is overridden by settings in Task Manager.
31800004	The setting failed due to system scheduling reasons.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { backgroundProcessManager } from '@kit.BackgroundTasksKit';

let pid = 33333;
try {
    backgroundProcessManager.setPowerSaveMode(pid, backgroundProcessManager.PowerSaveMode.EFFICIENCY_MODE); 
} catch (error) {
    console.error(`setPowerSaveMode failed, errCode: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

backgroundProcessManager.isPowerSaveMode²⁰⁺

isPowerSaveMode(pid: number): Promise<boolean>

Queries whether the process is in power saving mode. This API uses a promise to return the result.

Device behavior differences: This API can be properly called on PCs/2-in-1 devices. If it is called on other devices, error code 801 is returned.

Required permissions: ohos.permission.BACKGROUND_MANAGER_POWER_SAVE_MODE

System capability: SystemCapability.Resourceschedule.BackgroundProcessManager

Parameters

Name	Type	Mandatory	Description
pid	number	Yes	Process ID.

Return value

Type	Description
Promise<boolean>	Promise used to return the query result. The value true means that the process is in power saving mode; the value false means the opposite.

Error codes

For details about the error codes, see backgroundProcessManager Error Codes and Universal Error Codes.

ID	Error Message
201	Permission denied.
801	Capability not supported.
31800002	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { backgroundProcessManager } from '@kit.BackgroundTasksKit';

let pid = 33333;
try {
    backgroundProcessManager.isPowerSaveMode(pid).then((result: boolean) => {
        console.info("isPowerSaveMode: " + result.toString());
    });
} catch (error) {
    console.error(`isPowerSaveMode failed, errCode: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

backgroundProcessManager.getPowerSaveMode²³⁺

getPowerSaveMode(pid: number): Promise<PowerSaveMode>

Obtains the power saving mode of a process. This API uses a promise to return the result.

Device behavior differences: This API can be properly called on PCs/2-in-1 devices. If it is called on other devices, error code 801 is returned.

Required permissions: ohos.permission.BACKGROUND_MANAGER_POWER_SAVE_MODE

System capability: SystemCapability.Resourceschedule.BackgroundProcessManager

Parameters

Name	Type	Mandatory	Description
pid	number	Yes	Process ID. Value range: any integer greater than 0.

Return value

Type	Description
Promise<PowerSaveMode>	Promise that returns the power saving mode of a process.

Error codes

For details about the error codes, see backgroundProcessManager Error Codes and Universal Error Codes.

ID	Error Message
201	Permission denied.
801	Capability not supported.
31800002	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { backgroundProcessManager } from '@kit.BackgroundTasksKit';
// Replace the process ID with the actual one.
let pid = 33333;
try {
    backgroundProcessManager.getPowerSaveMode(pid).then((result: backgroundProcessManager.PowerSaveMode) => {
        console.info("getPowerSaveMode: " + result.toString());
    });
} catch (error) {
    console.error(`getPowerSaveMode failed, errCode: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
}

ProcessPriority

Specifies the child process priority.

System capability: SystemCapability.Resourceschedule.BackgroundProcessManager

Name	Value	Description
PROCESS_BACKGROUND	1	Compared with PROCESS_INACTIVE, PROCESS_LOWER has a more significant suppression effect and obtains fewer CPU resources. You are advised to set this priority when executing background child processes that cannot be perceived by users, such as background image-text pages.
PROCESS_INACTIVE	2	You are advised to set this priority when executing background child processes that can be perceived by users, such as audio playback and navigation.

PowerSaveMode²⁰⁺

Specifies the power saving mode.

System capability: SystemCapability.Resourceschedule.BackgroundProcessManager

Name	Value	Description
EFFICIENCY_MODE	1	Efficiency mode. Applications set to this mode will not enter the power saving mode, where fewer CPU resources are available.
DEFAULT_MODE	2	Default mode. Applications set to this mode may follow the system to enter the power saving mode.