diff options
author | Anna Henningsen <anna@addaleax.net> | 2019-10-29 15:15:36 +0100 |
---|---|---|
committer | Anna Henningsen <anna@addaleax.net> | 2019-11-05 23:07:04 +0100 |
commit | 973f324463a91721cc8a1158a5ab10ad0dd69019 (patch) | |
tree | a7664cbcc50c0fe7eced11fb20e49dc255abfe1e /doc/api | |
parent | f17e414dc4b5d80dd5b5c7ee7107659ec5ebeb1a (diff) | |
download | android-node-v8-973f324463a91721cc8a1158a5ab10ad0dd69019.tar.gz android-node-v8-973f324463a91721cc8a1158a5ab10ad0dd69019.tar.bz2 android-node-v8-973f324463a91721cc8a1158a5ab10ad0dd69019.zip |
child_process,cluster: allow using V8 serialization API
Add an `serialization` option that allows child process IPC to
use the (typically more powerful) V8 serialization API.
Fixes: https://github.com/nodejs/node/issues/10965
PR-URL: https://github.com/nodejs/node/pull/30162
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Gus Caplan <me@gus.host>
Reviewed-By: David Carlier <devnexen@gmail.com>
Reviewed-By: Michaƫl Zasso <targos@protonmail.com>
Diffstat (limited to 'doc/api')
-rw-r--r-- | doc/api/child_process.md | 39 | ||||
-rw-r--r-- | doc/api/cluster.md | 8 | ||||
-rw-r--r-- | doc/api/process.md | 6 |
3 files changed, 53 insertions, 0 deletions
diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 24dd6269f1..a2945ad764 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -321,6 +321,9 @@ arbitrary command execution.** <!-- YAML added: v0.5.0 changes: + - version: REPLACEME + pr-url: https://github.com/nodejs/node/pull/30162 + description: The `serialization` option is supported now. - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/10866 description: The `stdio` option can now be a string. @@ -340,6 +343,9 @@ changes: * `execPath` {string} Executable used to create the child process. * `execArgv` {string[]} List of string arguments passed to the executable. **Default:** `process.execArgv`. + * `serialization` {string} Specify the kind of serialization used for sending + messages between processes. Possible values are `'json'` and `'advanced'`. + See [Advanced Serialization][] for more details. **Default:** `'json'`. * `silent` {boolean} If `true`, stdin, stdout, and stderr of the child will be piped to the parent, otherwise they will be inherited from the parent, see the `'pipe'` and `'inherit'` options for [`child_process.spawn()`][]'s @@ -386,6 +392,9 @@ The `shell` option available in [`child_process.spawn()`][] is not supported by <!-- YAML added: v0.1.90 changes: + - version: REPLACEME + pr-url: https://github.com/nodejs/node/pull/30162 + description: The `serialization` option is supported now. - version: v8.8.0 pr-url: https://github.com/nodejs/node/pull/15380 description: The `windowsHide` option is supported now. @@ -411,6 +420,9 @@ changes: [`options.detached`][]). * `uid` {number} Sets the user identity of the process (see setuid(2)). * `gid` {number} Sets the group identity of the process (see setgid(2)). + * `serialization` {string} Specify the kind of serialization used for sending + messages between processes. Possible values are `'json'` and `'advanced'`. + See [Advanced Serialization][] for more details. **Default:** `'json'`. * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses `'/bin/sh'` on Unix, and `process.env.ComSpec` on Windows. A different shell can be specified as a string. See [Shell Requirements][] and @@ -998,6 +1010,11 @@ The `'message'` event is triggered when a child process uses The message goes through serialization and parsing. The resulting message might not be the same as what is originally sent. +If the `serialization` option was set to `'advanced'` used when spawning the +child process, the `message` argument can contain data that JSON is not able +to represent. +See [Advanced Serialization][] for more details. + ### subprocess.channel <!-- YAML added: v7.1.0 @@ -1472,6 +1489,26 @@ the same requirement. Thus, in `child_process` functions where a shell can be spawned, `'cmd.exe'` is used as a fallback if `process.env.ComSpec` is unavailable. +## Advanced Serialization +<!-- YAML +added: REPLACEME +--> + +Child processes support a serialization mechanism for IPC that is based on the +[serialization API of the `v8` module][v8.serdes], based on the +[HTML structured clone algorithm][]. This is generally more powerful and +supports more built-in JavaScript object types, such as `BigInt`, `Map` +and `Set`, `ArrayBuffer` and `TypedArray`, `Buffer`, `Error`, `RegExp` etc. + +However, this format is not a full superset of JSON, and e.g. properties set on +objects of such built-in types will not be passed on through the serialization +step. Additionally, performance may not be equivalent to that of JSON, depending +on the structure of the passed data. +Therefore, this feature requires opting in by setting the +`serialization` option to `'advanced'` when calling [`child_process.spawn()`][] +or [`child_process.fork()`][]. + +[Advanced Serialization]: #child_process_advanced_serialization [`'disconnect'`]: process.html#process_event_disconnect [`'error'`]: #child_process_event_error [`'exit'`]: #child_process_event_exit @@ -1505,5 +1542,7 @@ unavailable. [`subprocess.stdout`]: #child_process_subprocess_stdout [`util.promisify()`]: util.html#util_util_promisify_original [Default Windows Shell]: #child_process_default_windows_shell +[HTML structured clone algorithm]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm [Shell Requirements]: #child_process_shell_requirements [synchronous counterparts]: #child_process_synchronous_process_creation +[v8.serdes]: v8.html#v8_serialization_api diff --git a/doc/api/cluster.md b/doc/api/cluster.md index 112da9b2aa..dbe5080ff3 100644 --- a/doc/api/cluster.md +++ b/doc/api/cluster.md @@ -724,6 +724,9 @@ values are `'rr'` and `'none'`. <!-- YAML added: v0.7.1 changes: + - version: REPLACEME + pr-url: https://github.com/nodejs/node/pull/30162 + description: The `serialization` option is supported now. - version: v9.5.0 pr-url: https://github.com/nodejs/node/pull/18399 description: The `cwd` option is supported now. @@ -746,6 +749,10 @@ changes: **Default:** `process.argv.slice(2)`. * `cwd` {string} Current working directory of the worker process. **Default:** `undefined` (inherits from parent process). + * `serialization` {string} Specify the kind of serialization used for sending + messages between processes. Possible values are `'json'` and `'advanced'`. + See [Advanced Serialization for `child_process`][] for more details. + **Default:** `false`. * `silent` {boolean} Whether or not to send output to parent's stdio. **Default:** `false`. * `stdio` {Array} Configures the stdio of forked processes. Because the @@ -874,4 +881,5 @@ socket.on('data', (id) => { [`process` event: `'message'`]: process.html#process_event_message [`server.close()`]: net.html#net_event_close [`worker.exitedAfterDisconnect`]: #cluster_worker_exitedafterdisconnect +[Advanced Serialization for `child_process`]: child_process.html#child_process_advanced_serialization [Child Process module]: child_process.html#child_process_child_process_fork_modulepath_args_options diff --git a/doc/api/process.md b/doc/api/process.md index 9fa2b78654..a9b5c4af09 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -119,6 +119,11 @@ the child process. The message goes through serialization and parsing. The resulting message might not be the same as what is originally sent. +If the `serialization` option was set to `advanced` used when spawning the +process, the `message` argument can contain data that JSON is not able +to represent. +See [Advanced Serialization for `child_process`][] for more details. + ### Event: 'multipleResolves' <!-- YAML added: v10.12.0 @@ -2456,6 +2461,7 @@ cases: [`require.resolve()`]: modules.html#modules_require_resolve_request_options [`subprocess.kill()`]: child_process.html#child_process_subprocess_kill_signal [`v8.setFlagsFromString()`]: v8.html#v8_v8_setflagsfromstring_flags +[Advanced Serialization for `child_process`]: child_process.html#child_process_advanced_serialization [Android building]: https://github.com/nodejs/node/blob/master/BUILDING.md#androidandroid-based-devices-eg-firefox-os [Child Process]: child_process.html [Cluster]: cluster.html |