-
Notifications
You must be signed in to change notification settings - Fork 15k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat: UtilityProcess API #34980
Merged
Merged
feat: UtilityProcess API #34980
Changes from 36 commits
Commits
Show all changes
50 commits
Select commit
Hold shift + click to select a range
1f90147
chore: initial scaffolding
deepak1556 8d6735e
chore: implement interface and docs
deepak1556 d09f507
chore: address code style review
deepak1556 7adacda
fix: cleanup of utility process on shutdown
deepak1556 f74d84d
chore: simplify NodeBindings::CreateEnvironment
deepak1556 a4caadb
chore: rename disableLibraryValidation => allowLoadingUnsignedLibraries
deepak1556 ebbd3e5
chore: implement process.parentPort
deepak1556 fe7d6d5
chore(posix): implement stdio pipe interface
deepak1556 5e08d9f
chore(win): implement stdio interface
deepak1556 36cb34a
chore: reenable SetNodeOptions for utility process
deepak1556 906428e
chore: add specs
deepak1556 0db19ab
chore: fix lint
deepak1556 9bed786
fix: update kill API
deepak1556 489d3ac
fix: update process.parentPort API
deepak1556 f1393cd
fix: exit event
deepak1556 1ce8398
docs: update exit event
deepak1556 540f067
fix: tests on linux
deepak1556 965c5e3
chore: expand on some comments
deepak1556 5cb954d
fix: shutdown of pipe reader
deepak1556 76d398f
fix: remove exit code check for crash spec
deepak1556 c3dff10
fix: rm PR_SET_NO_NEW_PRIVS for unsandbox utility process
deepak1556 c8010a8
chore: fix incorrect rebase
deepak1556 c5f131f
fix: address review feedback
deepak1556 356bf25
Merge remote-tracking branch 'origin/main' into robo/feat_enable_util…
deepak1556 c04d850
chore: rename utility_process -> utility
deepak1556 328ce01
chore: update docs
deepak1556 4a3a579
chore: cleanup c++ implemantation
deepak1556 e3b4c22
fix: leak in NodeServiceHost impl
deepak1556 1b3ac3f
chore: minor cleanup
deepak1556 8793136
chore: cleanup JS implementation
deepak1556 6430fc8
chore: flip default stdio to inherit
deepak1556 9b2c4c8
Merge remote-tracking branch 'origin' into robo/feat_enable_utility_p…
deepak1556 40a545b
fix: some api improvements
deepak1556 581bcc9
fix: add tests for cwd and env option
deepak1556 09b7ba8
Merge remote-tracking branch 'origin' into robo/feat_enable_utility_p…
deepak1556 6a3c11c
chore: alt impl for reading stdio handles
deepak1556 5aebc0b
chore: support message queuing
deepak1556 d7df0c0
Merge remote-tracking branch 'origin' into robo/feat_enable_utility_p…
deepak1556 98ac626
chore: fix lint
deepak1556 6616a24
chore: new UtilityProcess => utilityProcess.fork
deepak1556 82c6114
fix: support for uncaught exception exits
deepak1556 d33b0b0
chore: remove process.execArgv as default
deepak1556 014d6e8
fix: windows build
deepak1556 a82d322
fix: style changes
deepak1556 77eab25
Merge remote-tracking branch 'origin' into robo/feat_enable_utility_p…
deepak1556 8632413
Merge remote-tracking branch 'origin' into robo/feat_enable_utility_p…
deepak1556 f6b160a
fix: docs and style changes
deepak1556 a8c0069
Merge remote-tracking branch 'origin' into robo/feat_enable_utility_p…
deepak1556 c806238
chore: update patches
patchup[bot] e8f8dd8
spec: disable flaky test on win32 arm CI
deepak1556 File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
module.exports = require('./webpack.config.base')({ | ||
target: 'utility', | ||
alwaysHasNode: true | ||
}); |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,44 @@ | ||
# parentPort | ||
|
||
> Interface for communication with parent process. | ||
|
||
Process: [Utility](../glossary.md#utility-process) | ||
|
||
`parentPort` is an [EventEmitter][event-emitter]. | ||
_This object is not exported from the `'electron'` module. It is only available as a property of the process object in the Electron API._ | ||
|
||
```js | ||
// Main process | ||
const child = new UtilityProcess(path.join(__dirname, 'test.js')) | ||
child.postMessage({ message: 'hello' }) | ||
child.on('message', (data) => { | ||
console.log(data) // hello world! | ||
}) | ||
|
||
// Child process | ||
process.parentPort.on('message', (e) => { | ||
process.parentPort.postMessage(`${e.data} world!`) | ||
}) | ||
``` | ||
|
||
## Events | ||
|
||
The `parentPort` object emits the following events: | ||
|
||
### Event: 'message' | ||
|
||
Returns: | ||
|
||
* `messageEvent` Object | ||
* `data` any | ||
* `ports` MessagePortMain[] | ||
|
||
Emitted when the process receives a message. | ||
|
||
## Methods | ||
|
||
### `parentPort.postMessage(message)` | ||
|
||
* `message` any | ||
|
||
Sends a message from the process to its parent. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,128 @@ | ||
# UtilityProcess | ||
|
||
`UtilityProcess` creates a child process with | ||
Node.js and Message ports enabled. It provides the equivalent of [`child_process.fork`][] API from Node.js | ||
but instead uses [Services API][] from Chromium to launch the child process. | ||
|
||
`UtilityProcess` is an [EventEmitter][event-emitter]. | ||
|
||
## Class: UtilityProcess | ||
|
||
> Child process with Node.js integration spawned by Chromium. | ||
|
||
Process: [Main](../glossary.md#main-process)<br /> | ||
|
||
### `new UtilityProcess(modulePath[, args][, options])` | ||
deepak1556 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
* `modulePath` string - Path to the script that should run as entrypoint in the child process. | ||
* `args` string[] (optional) - List of string arguments that will be available as `process.argv` | ||
in the child process. | ||
* `options` Object (optional) | ||
* `env` Object (optional) - Environment key-value pairs. Default is `process.env`. | ||
deepak1556 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
* `execArgv` string[] (optional) - List of string arguments passed to the executable. Default is `process.execArgv`. | ||
* `cwd` string (optional) - Current working directory of the child process. | ||
* `stdio` (string[] | string) (optional) - Child's stdout and stderr configuration. Default is `inherit`. | ||
deepak1556 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
String value can be one of `pipe`, `ignore`, `inherit`, for more details on these values you can refer to | ||
[stdio][] documentation from Node.js. Currently this option does not allow configuring | ||
stdin and is always set to `ignore`. For example, the supported values will be processed as following: | ||
* `pipe`: equivalent to ['ignore', 'pipe', 'pipe'] (the default) | ||
* `ignore`: equivalent to 'ignore', 'ignore', 'ignore'] | ||
* `inherit`: equivalent to ['ignore', 'inherit', 'inherit'] | ||
* `serviceName` string (optional) - Name of the process that will appear in `name` property of | ||
[`child-process-gone` event of `app`](app.md#event-child-process-gone). | ||
Default is `node.mojom.NodeService`. | ||
* `allowLoadingUnsignedLibraries` boolean (optional) _macOS_ - With this flag, the utility process will be | ||
launched via the `Electron Helper (Plugin).app` helper executable on macOS, which can be | ||
codesigned with `com.apple.security.cs.disable-library-validation` and | ||
`com.apple.security.cs.allow-unsigned-executable-memory` entitlements. This will allow the utility process | ||
to load unsigned libraries. Unless you specifically need this capability, it is best to leave this disabled. | ||
Default is `false`. | ||
|
||
### Instance Methods | ||
|
||
#### `child.postMessage(message, [transfer])` | ||
|
||
* `message` any | ||
* `transfer` MessagePortMain[] (optional) | ||
|
||
Send a message to the child process, optionally transferring ownership of | ||
zero or more [`MessagePortMain`][] objects. | ||
|
||
For example: | ||
|
||
```js | ||
// Main process | ||
const { port1, port2 } = new MessageChannelMain() | ||
const child = new UtilityProcess(path.join(__dirname, 'test.js')) | ||
child.postMessage({ message: 'hello' }, [port1]) | ||
|
||
// Child process | ||
process.parentPort.once('message', (e) => { | ||
const [port] = e.ports | ||
// ... | ||
}) | ||
``` | ||
|
||
#### `child.kill()` | ||
|
||
Returns `boolean` | ||
|
||
Terminates the process gracefully. On POSIX, it uses SIGTERM | ||
but will ensure the process is reaped on exit. This function returns | ||
true if the kill is successful, and false otherwise. | ||
|
||
### Instance Properties | ||
|
||
#### `child.pid` | ||
|
||
A `Integer | undefined` representing the process identifier (PID) of the child process. | ||
If the child process fails to spawn due to errors, then the value is `undefined`. When | ||
zcbenz marked this conversation as resolved.
Show resolved
Hide resolved
|
||
the child process exits, then the value is `undefined` after the `exit` event is emitted. | ||
|
||
#### `child.stdout` | ||
|
||
A `NodeJS.ReadableStream | null` that represents the child process's stdout. | ||
If the child was spawned with options.stdio[1] set to anything other than 'pipe', then this will be `null`. | ||
When the child process exits, then the value is `null` after the `exit` event is emitted. | ||
|
||
```js | ||
// Main process | ||
const { port1, port2 } = new MessageChannelMain() | ||
const child = new UtilityProcess(path.join(__dirname, 'test.js')) | ||
child.stdout.on('data', (data) => { | ||
console.log(`Received chunk ${data}`) | ||
}) | ||
``` | ||
|
||
#### `child.stderr` | ||
|
||
A `NodeJS.ReadableStream | null` that represents the child process's stderr. | ||
If the child was spawned with options.stdio[2] set to anything other than 'pipe', then this will be `null`. | ||
When the child process exits, then the value is `null` after the `exit` event is emitted. | ||
|
||
### Instance Events | ||
|
||
#### Event: 'spawn' | ||
|
||
Emitted once the child process has spawned successfully. | ||
|
||
#### Event: 'exit' | ||
|
||
Returns: | ||
|
||
* `code` number - Contains the exit code for | ||
the process obtained from waitpid on posix, or GetExitCodeProcess on windows. | ||
|
||
Emitted after the child process ends. | ||
|
||
#### Event: 'message' | ||
|
||
Returns: | ||
|
||
* `message` any | ||
|
||
Emitted when the child process sends a message using [`process.parentPort.postMessage()`](process.md#processparentport). | ||
|
||
[`child_process.fork`]: https://nodejs.org/dist/latest-v16.x/docs/api/child_process.html#child_processforkmodulepath-args-options | ||
[Services API]: https://chromium.googlesource.com/chromium/src/+/master/docs/mojo_and_services.md | ||
[stdio]: https://nodejs.org/dist/latest/docs/api/child_process.html#optionsstdio |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
When the API is fully finalized, we should also update our explainer docs (e.g. Process Model, Tutorial series) to reflect the existence of this new process type.