目录

@ohos.app.ability.childProcessManager (子进程管理)

childProcessManager模块提供子进程管理能力,支持子进程创建和启动操作。

创建的子进程会随着父进程的退出而退出,无法脱离父进程独立运行。

本模块首批接口从API version 11开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

本模块接口仅可在Stage模型下使用。

约束限制

[h2]功能限制

[h2]规格限制

导入模块

import { childProcessManager } from '@kit.AbilityKit';

StartMode

子进程启动模式枚举。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

名称 值 说明
SELF_FORK 0 从App自身进程Fork子进程。以该模式启动的子进程会继承父进程资源,不能使用Binder IPC和其他进程通信,否则会导致子进程崩溃退出。
APP_SPAWN_FORK 1 从AppSpawn Fork子进程。以该模式启动的子进程不会继承父进程资源,可以使用Binder IPC和其他进程通信。

ChildProcessInformation

type ChildProcessInformation = _ChildProcessInformation

定义子进程信息。

起始版本: 26.0.1

模型约束: 此接口仅可在Stage模型下使用。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

类型 说明
_ChildProcessInformation 定义子进程信息,包含子进程的PID、所属父进程的PID、子进程的进程名。

childProcessManager.startChildProcess

startChildProcess(srcEntry: string, startMode: StartMode): Promise<number>

启动ArkTS子进程。使用Promise异步回调。

调用该接口创建子进程成功会返回子进程pid,然后执行子进程的ChildProcess.onStart函数,ChildProcess.onStart函数执行完后子进程会自动销毁。

调用该接口创建的子进程不支持异步ArkTS API调用,仅支持同步ArkTS API调用。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

设备行为差异:该接口在Tablet、PC/2in1中可正常调用,在其他设备类型中返回16000061错误码。

参数:

参数名 类型 必填 说明
srcEntry string 是

子进程源文件路径,只支持源文件放在entry类型的模块中,以src/main为根目录。例如子进程文件在entry模块下src/main/ets/process/DemoProcess.ets,则srcEntry为"./ets/process/DemoProcess.ets"。

另外,需要确保子进程源文件被其它文件引用到,防止被构建工具优化掉。(详见下方示例代码)

startMode StartMode 是 子进程启动模式。SELF_FORK(值为0):从App自身进程Fork子进程,继承父进程资源,不能使用Binder IPC和其他进程通信,否则会导致子进程崩溃退出;APP_SPAWN_FORK(值为1):从AppSpawn Fork子进程,不继承父进程资源,可使用Binder IPC和其他进程通信。

返回值:

类型 说明
Promise<number> Promise对象,返回子进程pid。

错误码:

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16000050 Internal error.
16000061 Operation not supported.
16000062 The number of child processes exceeds the upper limit.

示例:

// 在entry模块的src/main/ets/process下创建DemoProcess.ets子进程类:
// entry/src/main/ets/process/DemoProcess.ets
import { ChildProcess } from '@kit.AbilityKit';

