• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.app.ability.childProcessManager (childProcessManager)
2
3The **childProcessManager** module provides the child process management capability. Currently, it provides APIs to start the child process and is available only for tablets.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 11. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8>
9> The APIs of this module can be used only in the stage model.
10
11## Modules to Import
12
13```ts
14import childProcessManager from '@ohos.app.ability.childProcessManager';
15```
16
17## childProcessManager.StartMode
18
19Enumerates the child process start modes.
20
21**System capability**: SystemCapability.Ability.AbilityRuntime.Core
22
23| Name                      | Value                            | Description                             |
24| --------                     |  -----------------               |  -----------------               |
25| SELF_FORK |  0   | The child process is forked from the application process. Binder IPC cannot be called in such a child process. Otherwise, the child process will crash.|
26| APP_SPAWN_FORK |  1   | The child process is forked from AppSpawn. Such a child process does not inherit the parent process resources. It does not have application context and therefore does not support API calls that depend on application context.|
27
28## childProcessManager.startChildProcess
29
30startChildProcess(srcEntry: string, startMode: StartMode): Promise<number>;
31
32Creates a child process and invokes the entrypoint method of the child process. This API uses a promise to return the result. A PID is returned once the child process is created. However, this does not mean that the child process is started. It is started only when the entrypoint method of the child process is successfully invoked. This API cannot be called by a child process to create its child process.
33
34**System capability**: SystemCapability.Ability.AbilityRuntime.Core
35
36**Parameters**
37
38  | Name| Type| Mandatory| Description|
39  | -------- | -------- | -------- | -------- |
40  | srcEntry | string | Yes| Relative path of the source file of the child process. (The source file must be stored in **src/main**. For details, see the sample code below.) Currently, source files can be stored only in modules of the entry type.|
41  | startMode | [StartMode](#childprocessmanagerstartmode) | Yes| Start mode of the child process.|
42
43**Return value**
44
45  | Type| Description|
46  | -------- | -------- |
47  | Promise<number> | Promise used to return the PID of the child process.|
48
49**Error codes**
50
51| ID| Error Message|
52| ------- | -------- |
53| 16000050 | Internal error. |
54| 16000061  | Operation not supported. |
55| 16000062  | The number of child process exceeds upper bound. |
56
57For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
58
59**Example**
60
61```ts
62// Create the child process class DemoProcess.ts in src/main/ets/process of the entry module.
63import ChildProcess from '@ohos.app.ability.ChildProcess';
64
65export default class DemoProcess extends ChildProcess {
66  onStart() {
67    console.log("DemoProcess OnStart() called");
68  }
69}
70```
71
72```ts
73// Call childProcessManager.startChildProcess to start the child process.
74import childProcessManager from '@ohos.app.ability.childProcessManager';
75import DemoProcess from '../process/DemoProcess';
76import { BusinessError } from '@ohos.base';
77
78try {
79  DemoProcess.toString(); // Call any API of the DemoProcess class to prevent the code from being directly optimized by the compiler because it is not being referenced.
80  childProcessManager.startChildProcess("./ets/process/DemoProcess.ts", childProcessManager.StartMode.SELF_FORK)
81    .then((data) => {
82      console.log(`startChildProcess success, pid: ${data}`);
83    }, (err: BusinessError) => {
84      console.error(`startChildProcess error, errorCode: ${err.code}`);
85    })
86} catch (err) {
87  console.error(`startChildProcess error, errorCode: ${(err as BusinessError).code}`);
88}
89```
90
91## childProcessManager.startChildProcess
92
93startChildProcess(srcEntry: string, startMode: StartMode, callback: AsyncCallback<number>): void;
94
95Creates a child process and invokes the entrypoint method of the child process. This API uses an asynchronous callback to return the result. A PID is returned once the child process is created. However, this does not mean that the child process is started. It is started only when the entrypoint method of the child process is successfully invoked. This API cannot be called by a child process to create its child process.
96
97**System capability**: SystemCapability.Ability.AbilityRuntime.Core
98
99**Parameters**
100
101  | Name| Type| Mandatory| Description|
102  | -------- | -------- | -------- | -------- |
103  | srcEntry | string | Yes| Relative path of the source file of the child process. (The source file must be stored in **src/main**. For details, see the sample code below.) Currently, source files can be stored only in modules of the entry type.|
104  | startMode | [StartMode](#childprocessmanagerstartmode) | Yes| Start mode of the child process.|
105  | callback | AsyncCallback<number> | Yes| Callback used to return the PID of the child process.|
106
107**Error codes**
108
109| ID| Error Message|
110| ------- | -------- |
111| 16000050 | Internal error. |
112| 16000061  | Operation not supported. |
113| 16000062  | The number of child process exceeds upper bound. |
114
115For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
116
117**Example**
118
119```ts
120// Create the child process class DemoProcess.ts in src/main/ets/process of the entry module.
121import ChildProcess from '@ohos.app.ability.ChildProcess';
122
123export default class DemoProcess extends ChildProcess {
124  onStart() {
125    console.log("DemoProcess OnStart() called");
126  }
127}
128```
129
130```ts
131// Call childProcessManager.startChildProcess to start the child process.
132import childProcessManager from '@ohos.app.ability.childProcessManager';
133import DemoProcess from '../process/DemoProcess';
134import { BusinessError } from '@ohos.base';
135
136try {
137  DemoProcess.toString(); // Call any API of the DemoProcess class to prevent the code from being directly optimized by the compiler because it is not being referenced.
138  childProcessManager.startChildProcess("./ets/process/DemoProcess.ts", childProcessManager.StartMode.SELF_FORK, (err, data) => {
139    if (data) {
140      console.log(`startChildProcess success, pid: ${data}`);
141    } else {
142      console.error(`startChildProcess error, errorCode: ${err.code}`);
143    }
144  });
145} catch (err) {
146  console.error(`startChildProcess error, errorCode: ${(err as BusinessError).code}`);
147}
148```
149