diff --git a/doc/api/errors.md b/doc/api/errors.md index a98571edd61942..3079e2031d7a9f 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -1566,6 +1566,17 @@ behavior. See the documentation for [policy][] manifests for more information. An attempt was made to allocate memory (usually in the C++ layer) but it failed. + +### `ERR_MESSAGE_TARGET_CONTEXT_UNAVAILABLE` + + +A message posted to a [`MessagePort`][] could not be deserialized in the target +[vm][] `Context`. Not all Node.js objects can be successfully instantiated in +any context at this time, and attempting to transfer them using `postMessage()` +can fail on the receiving side in that case. + ### `ERR_METHOD_NOT_IMPLEMENTED` @@ -1589,8 +1600,9 @@ is thrown if a required option is missing. ### `ERR_MISSING_MESSAGE_PORT_IN_TRANSFER_LIST` -A `MessagePort` was found in the object passed to a `postMessage()` call, -but not provided in the `transferList` for that call. +An object that needs to be explicitly listed in the `transferList` argument +was found in the object passed to a `postMessage()` call, but not provided in +the `transferList` for that call. Usually, this is a `MessagePort`. ### `ERR_MISSING_PASSPHRASE` @@ -2563,6 +2575,7 @@ such as `process.stdout.on('data')`. [`Class: assert.AssertionError`]: assert.html#assert_class_assert_assertionerror [`ERR_INVALID_ARG_TYPE`]: #ERR_INVALID_ARG_TYPE [`EventEmitter`]: events.html#events_class_eventemitter +[`MessagePort`]: worker_threads.html#worker_threads_class_messageport [`Object.getPrototypeOf`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getPrototypeOf [`Object.setPrototypeOf`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/setPrototypeOf [`REPL`]: repl.html diff --git a/doc/api/worker_threads.md b/doc/api/worker_threads.md index d4fd2f5179a3c1..702abca0a01dd9 100644 --- a/doc/api/worker_threads.md +++ b/doc/api/worker_threads.md @@ -303,6 +303,15 @@ input of [`port.postMessage()`][]. Listeners on this event will receive a clone of the `value` parameter as passed to `postMessage()` and no further arguments. +### Event: `'messageerror'` + + +* `error` {Error} An Error object + +The `'messageerror'` event is emitted when deserializing a message failed. + ### `port.close()` * `value` {any} @@ -335,7 +348,8 @@ In particular, the significant differences to `JSON` are: * `value` may contain typed arrays, both using `ArrayBuffer`s and `SharedArrayBuffer`s. * `value` may contain [`WebAssembly.Module`][] instances. -* `value` may not contain native (C++-backed) objects other than `MessagePort`s. +* `value` may not contain native (C++-backed) objects other than `MessagePort`s + and [`FileHandle`][]s. ```js const { MessageChannel } = require('worker_threads'); @@ -349,7 +363,8 @@ circularData.foo = circularData; port2.postMessage(circularData); ``` -`transferList` may be a list of `ArrayBuffer` and `MessagePort` objects. +`transferList` may be a list of [`ArrayBuffer`][], [`MessagePort`][] and +[`FileHandle`][] objects. After transferring, they will not be usable on the sending side of the channel anymore (even if they are not contained in `value`). Unlike with [child processes][], transferring handles such as network sockets is currently @@ -675,6 +690,15 @@ See the [`port.on('message')`][] event for more details. All messages sent from the worker thread will be emitted before the [`'exit'` event][] is emitted on the `Worker` object. +### Event: `'messageerror'` + + +* `error` {Error} An Error object + +The `'messageerror'` event is emitted when deserializing a message failed. + ### Event: `'online'`