export default class DemoProcess extends ChildProcess {
  onStart() {
    console.info('DemoProcess OnStart() called');
  }
}
// 使用childProcessManager.startChildProcess方法启动子进程:
// entry/src/main/ets/tool/Tool.ets
import { childProcessManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import DemoProcess from '../process/DemoProcess';

try {
  DemoProcess.toString(); // 这里要调用下DemoProcess类的任意方法,防止没有引用到而被构建工具优化掉
  childProcessManager.startChildProcess("./ets/process/DemoProcess.ets", childProcessManager.StartMode.SELF_FORK)
    .then((data) => {
      console.info(`startChildProcess success, pid: ${data}`);
    }, (err: BusinessError) => {
      console.error(`startChildProcess error, errorCode: ${err.code}`);
    })
} catch (err) {
  console.error(`startChildProcess error, errorCode: ${(err as BusinessError).code}, errorMsg: ${(err as BusinessError).message}.`);
}

childProcessManager.startChildProcess

startChildProcess(srcEntry: string, startMode: StartMode, callback: AsyncCallback<number>): void

启动ArkTS子进程。使用callback异步回调。

调用该接口创建子进程成功会返回子进程pid,然后执行子进程的ChildProcess.onStart函数,ChildProcess.onStart函数执行完后子进程会自动销毁。

调用该接口创建的子进程不支持异步ArkTS API调用,仅支持同步ArkTS API调用。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

设备行为差异:该接口在Tablet、PC/2in1中可正常调用,在其他设备类型中返回16000061错误码。

参数:

参数名 类型 必填 说明
srcEntry string 是

子进程源文件路径,只支持源文件放在entry类型的模块中,以src/main为根目录。例如子进程文件在entry模块下src/main/ets/process/DemoProcess.ets,则srcEntry为"./ets/process/DemoProcess.ets"。

另外,需要确保子进程源文件被其它文件引用到,防止被构建工具优化掉。(详见下方示例代码)

startMode StartMode 是 子进程启动模式。SELF_FORK(值为0):从App自身进程Fork子进程,继承父进程资源,不能使用Binder IPC和其他进程通信,否则会导致子进程崩溃退出;APP_SPAWN_FORK(值为1):从AppSpawn Fork子进程,不继承父进程资源,可使用Binder IPC和其他进程通信。
callback AsyncCallback<number> 是 回调函数。当子进程启动成功,err为undefined,data为获取到的子进程pid;否则为错误对象。

错误码:

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
16000050 Internal error.
16000061 Operation not supported.
16000062 The number of child processes exceeds the upper limit.

示例:

// 在entry模块的src/main/ets/process下创建DemoProcess.ets子进程类:
// entry/src/main/ets/process/DemoProcess.ets
import { ChildProcess } from '@kit.AbilityKit';

export default class DemoProcess extends ChildProcess {
  onStart() {
    console.info('DemoProcess OnStart() called');
  }
}
// 使用childProcessManager.startChildProcess方法启动子进程:
// entry/src/main/ets/tool/Tool.ets
import { childProcessManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import DemoProcess from '../process/DemoProcess';

try {
  DemoProcess.toString(); // 这里要调用下DemoProcess类的任意方法,防止没有引用到而被构建工具优化掉
  childProcessManager.startChildProcess("./ets/process/DemoProcess.ets", childProcessManager.StartMode.SELF_FORK, (err, data) => {
    if (err) {
      console.error(`startChildProcess error. Code: ${err.code}, message: ${err.message}`);
    } else {
      console.info(`startChildProcess success, pid: ${data}`);
    }
  });
} catch (err) {
  console.error(`startChildProcess error, errorCode: ${(err as BusinessError).code}, errorMsg: ${(err as BusinessError).message}.`);
}

childProcessManager.startArkChildProcess12+

startArkChildProcess(srcEntry: string, args: ChildProcessArgs, options?: ChildProcessOptions): Promise<number>

启动ArkTS子进程。使用Promise异步回调。

调用该接口创建的子进程不会继承父进程资源,子进程创建成功会返回子进程pid,然后执行子进程的ChildProcess.onStart函数。ChildProcess.onStart函数执行完后子进程不会自动销毁,需要子进程调用process.abort销毁。调用该接口的进程销毁后,所创建的子进程也会一并销毁。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

设备行为差异:该接口在Tablet、PC/2in1中可正常调用,在其他设备类型中返回801错误码。

参数:

参数名 类型 必填 说明
srcEntry string 是

子进程源文件路径,不支持源文件放在HAR类型的模块中。由“模块名” + “/” + “文件路径”组成,文件路径以src/main为根目录。例如子进程文件在module1模块下src/main/ets/process/DemoProcess.ets,则srcEntry为"module1/ets/process/DemoProcess.ets"。

另外,需要确保子进程源文件被其它文件引用到,防止被构建工具优化掉(详见下方示例代码)。

args ChildProcessArgs 是 传递到子进程的参数。对象包含entryParams(字符串类型,传递给子进程的参数)和fds(文件描述符句柄集合,用于主进程和子进程通信)。
options ChildProcessOptions 否 子进程的启动配置选项。

返回值:

类型 说明
Promise<number> Promise对象,返回子进程pid。

错误码:

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
801 Capability not supported.
16000050 Internal error.
16000061 Operation not supported.
16000062

The number of child processes exceeds the upper limit.

适用版本:13+

示例:

子进程部分:

// 在module1模块的src/main/ets/process下创建DemoProcess.ets子进程类:
// module1/src/main/ets/process/DemoProcess.ets
import { ChildProcess, ChildProcessArgs } from '@kit.AbilityKit';

export default class DemoProcess extends ChildProcess {

  onStart(args?: ChildProcessArgs) {
    let entryParams = args?.entryParams;
    let fd = args?.fds?.key1;
    // ..
  }
}

主进程部分,示例中的context的获取方式请参见获取UIAbility的上下文信息:

// 使用childProcessManager.startArkChildProcess方法启动子进程:
// module1/src/main/ets/tool/Tool.ets
import { common, ChildProcessArgs, ChildProcessOptions, childProcessManager } from '@kit.AbilityKit';
import { fileIo } from '@kit.CoreFileKit';
import { BusinessError } from '@kit.BasicServicesKit';
import DemoProcess from '../process/DemoProcess';

@Entry
@Component
struct Index {
  build() {
    Row() {
      Column() {
        Text('Click')
          .fontSize(30)
          .fontWeight(FontWeight.Bold)
          .onClick(() => {
            try {
              DemoProcess.toString(); // 这里要调用下DemoProcess类的任意方法,防止没有引用到而被构建工具优化掉
              let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
              let path = context.filesDir + "/test.txt";
              let file = fileIo.openSync(path, fileIo.OpenMode.READ_ONLY | fileIo.OpenMode.CREATE);
              let args: ChildProcessArgs = {
                entryParams: "testParam",
                fds: {
                  "key1": file.fd
                }
              };
              let options: ChildProcessOptions = {
                isolationMode: false
              };
              childProcessManager.startArkChildProcess("module1/ets/process/DemoProcess.ets", args, options)
                .then((pid) => {
                  console.info(`startArkChildProcess success, pid: ${pid}`);
                })
                .catch((err: BusinessError) => {
                  console.error(`startArkChildProcess business error, errorCode: ${err.code}, errorMsg:${err.message}`);
                })
            } catch (err) {
              console.error(`startArkChildProcess error, errorCode: ${err.code}, errorMsg:${err.message}`);
            }
          });
      }
      .width('100%')
    }
    .height('100%')
  }
}

childProcessManager.startNativeChildProcess13+

startNativeChildProcess(entryPoint: string, args: ChildProcessArgs, options?: ChildProcessOptions): Promise<number>

启动Native子进程。使用Promise异步回调。

使用场景:

调用该接口创建的子进程不会继承父进程资源,子进程创建成功会返回子进程pid,然后加载参数中指定的动态链接库文件并执行子进程的入口函数,入口函数执行完后子进程会自动销毁。调用该接口的进程销毁后,所创建的子进程也会一并销毁。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

设备行为差异:该接口在Tablet、PC/2in1中可正常调用,在其他设备类型中返回801错误码。

参数:

参数名 类型 必填 说明
entryPoint string 是 子进程中调用动态库的符号和入口函数,中间用“:”隔开(例如“libentry.so:Main”)。
args ChildProcessArgs 是 传递到子进程的参数。对象包含entryParams(字符串类型,传递给子进程的参数)和fds(文件描述符句柄集合,用于主进程和子进程通信)。
options ChildProcessOptions 否 子进程的启动配置选项。对象包含isolationMode(是否启用隔离模式)等属性。如果不传则使用ChildProcessOptions中的默认配置。

返回值:

类型 说明
Promise<number> Promise对象,返回子进程pid。

错误码:

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
801 Capability not supported. Failed to call the API due to limited device capabilities.
16000050 Internal error.
16000061 Operation not supported.
16000062 The number of child processes exceeds the upper limit.

示例:

子进程部分,详见子进程开发指导(ArkTS)- 创建支持参数传递的Native子进程:

#include <AbilityKit/native_child_process.h>

extern "C" {

/**
 * 子进程的入口函数,实现子进程的业务逻辑
 * 函数名称可以自定义,在主进程调用OH_Ability_StartNativeChildProcess方法时指定,此示例中为Main
 * 函数返回后子进程退出
 */
void Main(NativeChildProcess_Args args)
{
    // 获取传入的entryParams
    char *entryParams = args.entryParams;
    // 获取传入的fd列表,对应ChildProcessArgs中的args.fds
    NativeChildProcess_Fd *current = args.fdList.head;
    while (current != nullptr) {
        char *fdName = current->fdName;
        int32_t fd = current->fd;
        current = current->next;
        // 业务逻辑...
    }
}
} // extern "C"

主进程部分,示例中的context的获取方式请参见获取UIAbility的上下文信息:

// 主进程:
// 使用childProcessManager.startNativeChildProcess方法启动子进程:
import { common, ChildProcessArgs, ChildProcessOptions, childProcessManager } from '@kit.AbilityKit';
import { fileIo } from '@kit.CoreFileKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  build() {
    Row() {
      Column() {
        Text('Click')
          .fontSize(30)
          .fontWeight(FontWeight.Bold)
          .onClick(() => {
            try {
              let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
              let path = context.filesDir + "/test.txt";
              let file = fileIo.openSync(path, fileIo.OpenMode.READ_ONLY | fileIo.OpenMode.CREATE);
              let args: ChildProcessArgs = {
                entryParams: "testParam",
                fds: {
                  "key1": file.fd
                }
              };
              let options: ChildProcessOptions = {
                isolationMode: false
              };
              childProcessManager.startNativeChildProcess("libentry.so:Main", args, options)
                .then((pid) => {
                  console.info(`startNativeChildProcess success, pid: ${pid}`);
                })
                .catch((err: BusinessError) => {
                  console.error(`startNativeChildProcess business error, errorCode: ${err.code}, errorMsg:${err.message}`);
                })
            } catch (err) {
              console.error(`startNativeChildProcess error, errorCode: ${err.code}, errorMsg:${err.message}`);
            }
          });
      }
      .width('100%')
    }
    .height('100%')
  }
}

childProcessManager.isArkChildProcessSupported

isArkChildProcessSupported(): boolean

查询是否允许调用者在此设备上创建ArkTS子进程。

起始版本: 26.0.0

模型约束: 此接口仅可在Stage模型下使用。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

返回值:

类型 说明
boolean

是否允许调用者创建ArkTS子进程。

true:允许创建ArkTS子进程。

false:不允许创建ArkTS子进程。

默认值:false。

示例:

import { childProcessManager } from '@kit.AbilityKit';

@Entry
@Component
struct Index {
  build() {
    Row() {
      Column() {
        Text('Click')
          .fontSize(30)
          .fontWeight(FontWeight.Bold)
          .onClick(() => {
            try {
              let isSupport: boolean = childProcessManager.isArkChildProcessSupported();
              console.info(`isArkChildProcessSupported: ${isSupport}`);
            } catch (err) {
              console.error(`isArkChildProcessSupported error, errorCode: ${err.code}, errorMsg: ${err.message}`);
            }
          });
      }
      .width('100%')
    }
    .height('100%')
  }
}

childProcessManager.isNativeChildProcessSupported

isNativeChildProcessSupported(): boolean

查询是否允许调用者在此设备上创建Native子进程。

起始版本: 26.0.0

模型约束: 此接口仅可在Stage模型下使用。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

返回值:

类型 说明
boolean

是否允许调用者创建Native子进程。

true:允许创建Native子进程。

false:不允许创建Native子进程。

默认值:false。

示例:

import { childProcessManager } from '@kit.AbilityKit';

@Entry
@Component
struct Index {
  build() {
    Row() {
      Column() {
        Text('Click')
          .fontSize(30)
          .fontWeight(FontWeight.Bold)
          .onClick(() => {
            try {
              let isSupport: boolean = childProcessManager.isNativeChildProcessSupported();
              console.info(`isNativeChildProcessSupported: ${isSupport}`);
            } catch (err) {
              console.error(`isNativeChildProcessSupported error, errorCode: ${err.code}, errorMsg: ${err.message}`);
            }
          });
      }
      .width('100%')
    }
    .height('100%')
  }
}

childProcessManager.getChildProcessInfos

getChildProcessInfos(): Promise<Array<ChildProcessInformation>>

获取当前应用的所有子进程信息,使用Promise异步回调。包括通过以下方式启动的子进程:

起始版本: 26.0.1

模型约束: 此接口仅可在Stage模型下使用。

系统能力:SystemCapability.Ability.AbilityRuntime.Core

返回值:

类型 说明
Promise<Array<ChildProcessInformation>> Promise对象,返回当前应用的子进程信息。

错误码:

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

错误码ID 错误信息
16000050 Connect to system service failed.

示例:

import { childProcessManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

childProcessManager.getChildProcessInfos().then((data) => {
  console.info(`getChildProcessInfos success, count: ${data.length}`);
  for (let info of data) {
    console.info(`pid: ${info.pid}, parentPid: ${info.parentPid}, processName: ${info.processName}`);
  }
}).catch((err: BusinessError) => {
  console.error(`getChildProcessInfos failed, code: ${err.code}, msg: ${err.message}`);
});