diff --git a/addons/c_addons.md b/addons/c_addons.md index 9a9262a5..6e87fa9e 100644 --- a/addons/c_addons.md +++ b/addons/c_addons.md @@ -12,7 +12,7 @@ 当不使用 N-API 时，实现插件很复杂，涉及多个组件和 API 的知识： - - V8：Node.js 目前用于提供 JavaScript 实现的 C++ 库。 + - V8：Node.js 用于提供 JavaScript 实现的 C++ 库。 V8 提供了用于创建对象、调用函数等的机制。 V8 的 API 文档主要在 `v8.h` 头文件中（Node.js 源代码树中的 `deps/v8/include/v8.h`），也可以在查看[在线文档][v8-docs]。 diff --git a/addons/context_aware_addons.md b/addons/context_aware_addons.md index 7b73204e..d8910c9f 100644 --- a/addons/context_aware_addons.md +++ b/addons/context_aware_addons.md @@ -33,7 +33,7 @@ NODE_MODULE_INITIALIZER(Local exports, 可以通过执行以下步骤来构造上下文感知的插件以避免全局静态数据： * 定义一个类，该类会保存每个插件实例的数据，并且具有以下形式的静态成员： - ```C++ + ```cpp static void DeleteInstance(void* data) { // 将 `data` 转换为该类的实例并删除它。 } diff --git a/addons/native_abstractions_for_node_js.md b/addons/native_abstractions_for_node_js.md index bf6bc335..12accd64 100644 --- a/addons/native_abstractions_for_node_js.md +++ b/addons/native_abstractions_for_node_js.md @@ -2,7 +2,7 @@ 文档中所示的每个例子都直接使用 Node.js 和 V8 的 API 来实现插件。 V8 的 API 可能并且已经与下一个 V8 的发行版本有显著的变化。 伴随着每次变化，插件为了能够继续工作，可能需要进行更新和重新编译。 -Node.js 的发布计划会尽量减少这种变化的频率和影响，但 Node.js 目前可以确保 V8 API 的稳定性。 +Node.js 的发布计划会尽量减少这种变化的频率和影响，但 Node.js 可以确保 V8 API 的稳定性。 [Node.js 的原生抽象][Native Abstractions for Node.js]（或称为 `nan`）提供了一组工具，建议插件开发者使用这些工具来保持插件在过往与将来的 V8 和 Node.js 的版本之间的兼容性。 查看 `nan` [示例][examples]了解它是如何被使用的。 diff --git a/addons/worker_support.md b/addons/worker_support.md index cb283e02..8cf34ccc 100644 --- a/addons/worker_support.md +++ b/addons/worker_support.md @@ -7,7 +7,7 @@ 为了支持 [`Worker`] 线程，插件需要清理可能分配的任何资源（当存在这样的线程时）。 这可以通过使用 `AddEnvironmentCleanupHook()` 函数来实现： -```c++ +```cpp void AddEnvironmentCleanupHook(v8::Isolate* isolate, void (*fun)(void* arg), void* arg); diff --git a/async_hooks/async_hooks_executionasyncresource.md b/async_hooks/async_hooks_executionasyncresource.md index 24648b3a..84139694 100644 --- a/async_hooks/async_hooks_executionasyncresource.md +++ b/async_hooks/async_hooks_executionasyncresource.md @@ -45,7 +45,7 @@ createHook({ } }).enable(); -const server = createServer(function(req, res) { +const server = createServer((req, res) => { executionAsyncResource()[sym] = { state: req.url }; setTimeout(function() { res.end(JSON.stringify(executionAsyncResource()[sym])); diff --git a/async_hooks/integrating_asyncresource_with_eventemitter.md b/async_hooks/integrating_asyncresource_with_eventemitter.md new file mode 100644 index 00000000..d3c74b82 --- /dev/null +++ b/async_hooks/integrating_asyncresource_with_eventemitter.md @@ -0,0 +1,24 @@ + +Event listeners triggered by an [`EventEmitter`][] may be run in a different +execution context than the one that was active when `eventEmitter.on()` was +called. + +The following example shows how to use the `AsyncResource` class to properly +associate an event listener with the correct execution context. The same +approach can be applied to a [`Stream`][] or a similar event-driven class. + +```js +const { createServer } = require('http'); +const { AsyncResource, executionAsyncId } = require('async_hooks'); + +const server = createServer((req, res) => { + const asyncResource = new AsyncResource('request'); + // The listener will always run in the execution context of `asyncResource`. + req.on('close', asyncResource.runInAsyncScope.bind(asyncResource, () => { + // Prints: true + console.log(asyncResource.asyncId() === executionAsyncId()); + })); + res.end(); +}).listen(3000); +``` + diff --git a/async_hooks/troubleshooting.md b/async_hooks/troubleshooting.md index a43bbba3..8d87b5fb 100644 --- a/async_hooks/troubleshooting.md +++ b/async_hooks/troubleshooting.md @@ -22,3 +22,5 @@ to associate the asynchronous operation with the correct execution context. + + diff --git a/buffer/buffer.md b/buffer/buffer.md index 6f2bbb0a..95914372 100644 --- a/buffer/buffer.md +++ b/buffer/buffer.md @@ -10,7 +10,7 @@ 支持许多涵盖其他用例的额外方法。 只要支持 `Buffer` 的地方，Node.js API 都可以接受普通的 [`Uint8Array`]。 -`Buffer` 类的实例，以及通常的 [`Uint8Array`]，类似于从 `0` 到 `255` 之间的整数数组，但对应于固定大小的内存块，并且不能包含任何其他值。 +`Buffer` 的实例（通常是 [`Uint8Array`] 的实例），类似于从 `0` 到 `255` 之间的整数数组，但对应于固定大小的内存块，并且不能包含任何其他值。 一个 `Buffer` 的大小在创建时确定，且无法更改。 `Buffer` 类在全局作用域中，因此无需使用 `require('buffer').Buffer`。 diff --git a/buffer/class_method_buffer_from_object_offsetorencoding_length.md b/buffer/class_method_buffer_from_object_offsetorencoding_length.md index eb2e3df7..b72a4148 100644 --- a/buffer/class_method_buffer_from_object_offsetorencoding_length.md +++ b/buffer/class_method_buffer_from_object_offsetorencoding_length.md @@ -3,8 +3,8 @@ added: v8.2.0 --> * `object` {Object} 支持 `Symbol.toPrimitive` 或 `valueOf()` 的对象。 -* `offsetOrEncoding` {integer|string} 字节偏移量或字符编码，取决于 `object.valueOf()` 或 `object[Symbol.toPrimitive]()` 返回的值。 -* `length` {integer} 长度，取决于 `object.valueOf()` 或 `object[Symbol.toPrimitive]()` 的返回值。 +* `offsetOrEncoding` {integer|string} 字节偏移量或字符编码。 +* `length` {integer} 长度。 对于 `valueOf()` 返回值不严格等于 `object` 的对象，返回 `Buffer.from(object.valueOf(), offsetOrEncoding, length)`。 @@ -13,7 +13,7 @@ const buf = Buffer.from(new String('this is a test')); // 打印: ``` -对于支持 `Symbol.toPrimitive` 的对象，会返回 `Buffer.from(object[Symbol.toPrimitive](), offsetOrEncoding, length)`。 +对于支持 `Symbol.toPrimitive` 的对象，会返回 `Buffer.from(object[Symbol.toPrimitive]('string'), offsetOrEncoding)`。 ```js class Foo { diff --git a/cli/experimental_top_level_await.md b/cli/experimental_top_level_await.md new file mode 100644 index 00000000..14d07d37 --- /dev/null +++ b/cli/experimental_top_level_await.md @@ -0,0 +1,9 @@ + + +Enable experimental top-level `await` keyword support, available only in ES +module scripts. + +(See also `--experimental-repl-await`.) + diff --git a/cli/experimental_wasm_modules.md b/cli/experimental_wasm_modules.md index 9724a8d2..609519e4 100644 --- a/cli/experimental_wasm_modules.md +++ b/cli/experimental_wasm_modules.md @@ -2,5 +2,3 @@ added: v12.3.0 --> -Enable experimental WebAssembly module support. - diff --git a/cli/force_context_aware.md b/cli/force_context_aware.md index 8a7bacfc..68a3379e 100644 --- a/cli/force_context_aware.md +++ b/cli/force_context_aware.md @@ -4,3 +4,5 @@ added: v12.12.0 Disable loading native addons that are not [context-aware][]. +Enable experimental WebAssembly module support. + diff --git a/cli/node_options_options.md b/cli/node_options_options.md index 981749cb..2652ab18 100644 --- a/cli/node_options_options.md +++ b/cli/node_options_options.md @@ -45,6 +45,7 @@ Node.js options that are allowed are: * `--experimental-policy` * `--experimental-repl-await` * `--experimental-specifier-resolution` +* `--experimental-top-level-await` * `--experimental-vm-modules` * `--experimental-wasi-unstable-preview1` * `--experimental-wasm-modules` @@ -73,7 +74,7 @@ Node.js options that are allowed are: * `--prof-process` * `--redirect-warnings` * `--report-compact` -* `--report-directory` +* `--report-dir`, `--report-directory` * `--report-filename` * `--report-on-fatalerror` * `--report-on-signal` diff --git a/cli/node_skip_platform_check_value.md b/cli/node_skip_platform_check_value.md new file mode 100644 index 00000000..f1dc4412 --- /dev/null +++ b/cli/node_skip_platform_check_value.md @@ -0,0 +1,8 @@ + + +If `value` equals `'1'`, the check for a supported platform is skipped during +Node.js startup. Node.js might not execute correctly. Any issues encountered +on unsupported platforms will not be fixed. + diff --git a/cli/report_directory_directory.md b/cli/report_dir_directory_report_directory_directory.md similarity index 100% rename from cli/report_directory_directory.md rename to cli/report_dir_directory_report_directory_directory.md diff --git a/cli/unhandled_rejections_mode.md b/cli/unhandled_rejections_mode.md index 959ec7ec..dc740478 100644 --- a/cli/unhandled_rejections_mode.md +++ b/cli/unhandled_rejections_mode.md @@ -9,10 +9,14 @@ for the very first unhandled rejection in case no [`unhandledRejection`][] hook is used. Using this flag allows to change what should happen when an unhandled rejection -occurs. One of three modes can be chosen: +occurs. One of the following modes can be chosen: +* `throw`: Emit [`unhandledRejection`][]. If this hook is not set, raise the + unhandled rejection as an uncaught exception. * `strict`: Raise the unhandled rejection as an uncaught exception. * `warn`: Always trigger a warning, no matter if the [`unhandledRejection`][] hook is set or not but do not print the deprecation warning. +* `warn-with-error-code`: Emit [`unhandledRejection`][]. If this hook is not + set, trigger a warning, and set the process exit code to 1. * `none`: Silence all warnings. diff --git a/cluster/worker_kill_signal_sigterm.md b/cluster/worker_kill_signal.md similarity index 96% rename from cluster/worker_kill_signal_sigterm.md rename to cluster/worker_kill_signal.md index 892541b4..0fa4a9ea 100644 --- a/cluster/worker_kill_signal_sigterm.md +++ b/cluster/worker_kill_signal.md @@ -2,7 +2,7 @@ added: v0.9.12 --> -* `signal` {string} 发送给工作进程的杀死信号的名称。 +* `signal` {string} 发送给工作进程的杀死信号的名称。**默认值**: `'SIGTERM'`。 这个方法将会杀死工作进程。 在主进程中，通过断开与 `worker.process` 的连接来实现，一旦断开连接后，通过 `signal` 来杀死工作进程。 diff --git a/crypto/ccm_mode.md b/crypto/ccm_mode.md index 7dfd68e4..ad0e5380 100644 --- a/crypto/ccm_mode.md +++ b/crypto/ccm_mode.md @@ -16,7 +16,12 @@ mode must adhere to certain restrictions when using the cipher API: mode might fail as CCM cannot handle more than one chunk of data per instance. * When passing additional authenticated data (AAD), the length of the actual message in bytes must be passed to `setAAD()` via the `plaintextLength` - option. This is not necessary if no AAD is used. + option. + Many crypto libraries include the authentication tag in the ciphertext, + which means that they produce ciphertexts of the length + `plaintextLength + authTagLength`. Node.js does not include the authentication + tag, so the ciphertext length is always `plaintextLength`. + This is not necessary if no AAD is used. * As CCM processes the whole message at once, `update()` can only be called once. * Even though calling `update()` is sufficient to encrypt/decrypt the message, diff --git a/crypto/class_keyobject.md b/crypto/class_keyobject.md index 0a19571a..a8158926 100644 --- a/crypto/class_keyobject.md +++ b/crypto/class_keyobject.md @@ -1,6 +1,10 @@ +Type: Runtime +`Transform._transformState` will be removed in future versions where it is +no longer required due to simplification of the implementation. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/dgram/socket_send_msg_offset_length_port_address_callback.md b/dgram/socket_send_msg_offset_length_port_address_callback.md index c96c6562..0a3d59e7 100644 --- a/dgram/socket_send_msg_offset_length_port_address_callback.md +++ b/dgram/socket_send_msg_offset_length_port_address_callback.md @@ -1,6 +1,9 @@ -* `msg` {Buffer|Uint8Array|string|Array} 要发送的消息。 +* `msg` {Buffer|TypedArray|DataView|string|Array} 要发送的消息。 * `offset` {integer} 指定消息的开头在 buffer 中的偏移量。 * `length` {integer} 消息的字节数。 * `port` {integer} 目标端口。 @@ -33,7 +36,7 @@ changes: `msg` 参数包含了要发送的消息。 根据消息的类型可以有不同的做法。 -如果 `msg` 是一个 `Buffer` 或 `Uint8Array`，则 `offset` 和 `length` 指定了消息在 `Buffer` 中对应的偏移量和字节数。 +如果 `msg` 是一个 `Buffer`、`TypedArray` 或 `DataView`，则 `offset` 和 `length` 指定了消息在 `Buffer` 中对应的偏移量和字节数。 如果 `msg` 是一个` String`，那么它会被自动地按照 `'utf8'` 编码转换为 `Buffer`。 对于包含了多字节字符的消息，`offset` 和 `length` 会根据对应的[字节长度][byte length]进行计算，而不是根据字符的位置。 如果 `msg` 是一个数组，那么 `offset` 和 `length` 必须都不能被指定。 @@ -52,7 +55,7 @@ changes: 若 `callback` 未被指定，该错误会以 `'error'` 事件的方式投射到 `socket` 对象上。 偏移量和长度是可选的，但如其中一个被指定则另一个也必须被指定。 -另外，它们只在第一个参数是 `Buffer` 或 `Uint8Array` 的情况下才能被使用。 +另外，它们只在第一个参数是 `Buffer`、`TypedArray` 或 `DataView` 的情况下才能被使用。 示例，发送 UDP 包到 `localhost` 上的某个端口： diff --git a/dns/dns.md b/dns/dns.md index 8a74c0e2..ba5b730b 100644 --- a/dns/dns.md +++ b/dns/dns.md @@ -9,7 +9,7 @@ 尽管以[域名系统（DNS）][Domain Name System (DNS)]命名，但它并不总是使用 DNS 协议进行查找。 [`dns.lookup()`] 使用操作系统功能来执行名称解析。 它可能不需要执行任何网络通信。 -希望以与同一操作系统上其他应用程序相同的方式执行名称解析的开发者应使用 [`dns.lookup()`]。 +若要像同一系统上其他应用程序一样执行名称解析，则使用 [`dns.lookup()`]。 ```js const dns = require('dns'); @@ -22,8 +22,8 @@ console.log('地址: %j 地址族: IPv%s', address, family); `dns` 模块中的所有其他函数都连接到实际的 DNS 服务器以执行名称解析。 它们将会始终使用网络执行 DNS 查询。 -这些函数不使用与 [`dns.lookup()`] 使用的同一组配置文件（例如 `/etc/hosts`）。 -这些函数应由不想使用底层操作系统的功能进行名称解析、而希望始终执行 DNS 查询的开发者使用。 +这些函数不使用与 [`dns.lookup()`] 使用的同一组配置文件（例如 `/etc/hosts`）。 +使用这些函数可以始终执行 DNS 查询（绕过其他的名称解析功能）。 ```js const dns = require('dns'); diff --git a/dns/resolver_options.md b/dns/resolver_options.md new file mode 100644 index 00000000..3174b94f --- /dev/null +++ b/dns/resolver_options.md @@ -0,0 +1,15 @@ + + +Create a new resolver. + +* `options` {Object} + * `timeout` {integer} Query timeout in milliseconds, or `-1` to use the + default timeout. + diff --git a/embedding/per_instance_state.md b/embedding/per_instance_state.md index 5c45b30c..70408e43 100644 --- a/embedding/per_instance_state.md +++ b/embedding/per_instance_state.md @@ -25,7 +25,7 @@ The `node::NewIsolate()` helper function creates a `v8::Isolate`, sets it up with some Node.js-specific hooks (e.g. the Node.js error handler), and registers it with the platform automatically. -```c++ +```cpp int RunNodeInstance(MultiIsolatePlatform* platform, const std::vector& args, const std::vector& exec_args) { diff --git a/embedding/setting_up_per_process_state.md b/embedding/setting_up_per_process_state.md index 6f0d86d9..4b983d3e 100644 --- a/embedding/setting_up_per_process_state.md +++ b/embedding/setting_up_per_process_state.md @@ -7,7 +7,7 @@ Node.js requires some per-process state management in order to run: The following example shows how these can be set up. Some class names are from the `node` and `v8` C++ namespaces, respectively. -```c++ +```cpp int main(int argc, char** argv) { std::vector args(argv, argv + argc); std::vector exec_args; diff --git a/errors/err_eval_esm_cannot_print.md b/errors/err_eval_esm_cannot_print.md index 8215dcd4..8dad8887 100644 --- a/errors/err_eval_esm_cannot_print.md +++ b/errors/err_eval_esm_cannot_print.md @@ -1,4 +1,4 @@ `--print` cannot be used with ESM input. - + diff --git a/errors/err_event_recursion.md b/errors/err_event_recursion.md new file mode 100644 index 00000000..949121cb --- /dev/null +++ b/errors/err_event_recursion.md @@ -0,0 +1,4 @@ + +Thrown when an attempt is made to recursively dispatch an event on `EventTarget`. + + diff --git a/errors/err_input_type_not_allowed.md b/errors/err_input_type_not_allowed.md index d5eeaec7..83b773fd 100644 --- a/errors/err_input_type_not_allowed.md +++ b/errors/err_input_type_not_allowed.md @@ -4,4 +4,4 @@ The `--input-type` flag was used to attempt to execute a file. This flag can only be used with input via `--eval`, `--print` or `STDIN`. - + diff --git a/errors/err_inspector_already_activated.md b/errors/err_inspector_already_activated.md new file mode 100644 index 00000000..524b6c70 --- /dev/null +++ b/errors/err_inspector_already_activated.md @@ -0,0 +1,6 @@ + +While using the `inspector` module, an attempt was made to activate the +inspector when it already started to listen on a port. Use `inspector.close()` +before activating it on a different address. + + diff --git a/errors/err_invalid_repl_type.md b/errors/err_invalid_repl_type.md index 2409c68a..f09e2d8c 100644 --- a/errors/err_invalid_repl_type.md +++ b/errors/err_invalid_repl_type.md @@ -3,4 +3,4 @@ The `--entry-type=...` flag is not compatible with the Node.js REPL. - + diff --git a/errors/err_memory_allocation_failed.md b/errors/err_memory_allocation_failed.md index 9d232453..a4bab732 100644 --- a/errors/err_memory_allocation_failed.md +++ b/errors/err_memory_allocation_failed.md @@ -2,4 +2,4 @@ An attempt was made to allocate memory (usually in the C++ layer) but it failed. - + diff --git a/errors/err_message_target_context_unavailable.md b/errors/err_message_target_context_unavailable.md new file mode 100644 index 00000000..68ed4cc9 --- /dev/null +++ b/errors/err_message_target_context_unavailable.md @@ -0,0 +1,10 @@ + + +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. + + diff --git a/errors/err_missing_args.md b/errors/err_missing_args.md index 421559f8..6ca509fd 100644 --- a/errors/err_missing_args.md +++ b/errors/err_missing_args.md @@ -5,4 +5,4 @@ strict compliance with the API specification (which in some cases may accept `func(undefined)` and `func()` are treated identically, and the [`ERR_INVALID_ARG_TYPE`][] error code may be used instead. - + diff --git a/errors/err_missing_dynamic_instantiate_hook.md b/errors/err_missing_dynamic_instantiate_hook.md deleted file mode 100644 index c48c0200..00000000 --- a/errors/err_missing_dynamic_instantiate_hook.md +++ /dev/null @@ -1,7 +0,0 @@ - -> Stability: 1 - Experimental - -An [ES Module][] loader hook specified `format: 'dynamic'` but did not provide -a `dynamicInstantiate` hook. - - diff --git a/errors/err_missing_dynamic_instantiate_hook_1.md b/errors/err_missing_dynamic_instantiate_hook_1.md deleted file mode 100644 index c66225ab..00000000 --- a/errors/err_missing_dynamic_instantiate_hook_1.md +++ /dev/null @@ -1,5 +0,0 @@ - -Used when an [ES Module][] loader hook specifies `format: 'dynamic'` but does -not provide a `dynamicInstantiate` hook. - - diff --git a/errors/err_missing_message_port_in_transfer_list.md b/errors/err_missing_message_port_in_transfer_list.md index 16a9ec7d..7ee41664 100644 --- a/errors/err_missing_message_port_in_transfer_list.md +++ b/errors/err_missing_message_port_in_transfer_list.md @@ -1,5 +1,6 @@ -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`. diff --git a/errors/err_tls_renegotiation_failed.md b/errors/err_tls_renegotiation_failed.md index d27b0494..490f2762 100644 --- a/errors/err_tls_renegotiation_failed.md +++ b/errors/err_tls_renegotiation_failed.md @@ -5,4 +5,4 @@ removed: v10.0.0 Used when a TLS renegotiation request has failed in a non-specific way. - + diff --git a/errors/err_trace_events_unavailable.md b/errors/err_trace_events_unavailable.md index ee9687a7..dff0e873 100644 --- a/errors/err_trace_events_unavailable.md +++ b/errors/err_trace_events_unavailable.md @@ -2,4 +2,4 @@ The `trace_events` module could not be loaded because Node.js was compiled with the `--without-v8-platform` flag. - + diff --git a/errors/err_transferring_externalized_sharedarraybuffer.md b/errors/err_transferring_externalized_sharedarraybuffer.md index 88e75069..2660ac4b 100644 --- a/errors/err_transferring_externalized_sharedarraybuffer.md +++ b/errors/err_transferring_externalized_sharedarraybuffer.md @@ -1,3 +1,7 @@ + A `SharedArrayBuffer` whose memory is not managed by the JavaScript engine or by Node.js was encountered during serialization. Such a `SharedArrayBuffer` @@ -6,4 +10,4 @@ cannot be serialized. This can only happen when native addons create `SharedArrayBuffer`s in "externalized" mode, or put existing `SharedArrayBuffer` into externalized mode. - + diff --git a/errors/err_tty_writable_not_readable.md b/errors/err_tty_writable_not_readable.md index 7e422f21..7f6947ea 100644 --- a/errors/err_tty_writable_not_readable.md +++ b/errors/err_tty_writable_not_readable.md @@ -72,5 +72,6 @@ such as `process.stdout.on('data')`. + diff --git a/errors/error_stack.md b/errors/error_stack.md index 5dbff6b4..2ab42db7 100644 --- a/errors/error_stack.md +++ b/errors/error_stack.md @@ -3,7 +3,7 @@ `error.stack` 属性是一个字符串，描述代码中 `Error` 被实例化的位置。 -```txt +```console Error: Things keep happening! at /home/gbusey/file.js:525:2 at Frobnicator.refrobulate (/home/gbusey/business-logic.js:424:21) diff --git a/esm/code_dynamicinstantiate_code_hook.md b/esm/code_dynamicinstantiate_code_hook.md deleted file mode 100644 index cb3afc82..00000000 --- a/esm/code_dynamicinstantiate_code_hook.md +++ /dev/null @@ -1,31 +0,0 @@ - -> Note: The loaders API is being redesigned. This hook may disappear or its -> signature may change. Do not rely on the API described below. - -To create a custom dynamic module that doesn't correspond to one of the -existing `format` interpretations, the `dynamicInstantiate` hook can be used. -This hook is called only for modules that return `format: 'dynamic'` from -the [`getFormat` hook][]. - -```js -/** - * @param {string} url - * @returns {object} response - * @returns {array} response.exports - * @returns {function} response.execute - */ -export async function dynamicInstantiate(url) { - return { - exports: ['customExportName'], - execute: (exports) => { - // Get and set functions provided for pre-allocated export names - exports.customExportName.set('value'); - } - }; -} -``` - -With the list of module exports provided upfront, the `execute` function will -then be called at the exact point of module evaluation order for that module -in the import tree. - diff --git a/esm/code_getformat_code_hook.md b/esm/code_getformat_code_hook.md index 4c567b40..bf4def8a 100644 --- a/esm/code_getformat_code_hook.md +++ b/esm/code_getformat_code_hook.md @@ -3,32 +3,41 @@ > signature may change. Do not rely on the API described below. The `getFormat` hook provides a way to define a custom method of determining how -a URL should be interpreted. This can be one of the following: +a URL should be interpreted. The `format` returned also affects what the +acceptable forms of source values are for a module when parsing. This can be one +of the following: -| `format` | Description | -| --- | --- | -| `'builtin'` | Load a Node.js builtin module | -| `'commonjs'` | Load a Node.js CommonJS module | -| `'dynamic'` | Use a [dynamic instantiate hook][] | -| `'json'` | Load a JSON file | -| `'module'` | Load a standard JavaScript module (ES module) | -| `'wasm'` | Load a WebAssembly module | +| `format` | Description | Acceptable Types For `source` Returned by `getSource` or `transformSource` | +| --- | --- | --- | +| `'builtin'` | Load a Node.js builtin module | Not applicable | +| `'commonjs'` | Load a Node.js CommonJS module | Not applicable | +| `'json'` | Load a JSON file | { [ArrayBuffer][], [string][], [TypedArray][] } | +| `'module'` | Load an ES module | { [ArrayBuffer][], [string][], [TypedArray][] } | +| `'wasm'` | Load a WebAssembly module | { [ArrayBuffer][], [string][], [TypedArray][] } | + +Note: These types all correspond to classes defined in ECMAScript. + +* The specific [ArrayBuffer][] object is a [SharedArrayBuffer][]. +* The specific [string][] object is not the class constructor, but an instance. +* The specific [TypedArray][] object is a [Uint8Array][]. + +Note: If the source value of a text-based format (i.e., `'json'`, `'module'`) is +not a string, it will be converted to a string using [`util.TextDecoder`][]. ```js /** * @param {string} url - * @param {object} context (currently empty) - * @param {function} defaultGetFormat - * @returns {object} response - * @returns {string} response.format + * @param {Object} context (currently empty) + * @param {Function} defaultGetFormat + * @returns {Promise<{ format: string }>} */ export async function getFormat(url, context, defaultGetFormat) { - if (someCondition) { + if (Math.random() > 0.5) { // Some condition. // For some or all URLs, do some custom logic for determining format. // Always return an object of the form {format: }, where the // format is one of the strings in the table above. return { - format: 'module' + format: 'module', }; } // Defer to Node.js for all other URLs. diff --git a/esm/code_getsource_code_hook.md b/esm/code_getsource_code_hook.md index 863eea10..2f6020c6 100644 --- a/esm/code_getsource_code_hook.md +++ b/esm/code_getsource_code_hook.md @@ -9,19 +9,17 @@ potentially avoid reading files from disk. ```js /** * @param {string} url - * @param {object} context - * @param {string} context.format - * @param {function} defaultGetSource - * @returns {object} response - * @returns {string|buffer} response.source + * @param {{ format: string }} context + * @param {Function} defaultGetSource + * @returns {Promise<{ source: !(SharedArrayBuffer | string | Uint8Array) }>} */ export async function getSource(url, context, defaultGetSource) { const { format } = context; - if (someCondition) { + if (Math.random() > 0.5) { // Some condition. // For some or all URLs, do some custom logic for retrieving the source. // Always return an object of the form {source: }. return { - source: '...' + source: '...', }; } // Defer to Node.js for all other URLs. diff --git a/esm/code_resolve_code_hook.md b/esm/code_resolve_code_hook.md index ba47c4a2..e14c1898 100644 --- a/esm/code_resolve_code_hook.md +++ b/esm/code_resolve_code_hook.md @@ -20,25 +20,26 @@ condition list **must** be passed through to the `defaultResolve` function. ```js /** * @param {string} specifier - * @param {object} context - * @param {string} context.parentURL - * @param {string[]} context.conditions - * @param {function} defaultResolve - * @returns {object} response - * @returns {string} response.url + * @param {{ + * parentURL: !(string | undefined), + * conditions: !(Array), + * }} context + * @param {Function} defaultResolve + * @returns {!(Promise<{ url: string }>)} */ export async function resolve(specifier, context, defaultResolve) { const { parentURL = null } = context; - if (someCondition) { + if (Math.random() > 0.5) { // Some condition. // For some or all specifiers, do some custom logic for resolving. - // Always return an object of the form {url: } + // Always return an object of the form {url: }. return { - url: (parentURL) ? - new URL(specifier, parentURL).href : new URL(specifier).href + url: parentURL ? + new URL(specifier, parentURL).href : + new URL(specifier).href, }; } - if (anotherCondition) { - // When calling the defaultResolve, the arguments can be modified. In this + if (Math.random() < 0.5) { // Another condition. + // When calling `defaultResolve`, the arguments can be modified. In this // case it's adding another value for matching conditional exports. return defaultResolve(specifier, { ...context, diff --git a/esm/code_transformsource_code_hook.md b/esm/code_transformsource_code_hook.md index 91337776..90ae5119 100644 --- a/esm/code_transformsource_code_hook.md +++ b/esm/code_transformsource_code_hook.md @@ -12,28 +12,25 @@ unknown-to-Node.js file extensions. See the [transpiler loader example][] below. ```js /** - * @param {string|buffer} source - * @param {object} context - * @param {string} context.url - * @param {string} context.format - * @param {function} defaultTransformSource - * @returns {object} response - * @returns {string|buffer} response.source + * @param {!(SharedArrayBuffer | string | Uint8Array)} source + * @param {{ + * url: string, + * format: string, + * }} context + * @param {Function} defaultTransformSource + * @returns {Promise<{ source: !(SharedArrayBuffer | string | Uint8Array) }>} */ -export async function transformSource(source, - context, - defaultTransformSource) { +export async function transformSource(source, context, defaultTransformSource) { const { url, format } = context; - if (someCondition) { + if (Math.random() > 0.5) { // Some condition. // For some or all URLs, do some custom logic for modifying the source. // Always return an object of the form {source: }. return { - source: '...' + source: '...', }; } // Defer to Node.js for all other sources. - return defaultTransformSource( - source, context, defaultTransformSource); + return defaultTransformSource(source, context, defaultTransformSource); } ``` diff --git a/esm/customizing_esm_specifier_resolution_algorithm.md b/esm/customizing_esm_specifier_resolution_algorithm.md index 7841e5ad..e932a0c3 100644 --- a/esm/customizing_esm_specifier_resolution_algorithm.md +++ b/esm/customizing_esm_specifier_resolution_algorithm.md @@ -43,6 +43,10 @@ success! + + + + diff --git a/esm/input_type_flag.md b/esm/input_type_flag.md index f288cde2..790bb9df 100644 --- a/esm/input_type_flag.md +++ b/esm/input_type_flag.md @@ -3,7 +3,7 @@ Strings passed in as an argument to `--eval` (or `-e`), or piped to `node` via `STDIN`, will be treated as ES modules when the `--input-type=module` flag is set. -```sh +```bash node --input-type=module --eval "import { sep } from 'path'; console.log(sep);" echo "import { sep } from 'path'; console.log(sep);" | node --input-type=module diff --git a/esm/package_json_type_field.md b/esm/package_json_type_field.md index 0442ea64..4dc52afa 100644 --- a/esm/package_json_type_field.md +++ b/esm/package_json_type_field.md @@ -15,7 +15,7 @@ until the root of the volume is reached. } ``` -```sh +```bash # In same folder as above package.json node my-app.js # Runs as ES module ``` diff --git a/events/class_event.md b/events/class_event.md new file mode 100644 index 00000000..bd129421 --- /dev/null +++ b/events/class_event.md @@ -0,0 +1,7 @@ + + +The `Event` object is an adaptation of the [`Event` Web API][]. Instances +are created internally by Node.js. + diff --git a/events/class_eventemitter.md b/events/class_eventemitter.md index f009e849..9b04e2db 100644 --- a/events/class_eventemitter.md +++ b/events/class_eventemitter.md @@ -18,5 +18,5 @@ const EventEmitter = require('events'); 它支持以下选项： -* `captureRejections` {boolean} 它可以[自动捕获 promise 的拒绝][capturerejections]。 默认值：`false`。 +* `captureRejections` {boolean} 它可以[自动捕获 promise 的拒绝][capturerejections]。 **默认值:** `false`。 diff --git a/perf_hooks/class_performance.md b/events/class_eventtarget.md similarity index 50% rename from perf_hooks/class_performance.md rename to events/class_eventtarget.md index 5734aabe..0af65c38 100644 --- a/perf_hooks/class_performance.md +++ b/events/class_eventtarget.md @@ -1,4 +1,4 @@ diff --git a/events/class_nodeeventtarget_extends_eventtarget.md b/events/class_nodeeventtarget_extends_eventtarget.md new file mode 100644 index 00000000..fa3c34d7 --- /dev/null +++ b/events/class_nodeeventtarget_extends_eventtarget.md @@ -0,0 +1,7 @@ + + +The `NodeEventTarget` is a Node.js-specific extension to `EventTarget` +that emulates a subset of the `EventEmitter` API. + diff --git a/events/event_bubbles.md b/events/event_bubbles.md new file mode 100644 index 00000000..26a1a415 --- /dev/null +++ b/events/event_bubbles.md @@ -0,0 +1,8 @@ + + +* Type: {boolean} Always returns `false`. + +This is not used in Node.js and is provided purely for completeness. + diff --git a/events/event_cancelable.md b/events/event_cancelable.md new file mode 100644 index 00000000..38cb5a5d --- /dev/null +++ b/events/event_cancelable.md @@ -0,0 +1,6 @@ + + +* Type: {boolean} True if the event was created with the `cancelable` option. + diff --git a/events/event_cancelbubble.md b/events/event_cancelbubble.md new file mode 100644 index 00000000..06ae3c5c --- /dev/null +++ b/events/event_cancelbubble.md @@ -0,0 +1,7 @@ + + +Alias for `event.stopPropagation()`. This is not used in Node.js and is +provided purely for completeness. + diff --git a/events/event_composed.md b/events/event_composed.md new file mode 100644 index 00000000..26a1a415 --- /dev/null +++ b/events/event_composed.md @@ -0,0 +1,8 @@ + + +* Type: {boolean} Always returns `false`. + +This is not used in Node.js and is provided purely for completeness. + diff --git a/events/event_composedpath.md b/events/event_composedpath.md new file mode 100644 index 00000000..d46f8c39 --- /dev/null +++ b/events/event_composedpath.md @@ -0,0 +1,8 @@ + + +Returns an array containing the current `EventTarget` as the only entry or +empty if the event is not being dispatched. This is not used in +Node.js and is provided purely for completeness. + diff --git a/events/event_currenttarget.md b/events/event_currenttarget.md new file mode 100644 index 00000000..57020aec --- /dev/null +++ b/events/event_currenttarget.md @@ -0,0 +1,8 @@ + + +* Type: {EventTarget} The `EventTarget` dispatching the event. + +Alias for `event.target`. + diff --git a/events/event_defaultprevented.md b/events/event_defaultprevented.md new file mode 100644 index 00000000..01234a1d --- /dev/null +++ b/events/event_defaultprevented.md @@ -0,0 +1,9 @@ + + +* Type: {boolean} + +Will be `true` if `cancelable` is `true` and `event.preventDefault()` has been +called. + diff --git a/events/event_eventphase.md b/events/event_eventphase.md new file mode 100644 index 00000000..2760ef8a --- /dev/null +++ b/events/event_eventphase.md @@ -0,0 +1,9 @@ + + +* Type: {number} Returns `0` while an event is not being dispatched, `2` while + it is being dispatched. + +This is not used in Node.js and is provided purely for completeness. + diff --git a/events/event_istrusted.md b/events/event_istrusted.md new file mode 100644 index 00000000..26a1a415 --- /dev/null +++ b/events/event_istrusted.md @@ -0,0 +1,8 @@ + + +* Type: {boolean} Always returns `false`. + +This is not used in Node.js and is provided purely for completeness. + diff --git a/events/event_listener.md b/events/event_listener.md new file mode 100644 index 00000000..c6b0f45f --- /dev/null +++ b/events/event_listener.md @@ -0,0 +1,51 @@ + +Event listeners registered for an event `type` may either be JavaScript +functions or objects with a `handleEvent` property whose value is a function. + +In either case, the handler function will be invoked with the `event` argument +passed to the `eventTarget.dispatchEvent()` function. + +Async functions may be used as event listeners. If an async handler function +rejects, the rejection will be captured and be will handled as described in +[`EventTarget` Error Handling][]. + +An error thrown by one handler function will not prevent the other handlers +from being invoked. + +The return value of a handler function will be ignored. + +Handlers are always invoked in the order they were added. + +Handler functions may mutate the `event` object. + +```js +function handler1(event) { + console.log(event.type); // Prints 'foo' + event.a = 1; +} + +async function handler2(event) { + console.log(event.type); // Prints 'foo' + console.log(event.a); // Prints 1 +} + +const handler3 = { + handleEvent(event) { + console.log(event.type); // Prints 'foo' + } +}; + +const handler4 = { + async handleEvent(event) { + console.log(event.type); // Prints 'foo' + } +}; + +const target = getEventTargetSomehow(); + +target.addEventListener('foo', handler1); +target.addEventListener('foo', handler2); +target.addEventListener('foo', handler3); +target.addEventListener('foo', handler4, { once: true }); +``` + diff --git a/events/event_preventdefault.md b/events/event_preventdefault.md new file mode 100644 index 00000000..a99d1aeb --- /dev/null +++ b/events/event_preventdefault.md @@ -0,0 +1,6 @@ + + +Sets the `defaultPrevented` property to `true` if `cancelable` is `true`. + diff --git a/events/event_returnvalue.md b/events/event_returnvalue.md new file mode 100644 index 00000000..2707bce1 --- /dev/null +++ b/events/event_returnvalue.md @@ -0,0 +1,8 @@ + + +* Type: {boolean} True if the event has not been canceled. + +This is not used in Node.js and is provided purely for completeness. + diff --git a/events/event_srcelement.md b/events/event_srcelement.md new file mode 100644 index 00000000..57020aec --- /dev/null +++ b/events/event_srcelement.md @@ -0,0 +1,8 @@ + + +* Type: {EventTarget} The `EventTarget` dispatching the event. + +Alias for `event.target`. + diff --git a/events/event_stopimmediatepropagation.md b/events/event_stopimmediatepropagation.md new file mode 100644 index 00000000..35a59337 --- /dev/null +++ b/events/event_stopimmediatepropagation.md @@ -0,0 +1,6 @@ + + +Stops the invocation of event listeners after the current one completes. + diff --git a/events/event_stoppropagation.md b/events/event_stoppropagation.md new file mode 100644 index 00000000..c511ff92 --- /dev/null +++ b/events/event_stoppropagation.md @@ -0,0 +1,6 @@ + + +This is not used in Node.js and is provided purely for completeness. + diff --git a/events/event_target.md b/events/event_target.md new file mode 100644 index 00000000..b9c92e54 --- /dev/null +++ b/events/event_target.md @@ -0,0 +1,6 @@ + + +* Type: {EventTarget} The `EventTarget` dispatching the event. + diff --git a/events/event_timestamp.md b/events/event_timestamp.md new file mode 100644 index 00000000..b3844426 --- /dev/null +++ b/events/event_timestamp.md @@ -0,0 +1,8 @@ + + +* Type: {number} + +The millisecond timestamp when the `Event` object was created. + diff --git a/events/event_type.md b/events/event_type.md new file mode 100644 index 00000000..a05bc9e7 --- /dev/null +++ b/events/event_type.md @@ -0,0 +1,8 @@ + + +* Type: {string} + +The event type identifier. + diff --git a/events/events_on_emitter_eventname.md b/events/events_on_emitter_eventname.md index 1ea9940c..6829586b 100644 --- a/events/events_on_emitter_eventname.md +++ b/events/events_on_emitter_eventname.md @@ -35,18 +35,3 @@ if the `EventEmitter` emits `'error'`. It removes all listeners when exiting the loop. The `value` returned by each iteration is an array composed of the emitted event arguments. - - - - - - - - - - - - - - - diff --git a/events/eventtarget_addeventlistener_type_listener_options.md b/events/eventtarget_addeventlistener_type_listener_options.md new file mode 100644 index 00000000..c7e3244c --- /dev/null +++ b/events/eventtarget_addeventlistener_type_listener_options.md @@ -0,0 +1,41 @@ + + +* `type` {string} +* `listener` {Function|EventListener} +* `options` {Object} + * `once` {boolean} When `true`, the listener will be automatically removed + when it is first invoked. **Default:** `false`. + * `passive` {boolean} When `true`, serves as a hint that the listener will + not call the `Event` object's `preventDefault()` method. + **Default:** `false`. + * `capture` {boolean} Not directly used by Node.js. Added for API + completeness. **Default:** `false`. + +Adds a new handler for the `type` event. Any given `listener` will be added +only once per `type` and per `capture` option value. + +If the `once` option is `true`, the `listener` will be removed after the +next time a `type` event is dispatched. + +The `capture` option is not used by Node.js in any functional way other than +tracking registered event listeners per the `EventTarget` specification. +Specifically, the `capture` option is used as part of the key when registering +a `listener`. Any individual `listener` may be added once with +`capture = false`, and once with `capture = true`. + +```js +function handler(event) {} + +const target = getEventTargetSomehow(); +target.addEventListener('foo', handler, { capture: true }); // first +target.addEventListener('foo', handler, { capture: false }); // second + +// Removes the second instance of handler +target.removeEventListener('foo', handler); + +// Removes the first instance of handler +target.removeEventListener('foo', handler, { capture: true }); +``` + diff --git a/events/eventtarget_and_event_api.md b/events/eventtarget_and_event_api.md new file mode 100644 index 00000000..d678b52a --- /dev/null +++ b/events/eventtarget_and_event_api.md @@ -0,0 +1,19 @@ + + +> Stability: 1 - Experimental + +The `EventTarget` and `Event` objects are a Node.js-specific implementation +of the [`EventTarget` Web API][] that are exposed by some Node.js core APIs. +Neither the `EventTarget` nor `Event` classes are available for end +user code to create. + +```js +const target = getEventTargetSomehow(); + +target.addEventListener('foo', (event) => { + console.log('foo event happened!'); +}); +``` + diff --git a/events/eventtarget_dispatchevent_event.md b/events/eventtarget_dispatchevent_event.md new file mode 100644 index 00000000..bad8a643 --- /dev/null +++ b/events/eventtarget_dispatchevent_event.md @@ -0,0 +1,13 @@ + + +* `event` {Object|Event} + +Dispatches the `event` to the list of handlers for `event.type`. The `event` +may be an `Event` object or any object with a `type` property whose value is +a `string`. + +The registered event listeners will be synchronously invoked in the order they +were registered. + diff --git a/events/eventtarget_error_handling.md b/events/eventtarget_error_handling.md new file mode 100644 index 00000000..83a5b784 --- /dev/null +++ b/events/eventtarget_error_handling.md @@ -0,0 +1,9 @@ + +When a registered event listener throws (or returns a Promise that rejects), +by default the error will be forwarded to the `process.on('error')` event +on `process.nextTick()`. Throwing within an event listener will *not* stop +the other registered handlers from being invoked. + +The `EventTarget` does not implement any special default handling for +`'error'` type events. + diff --git a/events/eventtarget_removeeventlistener_type_listener.md b/events/eventtarget_removeeventlistener_type_listener.md new file mode 100644 index 00000000..9859f4d4 --- /dev/null +++ b/events/eventtarget_removeeventlistener_type_listener.md @@ -0,0 +1,11 @@ + + +* `type` {string} +* `listener` {Function|EventListener} +* `options` {Object} + * `capture` {boolean} + +Removes the `listener` from the list of handlers for event `type`. + diff --git a/events/node_js_eventtarget_vs_dom_eventtarget.md b/events/node_js_eventtarget_vs_dom_eventtarget.md new file mode 100644 index 00000000..f42ffd5d --- /dev/null +++ b/events/node_js_eventtarget_vs_dom_eventtarget.md @@ -0,0 +1,14 @@ + +There are two key differences between the Node.js `EventTarget` and the +[`EventTarget` Web API][]: + +1. Whereas DOM `EventTarget` instances *may* be hierarchical, there is no + concept of hierarchy and event propagation in Node.js. That is, an event + dispatched to an `EventTarget` does not propagate through a hierarchy of + nested target objects that may each have their own set of handlers for the + event. +2. In the Node.js `EventTarget`, if an event listener is an async function + or returns a `Promise`, and the returned `Promise` rejects, the rejection + will be automatically captured and handled the same way as a listener that + throws synchronously (see [`EventTarget` Error Handling][] for details). + diff --git a/events/nodeeventtarget_addlistener_type_listener_options.md b/events/nodeeventtarget_addlistener_type_listener_options.md new file mode 100644 index 00000000..94deb258 --- /dev/null +++ b/events/nodeeventtarget_addlistener_type_listener_options.md @@ -0,0 +1,16 @@ + + +* `type` {string} +* `listener` {Function|EventListener} +* `options` {Object} + * `once` {boolean} + +* Returns: {EventTarget} this + +Node.js-specific extension to the `EventTarget` class that emulates the +equivalent `EventEmitter` API. The only difference between `addListener()` and +`addEventListener()` is that `addListener()` will return a reference to the +`EventTarget`. + diff --git a/events/nodeeventtarget_eventnames.md b/events/nodeeventtarget_eventnames.md new file mode 100644 index 00000000..a037bb91 --- /dev/null +++ b/events/nodeeventtarget_eventnames.md @@ -0,0 +1,9 @@ + + +* Returns: {string[]} + +Node.js-specific extension to the `EventTarget` class that returns an array +of event `type` names for which event listeners are registered. + diff --git a/events/nodeeventtarget_listenercount_type.md b/events/nodeeventtarget_listenercount_type.md new file mode 100644 index 00000000..ba296e0a --- /dev/null +++ b/events/nodeeventtarget_listenercount_type.md @@ -0,0 +1,11 @@ + + +* `type` {string} + +* Returns: {number} + +Node.js-specific extension to the `EventTarget` class that returns the number +of event listeners registered for the `type`. + diff --git a/events/nodeeventtarget_off_type_listener.md b/events/nodeeventtarget_off_type_listener.md new file mode 100644 index 00000000..d36bf848 --- /dev/null +++ b/events/nodeeventtarget_off_type_listener.md @@ -0,0 +1,11 @@ + + +* `type` {string} +* `listener` {Function|EventListener} + +* Returns: {EventTarget} this + +Node.js-speciic alias for `eventTarget.removeListener()`. + diff --git a/events/nodeeventtarget_on_type_listener_options.md b/events/nodeeventtarget_on_type_listener_options.md new file mode 100644 index 00000000..d8c7c3ae --- /dev/null +++ b/events/nodeeventtarget_on_type_listener_options.md @@ -0,0 +1,13 @@ + + +* `type` {string} +* `listener` {Function|EventListener} +* `options` {Object} + * `once` {boolean} + +* Returns: {EventTarget} this + +Node.js-specific alias for `eventTarget.addListener()`. + diff --git a/events/nodeeventtarget_once_type_listener_options.md b/events/nodeeventtarget_once_type_listener_options.md new file mode 100644 index 00000000..02817ecd --- /dev/null +++ b/events/nodeeventtarget_once_type_listener_options.md @@ -0,0 +1,14 @@ + + +* `type` {string} +* `listener` {Function|EventListener} +* `options` {Object} + +* Returns: {EventTarget} this + +Node.js-specific extension to the `EventTarget` class that adds a `once` +listener for the given event `type`. This is equivalent to calling `on` +with the `once` option set to `true`. + diff --git a/events/nodeeventtarget_removealllisteners_type.md b/events/nodeeventtarget_removealllisteners_type.md new file mode 100644 index 00000000..827bff66 --- /dev/null +++ b/events/nodeeventtarget_removealllisteners_type.md @@ -0,0 +1,10 @@ + + +* `type` {string} + +Node.js-specific extension to the `EventTarget` class. If `type` is specified, +removes all registered listeners for `type`, otherwise removes all registered +listeners. + diff --git a/events/nodeeventtarget_removelistener_type_listener.md b/events/nodeeventtarget_removelistener_type_listener.md new file mode 100644 index 00000000..0b4cd36a --- /dev/null +++ b/events/nodeeventtarget_removelistener_type_listener.md @@ -0,0 +1,32 @@ + + +* `type` {string} +* `listener` {Function|EventListener} + +* Returns: {EventTarget} this + +Node.js-specific extension to the `EventTarget` class that removes the +`listener` for the given `type`. The only difference between `removeListener()` +and `removeEventListener()` is that `removeListener()` will return a reference +to the `EventTarget`. + + + + + + + + + + + + + + + + + + + diff --git a/events/nodeeventtarget_vs_eventemitter.md b/events/nodeeventtarget_vs_eventemitter.md new file mode 100644 index 00000000..5091fa57 --- /dev/null +++ b/events/nodeeventtarget_vs_eventemitter.md @@ -0,0 +1,19 @@ + +The `NodeEventTarget` object implements a modified subset of the +`EventEmitter` API that allows it to closely *emulate* an `EventEmitter` in +certain situations. A `NodeEventTarget` is *not* an instance of `EventEmitter` +and cannot be used in place of an `EventEmitter` in most cases. + +1. Unlike `EventEmitter`, any given `listener` can be registered at most once + per event `type`. Attempts to register a `listener` multiple times will be + ignored. +2. The `NodeEventTarget` does not emulate the full `EventEmitter` API. + Specifically the `prependListener()`, `prependOnceListener()`, + `rawListeners()`, `setMaxListeners()`, `getMaxListeners()`, and + `errorMonitor` APIs are not emulated. The `'newListener'` and + `'removeListener'` events will also not be emitted. +3. The `NodeEventTarget` does not implement any special default behavior + for events with type `'error'`. +3. The `NodeEventTarget` supports `EventListener` objects as well as + functions as handlers for all event types. + diff --git a/fs/fs_constants_1.md b/fs/fs_constants_1.md index 9f45a437..4b0497b2 100644 --- a/fs/fs_constants_1.md +++ b/fs/fs_constants_1.md @@ -3,3 +3,23 @@ 并非所有操作系统都可以使用每个常量。 + +To use more than one constant, use the bitwise OR `|` operator. + +Example: + +```js +const fs = require('fs'); + +const { + O_RDWR, + O_CREAT, + O_EXCL +} = fs.constants; + +fs.open('/path/to/my/file', O_RDWR | O_CREAT | O_EXCL, (err, fd) => { + // ... +}); +``` + + diff --git a/fs/fs_lutimes_path_atime_mtime_callback.md b/fs/fs_lutimes_path_atime_mtime_callback.md new file mode 100644 index 00000000..42a4024b --- /dev/null +++ b/fs/fs_lutimes_path_atime_mtime_callback.md @@ -0,0 +1,18 @@ + + +* `path` {string|Buffer|URL} +* `atime` {number|string|Date} +* `mtime` {number|string|Date} +* `callback` {Function} + * `err` {Error} + +Changes the access and modification times of a file in the same way as +[`fs.utimes()`][], with the difference that if the path refers to a symbolic +link, then the link is not dereferenced: instead, the timestamps of the +symbolic link itself are changed. + +No arguments other than a possible exception are given to the completion +callback. + diff --git a/fs/fs_lutimessync_path_atime_mtime.md b/fs/fs_lutimessync_path_atime_mtime.md new file mode 100644 index 00000000..15486f29 --- /dev/null +++ b/fs/fs_lutimessync_path_atime_mtime.md @@ -0,0 +1,12 @@ + + +* `path` {string|Buffer|URL} +* `atime` {number|string|Date} +* `mtime` {number|string|Date} + +Change the file system timestamps of the symbolic link referenced by `path`. +Returns `undefined`, or throws an exception when parameters are incorrect or +the operation fails. This is the synchronous version of [`fs.lutimes()`][]. + diff --git a/fs/fs_readv_fd_buffers_position_callback.md b/fs/fs_readv_fd_buffers_position_callback.md index fb5d7d91..c0bc5e83 100644 --- a/fs/fs_readv_fd_buffers_position_callback.md +++ b/fs/fs_readv_fd_buffers_position_callback.md @@ -20,3 +20,6 @@ from the current position. The callback will be given three arguments: `err`, `bytesRead`, and `buffers`. `bytesRead` is how many bytes were read from the file. +If this method is invoked as its [`util.promisify()`][]ed version, it returns +a `Promise` for an `Object` with `bytesRead` and `buffers` properties. + diff --git a/fs/fs_stat_path_options_callback.md b/fs/fs_stat_path_options_callback.md index 34ff27eb..10d3d8ab 100644 --- a/fs/fs_stat_path_options_callback.md +++ b/fs/fs_stat_path_options_callback.md @@ -38,7 +38,7 @@ changes: 例如，给定以下的目录结构： -```fundamental +```text - 目录 -- 文件.txt - 文件.js diff --git a/fs/fspromises_lutimes_path_atime_mtime.md b/fs/fspromises_lutimes_path_atime_mtime.md new file mode 100644 index 00000000..68206a12 --- /dev/null +++ b/fs/fspromises_lutimes_path_atime_mtime.md @@ -0,0 +1,16 @@ + + +* `path` {string|Buffer|URL} +* `atime` {number|string|Date} +* `mtime` {number|string|Date} +* Returns: {Promise} + +Changes the access and modification times of a file in the same way as +[`fsPromises.utimes()`][], with the difference that if the path refers to a +symbolic link, then the link is not dereferenced: instead, the timestamps of +the symbolic link itself are changed. + +Upon success, the `Promise` is resolved without arguments. + diff --git a/fs/using_fs_writefile_with_file_descriptors.md b/fs/using_fs_writefile_with_file_descriptors.md index 3fe81b6e..18d15a1f 100644 --- a/fs/using_fs_writefile_with_file_descriptors.md +++ b/fs/using_fs_writefile_with_file_descriptors.md @@ -1,7 +1,7 @@ 当 `file` 是一个文件描述符时，行为几乎与直接调用 `fs.write()` 类似： -```javascript +```js fs.write(fd, Buffer.from(data, options.encoding), callback); ``` diff --git a/http/agent_maxtotalsockets.md b/http/agent_maxtotalsockets.md new file mode 100644 index 00000000..e07cb1df --- /dev/null +++ b/http/agent_maxtotalsockets.md @@ -0,0 +1,9 @@ + + +* {number} + +By default set to `Infinity`. Determines how many concurrent sockets the agent +can have open. Unlike `maxSockets`, this parameter applies across all origins. + diff --git a/http/message_destroy_error.md b/http/message_destroy_error.md index 7fcaf976..7b94ef2b 100644 --- a/http/message_destroy_error.md +++ b/http/message_destroy_error.md @@ -1,8 +1,14 @@ * `error` {Error} +* 返回: {this} 在接收到 `IncomingMessage` 的套接字上调用 `destroy()`。 diff --git a/http/message_url.md b/http/message_url.md index e092f8ca..6f32ecf1 100644 --- a/http/message_url.md +++ b/http/message_url.md @@ -10,7 +10,7 @@ added: v0.1.90 它仅包含实际的 HTTP 请求中存在的 URL。 如果请求是： -```txt +```http GET /status?name=ryan HTTP/1.1\r\n Accept: text/plain\r\n \r\n diff --git a/http/new_agent_options.md b/http/new_agent_options.md index 389ee25d..a49fe5d7 100644 --- a/http/new_agent_options.md +++ b/http/new_agent_options.md @@ -1,5 +1,10 @@ * `options` {Object} 要在代理上设置的可配置选项集。可以包含以下字段： @@ -10,6 +15,18 @@ added: v0.3.4 * `keepAliveMsecs` {number} 当使用 `keepAlive` 选项时，指定用于 TCP Keep-Alive 数据包的[初始延迟][initial delay]。当 `keepAlive` 选项为 `false` 或 `undefined` 时则忽略。**默认值:** `1000`。 * `maxSockets` {number} 每个主机允许的套接字的最大数量。**默认值:** `Infinity`。 * `maxFreeSockets` {number} 在空闲状态下保持打开的套接字的最大数量。仅当 `keepAlive` 被设置为 `true` 时才相关。**默认值:** `256`。 + * `scheduling` {string} Scheduling strategy to apply when picking + the next free socket to use. It can be `'fifo'` or `'lifo'`. + The main difference between the two scheduling strategies is that `'lifo'` + selects the most recently used socket, while `'fifo'` selects + the least recently used socket. + In case of a low rate of request per second, the `'lifo'` scheduling + will lower the risk of picking a socket that might have been closed + by the server due to inactivity. + In case of a high rate of request per second, + the `'fifo'` scheduling will maximize the number of open sockets, + while the `'lifo'` scheduling will keep it as low as possible. + **Default:** `'fifo'`. * `timeout` {number} 套接字的超时时间，以毫秒为单位。这会在套接字被连接之后设置超时时间。 [`socket.connect()`] 中的 `options` 也受支持。 diff --git a/http/request_destroy_error.md b/http/request_destroy_error.md index 9a0e7953..1e03c102 100644 --- a/http/request_destroy_error.md +++ b/http/request_destroy_error.md @@ -1,5 +1,10 @@ * `error` {Error} Optional, an error to emit with `'error'` event. diff --git a/http/request_host.md b/http/request_host.md new file mode 100644 index 00000000..1fe15b0d --- /dev/null +++ b/http/request_host.md @@ -0,0 +1,6 @@ + + +* {string} The request host. + diff --git a/http/request_method.md b/http/request_method.md new file mode 100644 index 00000000..b381b322 --- /dev/null +++ b/http/request_method.md @@ -0,0 +1,6 @@ + + +* {string} The request method. + diff --git a/http/request_protocol.md b/http/request_protocol.md new file mode 100644 index 00000000..4f500d39 --- /dev/null +++ b/http/request_protocol.md @@ -0,0 +1,6 @@ + + +* {string} The request protocol. + diff --git a/http2/collecting_http_2_performance_metrics.md b/http2/collecting_http_2_performance_metrics.md index b50d542c..e7b971a5 100644 --- a/http2/collecting_http_2_performance_metrics.md +++ b/http2/collecting_http_2_performance_metrics.md @@ -108,6 +108,8 @@ following additional properties: + + diff --git a/http2/http2_connect_authority_options_listener.md b/http2/http2_connect_authority_options_listener.md index 782b9392..fad93726 100644 --- a/http2/http2_connect_authority_options_listener.md +++ b/http2/http2_connect_authority_options_listener.md @@ -40,7 +40,9 @@ changes: queued to be sent, and unacknowledged `PING` and `SETTINGS` frames are all counted towards the current limit. **Default:** `10`. * `maxHeaderListPairs` {number} Sets the maximum number of header entries. - The minimum value is `1`. **Default:** `128`. + This is similar to [`http.Server#maxHeadersCount`][] or + [`http.ClientRequest#maxHeadersCount`][]. The minimum value is `1`. + **Default:** `128`. * `maxOutstandingPings` {number} Sets the maximum number of outstanding, unacknowledged pings. **Default:** `10`. * `maxReservedRemoteStreams` {number} Sets the maximum number of reserved push diff --git a/http2/http2_createsecureserver_options_onrequesthandler.md b/http2/http2_createsecureserver_options_onrequesthandler.md index 5a54a1e8..31fc9336 100644 --- a/http2/http2_createsecureserver_options_onrequesthandler.md +++ b/http2/http2_createsecureserver_options_onrequesthandler.md @@ -53,7 +53,9 @@ changes: queued to be sent, and unacknowledged `PING` and `SETTINGS` frames are all counted towards the current limit. **Default:** `10`. * `maxHeaderListPairs` {number} Sets the maximum number of header entries. - The minimum value is `4`. **Default:** `128`. + This is similar to [`http.Server#maxHeadersCount`][] or + [`http.ClientRequest#maxHeadersCount`][]. The minimum value is `4`. + **Default:** `128`. * `maxOutstandingPings` {number} Sets the maximum number of outstanding, unacknowledged pings. **Default:** `10`. * `maxSendHeaderBlockLength` {number} Sets the maximum allowed size for a diff --git a/http2/http2_createserver_options_onrequesthandler.md b/http2/http2_createserver_options_onrequesthandler.md index b87b3b28..960d00fa 100644 --- a/http2/http2_createserver_options_onrequesthandler.md +++ b/http2/http2_createserver_options_onrequesthandler.md @@ -53,7 +53,9 @@ changes: queued to be sent, and unacknowledged `PING` and `SETTINGS` frames are all counted towards the current limit. **Default:** `10`. * `maxHeaderListPairs` {number} Sets the maximum number of header entries. - The minimum value is `4`. **Default:** `128`. + This is similar to [`http.Server#maxHeadersCount`][] or + [`http.ClientRequest#maxHeadersCount`][]. The minimum value is `4`. + **Default:** `128`. * `maxOutstandingPings` {number} Sets the maximum number of outstanding, unacknowledged pings. **Default:** `10`. * `maxSendHeaderBlockLength` {number} Sets the maximum allowed size for a diff --git a/http2/http2stream_respond_headers_options.md b/http2/http2stream_respond_headers_options.md index a0521ce3..621cd595 100644 --- a/http2/http2stream_respond_headers_options.md +++ b/http2/http2stream_respond_headers_options.md @@ -1,5 +1,9 @@ * `headers` {HTTP/2 Headers Object} diff --git a/http2/http2stream_respondwithfd_fd_headers_options.md b/http2/http2stream_respondwithfd_fd_headers_options.md index 97087593..b64f3f4c 100644 --- a/http2/http2stream_respondwithfd_fd_headers_options.md +++ b/http2/http2stream_respondwithfd_fd_headers_options.md @@ -1,6 +1,9 @@ + +* {string} + +The directory name of the module. This is usually the same as the +[`path.dirname()`][] of the [`module.id`][]. + diff --git a/modules/require_main.md b/modules/require_main.md index 4aa9bc23..d96fb068 100644 --- a/modules/require_main.md +++ b/modules/require_main.md @@ -13,7 +13,7 @@ added: v0.1.17 console.log(require.main); ``` -```sh +```bash node entry.js ``` @@ -21,6 +21,7 @@ node entry.js ```js Module { id: '.', + path: '/absolute/path/to', exports: {}, parent: null, filename: '/absolute/path/to/entry.js', diff --git a/modules/sourcemap_findentry_linenumber_columnnumber.md b/modules/sourcemap_findentry_linenumber_columnnumber.md index 0f8d08c7..4e896384 100644 --- a/modules/sourcemap_findentry_linenumber_columnnumber.md +++ b/modules/sourcemap_findentry_linenumber_columnnumber.md @@ -31,4 +31,5 @@ consists of the following keys: + diff --git a/n-api/asynchronous_thread_safe_function_calls.md b/n-api/asynchronous_thread_safe_function_calls.md index 831c530a..d8b3a605 100644 --- a/n-api/asynchronous_thread_safe_function_calls.md +++ b/n-api/asynchronous_thread_safe_function_calls.md @@ -30,90 +30,3 @@ The `context` given during the call to `napi_create_threadsafe_function()` can be retrieved from any thread with a call to `napi_get_threadsafe_function_context()`. -`napi_call_threadsafe_function()` can then be used for initiating a call into -JavaScript. `napi_call_threadsafe_function()` accepts a parameter which controls -whether the API behaves blockingly. If set to `napi_tsfn_nonblocking`, the API -behaves non-blockingly, returning `napi_queue_full` if the queue was full, -preventing data from being successfully added to the queue. If set to -`napi_tsfn_blocking`, the API blocks until space becomes available in the queue. -`napi_call_threadsafe_function()` never blocks if the thread-safe function was -created with a maximum queue size of 0. - -As a special case, when `napi_call_threadsafe_function()` is called from a -JavaScript thread, it will return `napi_would_deadlock` if the queue is full -and it was called with `napi_tsfn_blocking`. The reason for this is that the -JavaScript thread is responsible for removing items from the queue, thereby -reducing their number. Thus, if it waits for room to become available on the -queue, then it will deadlock. - -`napi_call_threadsafe_function()` will also return `napi_would_deadlock` if the -thread-safe function created on one JavaScript thread is called from another -JavaScript thread. The reason for this is to prevent a deadlock arising from the -possibility that the two JavaScript threads end up waiting on one another, -thereby both deadlocking. - -The actual call into JavaScript is controlled by the callback given via the -`call_js_cb` parameter. `call_js_cb` is invoked on the main thread once for each -value that was placed into the queue by a successful call to -`napi_call_threadsafe_function()`. If such a callback is not given, a default -callback will be used, and the resulting JavaScript call will have no arguments. -The `call_js_cb` callback receives the JavaScript function to call as a -`napi_value` in its parameters, as well as the `void*` context pointer used when -creating the `napi_threadsafe_function`, and the next data pointer that was -created by one of the secondary threads. The callback can then use an API such -as `napi_call_function()` to call into JavaScript. - -The callback may also be invoked with `env` and `call_js_cb` both set to `NULL` -to indicate that calls into JavaScript are no longer possible, while items -remain in the queue that may need to be freed. This normally occurs when the -Node.js process exits while there is a thread-safe function still active. - -It is not necessary to call into JavaScript via `napi_make_callback()` because -N-API runs `call_js_cb` in a context appropriate for callbacks. - -Threads can be added to and removed from a `napi_threadsafe_function` object -during its existence. Thus, in addition to specifying an initial number of -threads upon creation, `napi_acquire_threadsafe_function` can be called to -indicate that a new thread will start making use of the thread-safe function. -Similarly, `napi_release_threadsafe_function` can be called to indicate that an -existing thread will stop making use of the thread-safe function. - -`napi_threadsafe_function` objects are destroyed when every thread which uses -the object has called `napi_release_threadsafe_function()` or has received a -return status of `napi_closing` in response to a call to -`napi_call_threadsafe_function`. The queue is emptied before the -`napi_threadsafe_function` is destroyed. `napi_release_threadsafe_function()` -should be the last API call made in conjunction with a given -`napi_threadsafe_function`, because after the call completes, there is no -guarantee that the `napi_threadsafe_function` is still allocated. For the same -reason, do not make use of a thread-safe function -after receiving a return value of `napi_closing` in response to a call to -`napi_call_threadsafe_function`. Data associated with the -`napi_threadsafe_function` can be freed in its `napi_finalize` callback which -was passed to `napi_create_threadsafe_function()`. - -Once the number of threads making use of a `napi_threadsafe_function` reaches -zero, no further threads can start making use of it by calling -`napi_acquire_threadsafe_function()`. In fact, all subsequent API calls -associated with it, except `napi_release_threadsafe_function()`, will return an -error value of `napi_closing`. - -The thread-safe function can be "aborted" by giving a value of `napi_tsfn_abort` -to `napi_release_threadsafe_function()`. This will cause all subsequent APIs -associated with the thread-safe function except -`napi_release_threadsafe_function()` to return `napi_closing` even before its -reference count reaches zero. In particular, `napi_call_threadsafe_function()` -will return `napi_closing`, thus informing the threads that it is no longer -possible to make asynchronous calls to the thread-safe function. This can be -used as a criterion for terminating the thread. **Upon receiving a return value -of `napi_closing` from `napi_call_threadsafe_function()` a thread must make no -further use of the thread-safe function because it is no longer guaranteed to -be allocated.** - -Similarly to libuv handles, thread-safe functions can be "referenced" and -"unreferenced". A "referenced" thread-safe function will cause the event loop on -the thread on which it is created to remain alive until the thread-safe function -is destroyed. In contrast, an "unreferenced" thread-safe function will not -prevent the event loop from exiting. The APIs `napi_ref_threadsafe_function` and -`napi_unref_threadsafe_function` exist for this purpose. - diff --git a/n-api/calling_a_thread_safe_function.md b/n-api/calling_a_thread_safe_function.md new file mode 100644 index 00000000..15e4c0a3 --- /dev/null +++ b/n-api/calling_a_thread_safe_function.md @@ -0,0 +1,33 @@ + +`napi_call_threadsafe_function()` can be used for initiating a call into +JavaScript. `napi_call_threadsafe_function()` accepts a parameter which controls +whether the API behaves blockingly. If set to `napi_tsfn_nonblocking`, the API +behaves non-blockingly, returning `napi_queue_full` if the queue was full, +preventing data from being successfully added to the queue. If set to +`napi_tsfn_blocking`, the API blocks until space becomes available in the queue. +`napi_call_threadsafe_function()` never blocks if the thread-safe function was +created with a maximum queue size of 0. + +`napi_call_threadsafe_function()` should not be called with `napi_tsfn_blocking` +from a JavaScript thread, because, if the queue is full, it may cause the +JavaScript thread to deadlock. + +The actual call into JavaScript is controlled by the callback given via the +`call_js_cb` parameter. `call_js_cb` is invoked on the main thread once for each +value that was placed into the queue by a successful call to +`napi_call_threadsafe_function()`. If such a callback is not given, a default +callback will be used, and the resulting JavaScript call will have no arguments. +The `call_js_cb` callback receives the JavaScript function to call as a +`napi_value` in its parameters, as well as the `void*` context pointer used when +creating the `napi_threadsafe_function`, and the next data pointer that was +created by one of the secondary threads. The callback can then use an API such +as `napi_call_function()` to call into JavaScript. + +The callback may also be invoked with `env` and `call_js_cb` both set to `NULL` +to indicate that calls into JavaScript are no longer possible, while items +remain in the queue that may need to be freed. This normally occurs when the +Node.js process exits while there is a thread-safe function still active. + +It is not necessary to call into JavaScript via `napi_make_callback()` because +N-API runs `call_js_cb` in a context appropriate for callbacks. + diff --git a/n-api/deciding_whether_to_keep_the_process_running.md b/n-api/deciding_whether_to_keep_the_process_running.md new file mode 100644 index 00000000..28774be8 --- /dev/null +++ b/n-api/deciding_whether_to_keep_the_process_running.md @@ -0,0 +1,12 @@ + +Similarly to libuv handles, thread-safe functions can be "referenced" and +"unreferenced". A "referenced" thread-safe function will cause the event loop on +the thread on which it is created to remain alive until the thread-safe function +is destroyed. In contrast, an "unreferenced" thread-safe function will not +prevent the event loop from exiting. The APIs `napi_ref_threadsafe_function` and +`napi_unref_threadsafe_function` exist for this purpose. + +Neither does `napi_unref_threadsafe_function` mark the thread-safe functions as +able to be destroyed nor does `napi_ref_threadsafe_function` prevent it from +being destroyed. + diff --git a/n-api/implications_of_abi_stability.md b/n-api/implications_of_abi_stability.md index 52c28ba5..1987fb65 100644 --- a/n-api/implications_of_abi_stability.md +++ b/n-api/implications_of_abi_stability.md @@ -6,7 +6,7 @@ versions: * the Node.js C++ APIs available via any of - ```C++ + ```cpp #include #include #include @@ -15,20 +15,20 @@ versions: * the libuv APIs which are also included with Node.js and available via - ```C++ + ```cpp #include ``` * the V8 API available via - ```C++ + ```cpp #include ``` Thus, for an addon to remain ABI-compatible across Node.js major versions, it must make use exclusively of N-API by restricting itself to using -```C +```c #include ``` diff --git a/n-api/making_handle_lifespan_shorter_than_that_of_the_native_method.md b/n-api/making_handle_lifespan_shorter_than_that_of_the_native_method.md index 3f83ac5c..05a743fe 100644 --- a/n-api/making_handle_lifespan_shorter_than_that_of_the_native_method.md +++ b/n-api/making_handle_lifespan_shorter_than_that_of_the_native_method.md @@ -2,7 +2,7 @@ It is often necessary to make the lifespan of handles shorter than the lifespan of a native method. For example, consider a native method that has a loop which iterates through the elements in a large array: -```C +```c for (int i = 0; i < 1000000; i++) { napi_value result; napi_status status = napi_get_element(env, object, i, &result); @@ -34,7 +34,7 @@ Taking the earlier example, adding calls to [`napi_open_handle_scope`][] and [`napi_close_handle_scope`][] would ensure that at most a single handle is valid throughout the execution of the loop: -```C +```c for (int i = 0; i < 1000000; i++) { napi_handle_scope scope; napi_status status = napi_open_handle_scope(env, &scope); diff --git a/n-api/module_registration.md b/n-api/module_registration.md index b93c268e..e027249e 100644 --- a/n-api/module_registration.md +++ b/n-api/module_registration.md @@ -2,14 +2,14 @@ N-API modules are registered in a manner similar to other modules except that instead of using the `NODE_MODULE` macro the following is used: -```C +```c NAPI_MODULE(NODE_GYP_MODULE_NAME, Init) ``` The next difference is the signature for the `Init` method. For a N-API module it is as follows: -```C +```c napi_value Init(napi_env env, napi_value exports); ``` @@ -22,7 +22,7 @@ specify anything as the `exports` property of the module. To add the method `hello` as a function so that it can be called as a method provided by the addon: -```C +```c napi_value Init(napi_env env, napi_value exports) { napi_status status; napi_property_descriptor desc = @@ -35,7 +35,7 @@ napi_value Init(napi_env env, napi_value exports) { To set a function to be returned by the `require()` for the addon: -```C +```c napi_value Init(napi_env env, napi_value exports) { napi_value method; napi_status status; @@ -48,7 +48,7 @@ napi_value Init(napi_env env, napi_value exports) { To define a class so that new instances can be created (often used with [Object Wrap][]): -```C +```c // NOTE: partial example, not all referenced code is included napi_value Init(napi_env env, napi_value exports) { napi_status status; @@ -76,7 +76,7 @@ napi_value Init(napi_env env, napi_value exports) { If the module will be loaded multiple times during the lifetime of the Node.js process, use the `NAPI_MODULE_INIT` macro to initialize the module: -```C +```c NAPI_MODULE_INIT() { napi_value answer; napi_status result; diff --git a/n-api/n_api.md b/n-api/n_api.md index da584e1e..e051ddfd 100644 --- a/n-api/n_api.md +++ b/n-api/n_api.md @@ -44,12 +44,12 @@ following `node-addon-api` code. The first section shows the `node-addon-api` code and the second section shows what actually gets used in the addon. -```C++ +```cpp Object obj = Object::New(env); obj["foo"] = String::New(env, "bar"); ``` -```C++ +```cpp napi_status status; napi_value object, string; status = napi_create_object(env, &object); diff --git a/n-api/n_api_version_matrix.md b/n-api/n_api_version_matrix.md index a1e3772e..1a3be104 100644 --- a/n-api/n_api_version_matrix.md +++ b/n-api/n_api_version_matrix.md @@ -36,7 +36,7 @@ N-API or any implementation of N-API outside of Node.js. to the addon and which instantiates the addon by calling into `addon.c` when the addon is loaded into a Node.js environment. -```C +```c // addon.h #ifndef _ADDON_H_ #define _ADDON_H_ @@ -45,7 +45,7 @@ napi_value create_addon(napi_env env); #endif // _ADDON_H_ ``` -```C +```c // addon.c #include "addon.h" @@ -94,7 +94,7 @@ napi_value create_addon(napi_env env) { } ``` -```C +```c // addon_node.c #include #include "addon.h" diff --git a/n-api/napi_acquire_threadsafe_function.md b/n-api/napi_acquire_threadsafe_function.md index 3ca25845..7a1047fd 100644 --- a/n-api/napi_acquire_threadsafe_function.md +++ b/n-api/napi_acquire_threadsafe_function.md @@ -4,7 +4,7 @@ added: v10.6.0 napiVersion: 4 --> -```C +```c NAPI_EXTERN napi_status napi_acquire_threadsafe_function(napi_threadsafe_function func); ``` diff --git a/n-api/napi_add_env_cleanup_hook.md b/n-api/napi_add_env_cleanup_hook.md index a1dc36ff..0fea5a6a 100644 --- a/n-api/napi_add_env_cleanup_hook.md +++ b/n-api/napi_add_env_cleanup_hook.md @@ -3,7 +3,7 @@ added: v10.2.0 napiVersion: 3 --> -```C +```c NODE_EXTERN napi_status napi_add_env_cleanup_hook(napi_env env, void (*fun)(void* arg), void* arg); diff --git a/n-api/napi_add_finalizer.md b/n-api/napi_add_finalizer.md index 6e038235..cb03edfb 100644 --- a/n-api/napi_add_finalizer.md +++ b/n-api/napi_add_finalizer.md @@ -4,7 +4,7 @@ added: v8.0.0 napiVersion: 5 --> -```C +```c napi_status napi_add_finalizer(napi_env env, napi_value js_object, void* native_object, diff --git a/n-api/napi_adjust_external_memory.md b/n-api/napi_adjust_external_memory.md index 185746ed..45efb6d7 100644 --- a/n-api/napi_adjust_external_memory.md +++ b/n-api/napi_adjust_external_memory.md @@ -3,7 +3,7 @@ added: v8.5.0 napiVersion: 1 --> -```C +```c NAPI_EXTERN napi_status napi_adjust_external_memory(napi_env env, int64_t change_in_bytes, int64_t* result); diff --git a/n-api/napi_async_complete_callback.md b/n-api/napi_async_complete_callback.md index a7232316..93ffcb32 100644 --- a/n-api/napi_async_complete_callback.md +++ b/n-api/napi_async_complete_callback.md @@ -5,7 +5,7 @@ napiVersion: 1 Function pointer used with functions that support asynchronous operations. Callback functions must satisfy the following signature: -```C +```c typedef void (*napi_async_complete_callback)(napi_env env, napi_status status, void* data); diff --git a/n-api/napi_async_destroy.md b/n-api/napi_async_destroy.md index 2f4c9865..854b4596 100644 --- a/n-api/napi_async_destroy.md +++ b/n-api/napi_async_destroy.md @@ -3,7 +3,7 @@ added: v8.6.0 napiVersion: 1 --> -```C +```c napi_status napi_async_destroy(napi_env env, napi_async_context async_context); ``` diff --git a/n-api/napi_async_execute_callback.md b/n-api/napi_async_execute_callback.md index 221cd99f..580058f4 100644 --- a/n-api/napi_async_execute_callback.md +++ b/n-api/napi_async_execute_callback.md @@ -5,13 +5,13 @@ napiVersion: 1 Function pointer used with functions that support asynchronous operations. Callback functions must satisfy the following signature: -```C +```c typedef void (*napi_async_execute_callback)(napi_env env, void* data); ``` Implementations of this function must avoid making N-API calls that execute JavaScript or interact with -JavaScript objects. N-API +JavaScript objects. N-API calls should be in the `napi_async_complete_callback` instead. Do not use the `napi_env` parameter as it will likely result in execution of JavaScript. diff --git a/n-api/napi_async_init.md b/n-api/napi_async_init.md index 69c5f849..3ed03976 100644 --- a/n-api/napi_async_init.md +++ b/n-api/napi_async_init.md @@ -3,7 +3,7 @@ added: v8.6.0 napiVersion: 1 --> -```C +```c napi_status napi_async_init(napi_env env, napi_value async_resource, napi_value async_resource_name, diff --git a/n-api/napi_call_function.md b/n-api/napi_call_function.md index 17c7af05..5bdf1517 100644 --- a/n-api/napi_call_function.md +++ b/n-api/napi_call_function.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c NAPI_EXTERN napi_status napi_call_function(napi_env env, napi_value recv, napi_value func, @@ -39,7 +39,7 @@ function AddTwo(num) { Then, the above function can be invoked from a native add-on using the following code: -```C +```c // Get the function named "AddTwo" on the global object napi_value global, add_two, arg; napi_status status = napi_get_global(env, &global); diff --git a/n-api/napi_call_threadsafe_function.md b/n-api/napi_call_threadsafe_function.md index 36bdec97..0ecd7d80 100644 --- a/n-api/napi_call_threadsafe_function.md +++ b/n-api/napi_call_threadsafe_function.md @@ -3,6 +3,10 @@ added: v10.6.0 napiVersion: 4 changes: + - version: v14.5.0 + pr-url: https://github.com/nodejs/node/pull/33453 + description: > + Support for `napi_would_deadlock` has been reverted. - version: v14.1.0 pr-url: https://github.com/nodejs/node/pull/32689 description: > @@ -10,7 +14,7 @@ changes: the main thread or a worker thread and the queue is full. --> -```C +```c NAPI_EXTERN napi_status napi_call_threadsafe_function(napi_threadsafe_function func, void* data, @@ -25,13 +29,13 @@ napi_call_threadsafe_function(napi_threadsafe_function func, `napi_tsfn_nonblocking` to indicate that the call should return immediately with a status of `napi_queue_full` whenever the queue is full. -This API will return `napi_would_deadlock` if called with `napi_tsfn_blocking` -from the main thread and the queue is full. +This API should not be called with `napi_tsfn_blocking` from a JavaScript +thread, because, if the queue is full, it may cause the JavaScript thread to +deadlock. This API will return `napi_closing` if `napi_release_threadsafe_function()` was -called with `abort` set to `napi_tsfn_abort` from any thread. - -The value is only added to the queue if the API returns `napi_ok`. +called with `abort` set to `napi_tsfn_abort` from any thread. The value is only +added to the queue if the API returns `napi_ok`. This API may be called from any thread which makes use of `func`. diff --git a/n-api/napi_callback.md b/n-api/napi_callback.md index 317117d2..1cacc47b 100644 --- a/n-api/napi_callback.md +++ b/n-api/napi_callback.md @@ -6,7 +6,7 @@ Function pointer type for user-provided native functions which are to be exposed to JavaScript via N-API. Callback functions should satisfy the following signature: -```C +```c typedef napi_value (*napi_callback)(napi_env, napi_callback_info); ``` diff --git a/n-api/napi_cancel_async_work.md b/n-api/napi_cancel_async_work.md index 3f829e93..39d1acb5 100644 --- a/n-api/napi_cancel_async_work.md +++ b/n-api/napi_cancel_async_work.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_cancel_async_work(napi_env env, napi_async_work work); ``` diff --git a/n-api/napi_close_callback_scope.md b/n-api/napi_close_callback_scope.md index 9878db23..b9f900e6 100644 --- a/n-api/napi_close_callback_scope.md +++ b/n-api/napi_close_callback_scope.md @@ -3,7 +3,7 @@ added: v9.6.0 napiVersion: 3 --> -```C +```c NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env, napi_callback_scope scope) ``` diff --git a/n-api/napi_close_escapable_handle_scope.md b/n-api/napi_close_escapable_handle_scope.md index a422408f..d2ea45a5 100644 --- a/n-api/napi_close_escapable_handle_scope.md +++ b/n-api/napi_close_escapable_handle_scope.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c NAPI_EXTERN napi_status napi_close_escapable_handle_scope(napi_env env, napi_handle_scope scope); diff --git a/n-api/napi_close_handle_scope.md b/n-api/napi_close_handle_scope.md index d7981c57..16a3337a 100644 --- a/n-api/napi_close_handle_scope.md +++ b/n-api/napi_close_handle_scope.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c NAPI_EXTERN napi_status napi_close_handle_scope(napi_env env, napi_handle_scope scope); ``` diff --git a/n-api/napi_coerce_to_bool.md b/n-api/napi_coerce_to_bool.md index bc9d0822..a24a689a 100644 --- a/n-api/napi_coerce_to_bool.md +++ b/n-api/napi_coerce_to_bool.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_coerce_to_bool(napi_env env, napi_value value, napi_value* result) diff --git a/n-api/napi_coerce_to_number.md b/n-api/napi_coerce_to_number.md index 6b7cfb5e..8a81b2de 100644 --- a/n-api/napi_coerce_to_number.md +++ b/n-api/napi_coerce_to_number.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_coerce_to_number(napi_env env, napi_value value, napi_value* result) diff --git a/n-api/napi_coerce_to_object.md b/n-api/napi_coerce_to_object.md index e4416598..7916b58f 100644 --- a/n-api/napi_coerce_to_object.md +++ b/n-api/napi_coerce_to_object.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_coerce_to_object(napi_env env, napi_value value, napi_value* result) diff --git a/n-api/napi_coerce_to_string.md b/n-api/napi_coerce_to_string.md index d54f745b..6f99ea1a 100644 --- a/n-api/napi_coerce_to_string.md +++ b/n-api/napi_coerce_to_string.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_coerce_to_string(napi_env env, napi_value value, napi_value* result) diff --git a/n-api/napi_create_array.md b/n-api/napi_create_array.md index 15ad761b..c9c209a3 100644 --- a/n-api/napi_create_array.md +++ b/n-api/napi_create_array.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_create_array(napi_env env, napi_value* result) ``` diff --git a/n-api/napi_create_array_with_length.md b/n-api/napi_create_array_with_length.md index 6d8bbe8f..cc2f1e94 100644 --- a/n-api/napi_create_array_with_length.md +++ b/n-api/napi_create_array_with_length.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_create_array_with_length(napi_env env, size_t length, napi_value* result) diff --git a/n-api/napi_create_arraybuffer.md b/n-api/napi_create_arraybuffer.md index de99f455..6cea2039 100644 --- a/n-api/napi_create_arraybuffer.md +++ b/n-api/napi_create_arraybuffer.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_create_arraybuffer(napi_env env, size_t byte_length, void** data, diff --git a/n-api/napi_create_async_work.md b/n-api/napi_create_async_work.md index 9d6cf69f..d02957f1 100644 --- a/n-api/napi_create_async_work.md +++ b/n-api/napi_create_async_work.md @@ -7,7 +7,7 @@ changes: description: Added `async_resource` and `async_resource_name` parameters. --> -```C +```c napi_status napi_create_async_work(napi_env env, napi_value async_resource, napi_value async_resource_name, diff --git a/n-api/napi_create_bigint_int64.md b/n-api/napi_create_bigint_int64.md index 476ca4e9..8aa16655 100644 --- a/n-api/napi_create_bigint_int64.md +++ b/n-api/napi_create_bigint_int64.md @@ -3,7 +3,7 @@ added: v10.7.0 napiVersion: 6 --> -```C +```c napi_status napi_create_bigint_int64(napi_env env, int64_t value, napi_value* result); diff --git a/n-api/napi_create_bigint_uint64.md b/n-api/napi_create_bigint_uint64.md index 6eeec674..65b9ddfd 100644 --- a/n-api/napi_create_bigint_uint64.md +++ b/n-api/napi_create_bigint_uint64.md @@ -3,7 +3,7 @@ added: v10.7.0 napiVersion: 6 --> -```C +```c napi_status napi_create_bigint_uint64(napi_env env, uint64_t value, napi_value* result); diff --git a/n-api/napi_create_bigint_words.md b/n-api/napi_create_bigint_words.md index f1088a65..9d3b2978 100644 --- a/n-api/napi_create_bigint_words.md +++ b/n-api/napi_create_bigint_words.md @@ -3,7 +3,7 @@ added: v10.7.0 napiVersion: 6 --> -```C +```c napi_status napi_create_bigint_words(napi_env env, int sign_bit, size_t word_count, diff --git a/n-api/napi_create_buffer.md b/n-api/napi_create_buffer.md index 897b18dd..a97823dd 100644 --- a/n-api/napi_create_buffer.md +++ b/n-api/napi_create_buffer.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_create_buffer(napi_env env, size_t size, void** data, diff --git a/n-api/napi_create_buffer_copy.md b/n-api/napi_create_buffer_copy.md index 0e0f7030..866be4ed 100644 --- a/n-api/napi_create_buffer_copy.md +++ b/n-api/napi_create_buffer_copy.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_create_buffer_copy(napi_env env, size_t length, const void* data, diff --git a/n-api/napi_create_dataview.md b/n-api/napi_create_dataview.md index 31d80444..3c57fa71 100644 --- a/n-api/napi_create_dataview.md +++ b/n-api/napi_create_dataview.md @@ -3,7 +3,7 @@ added: v8.3.0 napiVersion: 1 --> -```C +```c napi_status napi_create_dataview(napi_env env, size_t byte_length, napi_value arraybuffer, diff --git a/n-api/napi_create_date.md b/n-api/napi_create_date.md index 6fde0339..d285c42c 100644 --- a/n-api/napi_create_date.md +++ b/n-api/napi_create_date.md @@ -5,7 +5,7 @@ added: napiVersion: 5 --> -```C +```c napi_status napi_create_date(napi_env env, double time, napi_value* result); diff --git a/n-api/napi_create_double.md b/n-api/napi_create_double.md index 4d7ece98..6a1c6315 100644 --- a/n-api/napi_create_double.md +++ b/n-api/napi_create_double.md @@ -3,7 +3,7 @@ added: v8.4.0 napiVersion: 1 --> -```C +```c napi_status napi_create_double(napi_env env, double value, napi_value* result) ``` diff --git a/n-api/napi_create_error.md b/n-api/napi_create_error.md index ffad202f..5b480213 100644 --- a/n-api/napi_create_error.md +++ b/n-api/napi_create_error.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c NAPI_EXTERN napi_status napi_create_error(napi_env env, napi_value code, napi_value msg, diff --git a/n-api/napi_create_external.md b/n-api/napi_create_external.md index 0ab92b00..8dd285ff 100644 --- a/n-api/napi_create_external.md +++ b/n-api/napi_create_external.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_create_external(napi_env env, void* data, napi_finalize finalize_cb, diff --git a/n-api/napi_create_external_arraybuffer.md b/n-api/napi_create_external_arraybuffer.md index ed7df023..4a26617c 100644 --- a/n-api/napi_create_external_arraybuffer.md +++ b/n-api/napi_create_external_arraybuffer.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_create_external_arraybuffer(napi_env env, void* external_data, diff --git a/n-api/napi_create_external_buffer.md b/n-api/napi_create_external_buffer.md index 7594b47a..33cbf306 100644 --- a/n-api/napi_create_external_buffer.md +++ b/n-api/napi_create_external_buffer.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_create_external_buffer(napi_env env, size_t length, void* data, diff --git a/n-api/napi_create_function.md b/n-api/napi_create_function.md index 607608f9..f2661c00 100644 --- a/n-api/napi_create_function.md +++ b/n-api/napi_create_function.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_create_function(napi_env env, const char* utf8name, size_t length, @@ -38,7 +38,7 @@ In order to expose a function as part of the add-on's module exports, set the newly created function on the exports object. A sample module might look as follows: -```C +```c napi_value SayHello(napi_env env, napi_callback_info info) { printf("Hello\n"); return NULL; diff --git a/n-api/napi_create_int32.md b/n-api/napi_create_int32.md index 60944b58..95638bac 100644 --- a/n-api/napi_create_int32.md +++ b/n-api/napi_create_int32.md @@ -3,7 +3,7 @@ added: v8.4.0 napiVersion: 1 --> -```C +```c napi_status napi_create_int32(napi_env env, int32_t value, napi_value* result) ``` diff --git a/n-api/napi_create_int64.md b/n-api/napi_create_int64.md index f09d4e84..d40b3c85 100644 --- a/n-api/napi_create_int64.md +++ b/n-api/napi_create_int64.md @@ -3,7 +3,7 @@ added: v8.4.0 napiVersion: 1 --> -```C +```c napi_status napi_create_int64(napi_env env, int64_t value, napi_value* result) ``` diff --git a/n-api/napi_create_object.md b/n-api/napi_create_object.md index 3dc369ca..d7f1cdb9 100644 --- a/n-api/napi_create_object.md +++ b/n-api/napi_create_object.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_create_object(napi_env env, napi_value* result) ``` diff --git a/n-api/napi_create_promise.md b/n-api/napi_create_promise.md index 3db38c20..1770a1d8 100644 --- a/n-api/napi_create_promise.md +++ b/n-api/napi_create_promise.md @@ -3,7 +3,7 @@ added: v8.5.0 napiVersion: 1 --> -```C +```c napi_status napi_create_promise(napi_env env, napi_deferred* deferred, napi_value* promise); diff --git a/n-api/napi_create_range_error.md b/n-api/napi_create_range_error.md index 9995505f..7e98d93e 100644 --- a/n-api/napi_create_range_error.md +++ b/n-api/napi_create_range_error.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c NAPI_EXTERN napi_status napi_create_range_error(napi_env env, napi_value code, napi_value msg, diff --git a/n-api/napi_create_reference.md b/n-api/napi_create_reference.md index 07ef0fec..a02b28f7 100644 --- a/n-api/napi_create_reference.md +++ b/n-api/napi_create_reference.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c NAPI_EXTERN napi_status napi_create_reference(napi_env env, napi_value value, uint32_t initial_refcount, diff --git a/n-api/napi_create_string_latin1.md b/n-api/napi_create_string_latin1.md index a91f3852..095c06ba 100644 --- a/n-api/napi_create_string_latin1.md +++ b/n-api/napi_create_string_latin1.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_create_string_latin1(napi_env env, const char* str, size_t length, diff --git a/n-api/napi_create_string_utf16.md b/n-api/napi_create_string_utf16.md index ce19e4f3..90362574 100644 --- a/n-api/napi_create_string_utf16.md +++ b/n-api/napi_create_string_utf16.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_create_string_utf16(napi_env env, const char16_t* str, size_t length, diff --git a/n-api/napi_create_string_utf8.md b/n-api/napi_create_string_utf8.md index 7d12c82d..2fd10c3c 100644 --- a/n-api/napi_create_string_utf8.md +++ b/n-api/napi_create_string_utf8.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_create_string_utf8(napi_env env, const char* str, size_t length, diff --git a/n-api/napi_create_symbol.md b/n-api/napi_create_symbol.md index 68511c9e..294b341d 100644 --- a/n-api/napi_create_symbol.md +++ b/n-api/napi_create_symbol.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_create_symbol(napi_env env, napi_value description, napi_value* result) diff --git a/n-api/napi_create_threadsafe_function.md b/n-api/napi_create_threadsafe_function.md index f1b6d02e..67b1ebd0 100644 --- a/n-api/napi_create_threadsafe_function.md +++ b/n-api/napi_create_threadsafe_function.md @@ -10,7 +10,7 @@ changes: description: Made `func` parameter optional with custom `call_js_cb`. --> -```C +```c NAPI_EXTERN napi_status napi_create_threadsafe_function(napi_env env, napi_value func, @@ -34,8 +34,9 @@ napi_create_threadsafe_function(napi_env env, the kind of resource that is being provided for diagnostic information exposed by the `async_hooks` API. * `[in] max_queue_size`: Maximum size of the queue. `0` for no limit. -* `[in] initial_thread_count`: The initial number of threads, including the main - thread, which will be making use of this function. +* `[in] initial_thread_count`: The initial number of acquisitions, i.e. the + initial number of threads, including the main thread, which will be making use + of this function. * `[in] thread_finalize_data`: Optional data to be passed to `thread_finalize_cb`. * `[in] thread_finalize_cb`: Optional function to call when the `napi_threadsafe_function` is being destroyed. diff --git a/n-api/napi_create_type_error.md b/n-api/napi_create_type_error.md index 871a50dd..1302ff1c 100644 --- a/n-api/napi_create_type_error.md +++ b/n-api/napi_create_type_error.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c NAPI_EXTERN napi_status napi_create_type_error(napi_env env, napi_value code, napi_value msg, diff --git a/n-api/napi_create_typedarray.md b/n-api/napi_create_typedarray.md index fbf517d7..c7daaf92 100644 --- a/n-api/napi_create_typedarray.md +++ b/n-api/napi_create_typedarray.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_create_typedarray(napi_env env, napi_typedarray_type type, size_t length, diff --git a/n-api/napi_create_uint32.md b/n-api/napi_create_uint32.md index 7e1e25bc..cbd751c7 100644 --- a/n-api/napi_create_uint32.md +++ b/n-api/napi_create_uint32.md @@ -3,7 +3,7 @@ added: v8.4.0 napiVersion: 1 --> -```C +```c napi_status napi_create_uint32(napi_env env, uint32_t value, napi_value* result) ``` diff --git a/n-api/napi_define_class.md b/n-api/napi_define_class.md index 3bc978b3..40b8aaa0 100644 --- a/n-api/napi_define_class.md +++ b/n-api/napi_define_class.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_define_class(napi_env env, const char* utf8name, size_t length, diff --git a/n-api/napi_define_properties.md b/n-api/napi_define_properties.md index ed1c4aae..9569ce4d 100644 --- a/n-api/napi_define_properties.md +++ b/n-api/napi_define_properties.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_define_properties(napi_env env, napi_value object, size_t property_count, diff --git a/n-api/napi_delete_async_work.md b/n-api/napi_delete_async_work.md index bab09112..62165524 100644 --- a/n-api/napi_delete_async_work.md +++ b/n-api/napi_delete_async_work.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_delete_async_work(napi_env env, napi_async_work work); ``` diff --git a/n-api/napi_delete_element.md b/n-api/napi_delete_element.md index 52aa4a73..186c8c6a 100644 --- a/n-api/napi_delete_element.md +++ b/n-api/napi_delete_element.md @@ -3,7 +3,7 @@ added: v8.2.0 napiVersion: 1 --> -```C +```c napi_status napi_delete_element(napi_env env, napi_value object, uint32_t index, diff --git a/n-api/napi_delete_property.md b/n-api/napi_delete_property.md index 1902ecd3..85de0e4e 100644 --- a/n-api/napi_delete_property.md +++ b/n-api/napi_delete_property.md @@ -3,7 +3,7 @@ added: v8.2.0 napiVersion: 1 --> -```C +```c napi_status napi_delete_property(napi_env env, napi_value object, napi_value key, diff --git a/n-api/napi_delete_reference.md b/n-api/napi_delete_reference.md index 017d3955..6cc174c9 100644 --- a/n-api/napi_delete_reference.md +++ b/n-api/napi_delete_reference.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c NAPI_EXTERN napi_status napi_delete_reference(napi_env env, napi_ref ref); ``` diff --git a/n-api/napi_detach_arraybuffer.md b/n-api/napi_detach_arraybuffer.md index 3b6991ab..4cac3db8 100644 --- a/n-api/napi_detach_arraybuffer.md +++ b/n-api/napi_detach_arraybuffer.md @@ -6,7 +6,7 @@ added: > Stability: 1 - Experimental -```C +```c napi_status napi_detach_arraybuffer(napi_env env, napi_value arraybuffer) ``` diff --git a/n-api/napi_escape_handle.md b/n-api/napi_escape_handle.md index 2ea301d6..9bd0f049 100644 --- a/n-api/napi_escape_handle.md +++ b/n-api/napi_escape_handle.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_escape_handle(napi_env env, napi_escapable_handle_scope scope, napi_value escapee, diff --git a/n-api/napi_extended_error_info.md b/n-api/napi_extended_error_info.md index d363d76d..db9c1a06 100644 --- a/n-api/napi_extended_error_info.md +++ b/n-api/napi_extended_error_info.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c typedef struct { const char* error_message; void* engine_reserved; diff --git a/n-api/napi_fatal_error.md b/n-api/napi_fatal_error.md index 07eaea3f..c73e97ee 100644 --- a/n-api/napi_fatal_error.md +++ b/n-api/napi_fatal_error.md @@ -3,7 +3,7 @@ added: v8.2.0 napiVersion: 1 --> -```C +```c NAPI_NO_RETURN void napi_fatal_error(const char* location, size_t location_len, const char* message, diff --git a/n-api/napi_fatal_exception.md b/n-api/napi_fatal_exception.md index f32afa5a..a4129645 100644 --- a/n-api/napi_fatal_exception.md +++ b/n-api/napi_fatal_exception.md @@ -3,7 +3,7 @@ added: v9.10.0 napiVersion: 3 --> -```C +```c napi_status napi_fatal_exception(napi_env env, napi_value err); ``` diff --git a/n-api/napi_finalize.md b/n-api/napi_finalize.md index 0d9a7a39..3e4d9c98 100644 --- a/n-api/napi_finalize.md +++ b/n-api/napi_finalize.md @@ -9,7 +9,7 @@ must provide a function satisfying the following signature which would get called upon the object's collection. Currently, `napi_finalize` can be used for finding out when objects that have external data are collected. -```C +```c typedef void (*napi_finalize)(napi_env env, void* finalize_data, void* finalize_hint); diff --git a/n-api/napi_get_all_property_names.md b/n-api/napi_get_all_property_names.md index f5e7e4f7..6d8eff36 100644 --- a/n-api/napi_get_all_property_names.md +++ b/n-api/napi_get_all_property_names.md @@ -5,7 +5,7 @@ added: napiVersion: 6 --> -```C +```c napi_get_all_property_names(napi_env env, napi_value object, napi_key_collection_mode key_mode, diff --git a/n-api/napi_get_and_clear_last_exception.md b/n-api/napi_get_and_clear_last_exception.md index 213c1274..05b00438 100644 --- a/n-api/napi_get_and_clear_last_exception.md +++ b/n-api/napi_get_and_clear_last_exception.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_get_and_clear_last_exception(napi_env env, napi_value* result); ``` diff --git a/n-api/napi_get_array_length.md b/n-api/napi_get_array_length.md index 33c648a3..1b86ba51 100644 --- a/n-api/napi_get_array_length.md +++ b/n-api/napi_get_array_length.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_get_array_length(napi_env env, napi_value value, uint32_t* result) diff --git a/n-api/napi_get_arraybuffer_info.md b/n-api/napi_get_arraybuffer_info.md index 26c93530..179903ec 100644 --- a/n-api/napi_get_arraybuffer_info.md +++ b/n-api/napi_get_arraybuffer_info.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_get_arraybuffer_info(napi_env env, napi_value arraybuffer, void** data, diff --git a/n-api/napi_get_boolean.md b/n-api/napi_get_boolean.md index 392ead4e..836d8f0b 100644 --- a/n-api/napi_get_boolean.md +++ b/n-api/napi_get_boolean.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_get_boolean(napi_env env, bool value, napi_value* result) ``` diff --git a/n-api/napi_get_buffer_info.md b/n-api/napi_get_buffer_info.md index d58f1903..72c1fc57 100644 --- a/n-api/napi_get_buffer_info.md +++ b/n-api/napi_get_buffer_info.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_get_buffer_info(napi_env env, napi_value value, void** data, diff --git a/n-api/napi_get_cb_info.md b/n-api/napi_get_cb_info.md index 21da8682..8e23460d 100644 --- a/n-api/napi_get_cb_info.md +++ b/n-api/napi_get_cb_info.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_get_cb_info(napi_env env, napi_callback_info cbinfo, size_t* argc, diff --git a/n-api/napi_get_dataview_info.md b/n-api/napi_get_dataview_info.md index 1d076565..6e901f8c 100644 --- a/n-api/napi_get_dataview_info.md +++ b/n-api/napi_get_dataview_info.md @@ -3,7 +3,7 @@ added: v8.3.0 napiVersion: 1 --> -```C +```c napi_status napi_get_dataview_info(napi_env env, napi_value dataview, size_t* byte_length, diff --git a/n-api/napi_get_date_value.md b/n-api/napi_get_date_value.md index 61608154..bf13760d 100644 --- a/n-api/napi_get_date_value.md +++ b/n-api/napi_get_date_value.md @@ -5,7 +5,7 @@ added: napiVersion: 5 --> -```C +```c napi_status napi_get_date_value(napi_env env, napi_value value, double* result) diff --git a/n-api/napi_get_element.md b/n-api/napi_get_element.md index d268562b..633f7fa9 100644 --- a/n-api/napi_get_element.md +++ b/n-api/napi_get_element.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_get_element(napi_env env, napi_value object, uint32_t index, diff --git a/n-api/napi_get_global.md b/n-api/napi_get_global.md index 1614c873..bc297f7e 100644 --- a/n-api/napi_get_global.md +++ b/n-api/napi_get_global.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_get_global(napi_env env, napi_value* result) ``` diff --git a/n-api/napi_get_instance_data.md b/n-api/napi_get_instance_data.md index d04ade55..cd6595e3 100644 --- a/n-api/napi_get_instance_data.md +++ b/n-api/napi_get_instance_data.md @@ -5,7 +5,7 @@ added: napiVersion: 6 --> -```C +```c napi_status napi_get_instance_data(napi_env env, void** data); ``` diff --git a/n-api/napi_get_last_error_info.md b/n-api/napi_get_last_error_info.md index 1d2ef321..ceb22fea 100644 --- a/n-api/napi_get_last_error_info.md +++ b/n-api/napi_get_last_error_info.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_get_last_error_info(napi_env env, const napi_extended_error_info** result); diff --git a/n-api/napi_get_named_property.md b/n-api/napi_get_named_property.md index ea4d3955..029aa395 100644 --- a/n-api/napi_get_named_property.md +++ b/n-api/napi_get_named_property.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_get_named_property(napi_env env, napi_value object, const char* utf8Name, diff --git a/n-api/napi_get_new_target.md b/n-api/napi_get_new_target.md index be099f2c..9a14068a 100644 --- a/n-api/napi_get_new_target.md +++ b/n-api/napi_get_new_target.md @@ -3,7 +3,7 @@ added: v8.6.0 napiVersion: 1 --> -```C +```c napi_status napi_get_new_target(napi_env env, napi_callback_info cbinfo, napi_value* result) diff --git a/n-api/napi_get_node_version.md b/n-api/napi_get_node_version.md index 0fc2576b..fde0a8e8 100644 --- a/n-api/napi_get_node_version.md +++ b/n-api/napi_get_node_version.md @@ -3,7 +3,7 @@ added: v8.4.0 napiVersion: 1 --> -```C +```c typedef struct { uint32_t major; uint32_t minor; diff --git a/n-api/napi_get_null.md b/n-api/napi_get_null.md index f634d67e..23bf7aa8 100644 --- a/n-api/napi_get_null.md +++ b/n-api/napi_get_null.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_get_null(napi_env env, napi_value* result) ``` diff --git a/n-api/napi_get_property.md b/n-api/napi_get_property.md index 0a3b7fe0..dc66d63a 100644 --- a/n-api/napi_get_property.md +++ b/n-api/napi_get_property.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_get_property(napi_env env, napi_value object, napi_value key, diff --git a/n-api/napi_get_property_names.md b/n-api/napi_get_property_names.md index d65b918b..bdf3ff15 100644 --- a/n-api/napi_get_property_names.md +++ b/n-api/napi_get_property_names.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_get_property_names(napi_env env, napi_value object, napi_value* result); diff --git a/n-api/napi_get_prototype.md b/n-api/napi_get_prototype.md index 96cd1d48..ce2923fe 100644 --- a/n-api/napi_get_prototype.md +++ b/n-api/napi_get_prototype.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_get_prototype(napi_env env, napi_value object, napi_value* result) diff --git a/n-api/napi_get_reference_value.md b/n-api/napi_get_reference_value.md index 66f098de..4239fa59 100644 --- a/n-api/napi_get_reference_value.md +++ b/n-api/napi_get_reference_value.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c NAPI_EXTERN napi_status napi_get_reference_value(napi_env env, napi_ref ref, napi_value* result); diff --git a/n-api/napi_get_threadsafe_function_context.md b/n-api/napi_get_threadsafe_function_context.md index e1f00fdb..2521c3e8 100644 --- a/n-api/napi_get_threadsafe_function_context.md +++ b/n-api/napi_get_threadsafe_function_context.md @@ -4,7 +4,7 @@ added: v10.6.0 napiVersion: 4 --> -```C +```c NAPI_EXTERN napi_status napi_get_threadsafe_function_context(napi_threadsafe_function func, void** result); diff --git a/n-api/napi_get_typedarray_info.md b/n-api/napi_get_typedarray_info.md index 77fe110d..52560f6b 100644 --- a/n-api/napi_get_typedarray_info.md +++ b/n-api/napi_get_typedarray_info.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_get_typedarray_info(napi_env env, napi_value typedarray, napi_typedarray_type* type, diff --git a/n-api/napi_get_undefined.md b/n-api/napi_get_undefined.md index 46656f40..2ea6a03d 100644 --- a/n-api/napi_get_undefined.md +++ b/n-api/napi_get_undefined.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_get_undefined(napi_env env, napi_value* result) ``` diff --git a/n-api/napi_get_uv_event_loop.md b/n-api/napi_get_uv_event_loop.md index 6fb85939..0dad2c13 100644 --- a/n-api/napi_get_uv_event_loop.md +++ b/n-api/napi_get_uv_event_loop.md @@ -5,7 +5,7 @@ added: napiVersion: 2 --> -```C +```c NAPI_EXTERN napi_status napi_get_uv_event_loop(napi_env env, struct uv_loop_s** loop); ``` diff --git a/n-api/napi_get_value_bigint_int64.md b/n-api/napi_get_value_bigint_int64.md index 287597d6..adc109b2 100644 --- a/n-api/napi_get_value_bigint_int64.md +++ b/n-api/napi_get_value_bigint_int64.md @@ -3,7 +3,7 @@ added: v10.7.0 napiVersion: 6 --> -```C +```c napi_status napi_get_value_bigint_int64(napi_env env, napi_value value, int64_t* result, diff --git a/n-api/napi_get_value_bigint_uint64.md b/n-api/napi_get_value_bigint_uint64.md index ca7b3d30..6cf1c825 100644 --- a/n-api/napi_get_value_bigint_uint64.md +++ b/n-api/napi_get_value_bigint_uint64.md @@ -3,7 +3,7 @@ added: v10.7.0 napiVersion: 6 --> -```C +```c napi_status napi_get_value_bigint_uint64(napi_env env, napi_value value, uint64_t* result, diff --git a/n-api/napi_get_value_bigint_words.md b/n-api/napi_get_value_bigint_words.md index ca3ffb28..4d644a24 100644 --- a/n-api/napi_get_value_bigint_words.md +++ b/n-api/napi_get_value_bigint_words.md @@ -3,7 +3,7 @@ added: v10.7.0 napiVersion: 6 --> -```C +```c napi_status napi_get_value_bigint_words(napi_env env, napi_value value, int* sign_bit, diff --git a/n-api/napi_get_value_bool.md b/n-api/napi_get_value_bool.md index bac92df8..f281d554 100644 --- a/n-api/napi_get_value_bool.md +++ b/n-api/napi_get_value_bool.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_get_value_bool(napi_env env, napi_value value, bool* result) ``` diff --git a/n-api/napi_get_value_double.md b/n-api/napi_get_value_double.md index 8a207e77..b73fce16 100644 --- a/n-api/napi_get_value_double.md +++ b/n-api/napi_get_value_double.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_get_value_double(napi_env env, napi_value value, double* result) diff --git a/n-api/napi_get_value_external.md b/n-api/napi_get_value_external.md index c1b12b4a..a5f41ef3 100644 --- a/n-api/napi_get_value_external.md +++ b/n-api/napi_get_value_external.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_get_value_external(napi_env env, napi_value value, void** result) diff --git a/n-api/napi_get_value_int32.md b/n-api/napi_get_value_int32.md index 00882ec7..47aa8761 100644 --- a/n-api/napi_get_value_int32.md +++ b/n-api/napi_get_value_int32.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_get_value_int32(napi_env env, napi_value value, int32_t* result) diff --git a/n-api/napi_get_value_int64.md b/n-api/napi_get_value_int64.md index e21c7058..63a3398b 100644 --- a/n-api/napi_get_value_int64.md +++ b/n-api/napi_get_value_int64.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_get_value_int64(napi_env env, napi_value value, int64_t* result) diff --git a/n-api/napi_get_value_string_latin1.md b/n-api/napi_get_value_string_latin1.md index f74c61d0..b398cfd0 100644 --- a/n-api/napi_get_value_string_latin1.md +++ b/n-api/napi_get_value_string_latin1.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_get_value_string_latin1(napi_env env, napi_value value, char* buf, diff --git a/n-api/napi_get_value_string_utf16.md b/n-api/napi_get_value_string_utf16.md index c102f5a2..676348a4 100644 --- a/n-api/napi_get_value_string_utf16.md +++ b/n-api/napi_get_value_string_utf16.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_get_value_string_utf16(napi_env env, napi_value value, char16_t* buf, diff --git a/n-api/napi_get_value_string_utf8.md b/n-api/napi_get_value_string_utf8.md index 6faf83af..d59527fa 100644 --- a/n-api/napi_get_value_string_utf8.md +++ b/n-api/napi_get_value_string_utf8.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_get_value_string_utf8(napi_env env, napi_value value, char* buf, diff --git a/n-api/napi_get_value_uint32.md b/n-api/napi_get_value_uint32.md index dae4bfab..1ef6d6d0 100644 --- a/n-api/napi_get_value_uint32.md +++ b/n-api/napi_get_value_uint32.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_get_value_uint32(napi_env env, napi_value value, uint32_t* result) diff --git a/n-api/napi_get_version.md b/n-api/napi_get_version.md index 08116d3a..6c453d7a 100644 --- a/n-api/napi_get_version.md +++ b/n-api/napi_get_version.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_get_version(napi_env env, uint32_t* result); ``` diff --git a/n-api/napi_has_element.md b/n-api/napi_has_element.md index a41e6234..96a1294f 100644 --- a/n-api/napi_has_element.md +++ b/n-api/napi_has_element.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_has_element(napi_env env, napi_value object, uint32_t index, diff --git a/n-api/napi_has_named_property.md b/n-api/napi_has_named_property.md index 63f85809..0fb3b2d2 100644 --- a/n-api/napi_has_named_property.md +++ b/n-api/napi_has_named_property.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_has_named_property(napi_env env, napi_value object, const char* utf8Name, diff --git a/n-api/napi_has_own_property.md b/n-api/napi_has_own_property.md index 37ab0994..3804454e 100644 --- a/n-api/napi_has_own_property.md +++ b/n-api/napi_has_own_property.md @@ -3,7 +3,7 @@ added: v8.2.0 napiVersion: 1 --> -```C +```c napi_status napi_has_own_property(napi_env env, napi_value object, napi_value key, diff --git a/n-api/napi_has_property.md b/n-api/napi_has_property.md index 653fa5cc..0c3f7b58 100644 --- a/n-api/napi_has_property.md +++ b/n-api/napi_has_property.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_has_property(napi_env env, napi_value object, napi_value key, diff --git a/n-api/napi_instanceof.md b/n-api/napi_instanceof.md index 5a1f1777..b635e707 100644 --- a/n-api/napi_instanceof.md +++ b/n-api/napi_instanceof.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_instanceof(napi_env env, napi_value object, napi_value constructor, diff --git a/n-api/napi_is_array.md b/n-api/napi_is_array.md index 5a7d0b17..32cd5d83 100644 --- a/n-api/napi_is_array.md +++ b/n-api/napi_is_array.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_is_array(napi_env env, napi_value value, bool* result) ``` diff --git a/n-api/napi_is_arraybuffer.md b/n-api/napi_is_arraybuffer.md index 67f042d3..d061418e 100644 --- a/n-api/napi_is_arraybuffer.md +++ b/n-api/napi_is_arraybuffer.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_is_arraybuffer(napi_env env, napi_value value, bool* result) ``` diff --git a/n-api/napi_is_buffer.md b/n-api/napi_is_buffer.md index 48f0aaef..3a83ee3d 100644 --- a/n-api/napi_is_buffer.md +++ b/n-api/napi_is_buffer.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_is_buffer(napi_env env, napi_value value, bool* result) ``` diff --git a/n-api/napi_is_dataview.md b/n-api/napi_is_dataview.md index 4c611e32..84c2047d 100644 --- a/n-api/napi_is_dataview.md +++ b/n-api/napi_is_dataview.md @@ -3,7 +3,7 @@ added: v8.3.0 napiVersion: 1 --> -```C +```c napi_status napi_is_dataview(napi_env env, napi_value value, bool* result) ``` diff --git a/n-api/napi_is_date.md b/n-api/napi_is_date.md index 516314e8..429efb05 100644 --- a/n-api/napi_is_date.md +++ b/n-api/napi_is_date.md @@ -5,7 +5,7 @@ added: napiVersion: 5 --> -```C +```c napi_status napi_is_date(napi_env env, napi_value value, bool* result) ``` diff --git a/n-api/napi_is_detached_arraybuffer.md b/n-api/napi_is_detached_arraybuffer.md index 35d059c2..490475b8 100644 --- a/n-api/napi_is_detached_arraybuffer.md +++ b/n-api/napi_is_detached_arraybuffer.md @@ -6,7 +6,7 @@ added: > Stability: 1 - Experimental -```C +```c napi_status napi_is_detached_arraybuffer(napi_env env, napi_value arraybuffer, bool* result) diff --git a/n-api/napi_is_error.md b/n-api/napi_is_error.md index ae34c868..53115bab 100644 --- a/n-api/napi_is_error.md +++ b/n-api/napi_is_error.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c NAPI_EXTERN napi_status napi_is_error(napi_env env, napi_value value, bool* result); diff --git a/n-api/napi_is_error_1.md b/n-api/napi_is_error_1.md index 84694c61..a402f272 100644 --- a/n-api/napi_is_error_1.md +++ b/n-api/napi_is_error_1.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_is_error(napi_env env, napi_value value, bool* result) ``` diff --git a/n-api/napi_is_exception_pending.md b/n-api/napi_is_exception_pending.md index 7ed4807f..ca0666b1 100644 --- a/n-api/napi_is_exception_pending.md +++ b/n-api/napi_is_exception_pending.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_is_exception_pending(napi_env env, bool* result); ``` diff --git a/n-api/napi_is_promise.md b/n-api/napi_is_promise.md index 72acc816..bb77cf30 100644 --- a/n-api/napi_is_promise.md +++ b/n-api/napi_is_promise.md @@ -3,7 +3,7 @@ added: v8.5.0 napiVersion: 1 --> -```C +```c napi_status napi_is_promise(napi_env env, napi_value value, bool* is_promise); diff --git a/n-api/napi_is_typedarray.md b/n-api/napi_is_typedarray.md index 3971552b..58b2a783 100644 --- a/n-api/napi_is_typedarray.md +++ b/n-api/napi_is_typedarray.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_is_typedarray(napi_env env, napi_value value, bool* result) ``` diff --git a/n-api/napi_key_collection_mode.md b/n-api/napi_key_collection_mode.md index 94701651..cb19fe5e 100644 --- a/n-api/napi_key_collection_mode.md +++ b/n-api/napi_key_collection_mode.md @@ -5,7 +5,7 @@ added: napiVersion: 6 --> -```C +```c typedef enum { napi_key_include_prototypes, napi_key_own_only diff --git a/n-api/napi_key_conversion.md b/n-api/napi_key_conversion.md index d4dca8d0..56ad67bb 100644 --- a/n-api/napi_key_conversion.md +++ b/n-api/napi_key_conversion.md @@ -5,7 +5,7 @@ added: napiVersion: 6 --> -```C +```c typedef enum { napi_key_keep_numbers, napi_key_numbers_to_strings diff --git a/n-api/napi_key_filter.md b/n-api/napi_key_filter.md index a287f819..6f23976e 100644 --- a/n-api/napi_key_filter.md +++ b/n-api/napi_key_filter.md @@ -5,7 +5,7 @@ added: napiVersion: 6 --> -```C +```c typedef enum { napi_key_all_properties = 0, napi_key_writable = 1, diff --git a/n-api/napi_make_callback.md b/n-api/napi_make_callback.md index 11fbe61a..dbc33c10 100644 --- a/n-api/napi_make_callback.md +++ b/n-api/napi_make_callback.md @@ -6,7 +6,7 @@ changes: description: Added `async_context` parameter. --> -```C +```c NAPI_EXTERN napi_status napi_make_callback(napi_env env, napi_async_context async_context, napi_value recv, @@ -44,3 +44,6 @@ is sufficient and appropriate. Use of the `napi_make_callback` function may be required when implementing custom async behavior that does not use `napi_create_async_work`. +Any `process.nextTick`s or Promises scheduled on the microtask queue by +JavaScript during the callback are ran before returning back to C/C++. + diff --git a/n-api/napi_new_instance.md b/n-api/napi_new_instance.md index 7757ea27..014a9df5 100644 --- a/n-api/napi_new_instance.md +++ b/n-api/napi_new_instance.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_new_instance(napi_env env, napi_value cons, size_t argc, @@ -35,7 +35,7 @@ const value = new MyObject(arg); The following can be approximated in N-API using the following snippet: -```C +```c // Get the constructor function MyObject napi_value global, constructor, arg, value; napi_status status = napi_get_global(env, &global); diff --git a/n-api/napi_open_callback_scope.md b/n-api/napi_open_callback_scope.md index e0d2edd5..e1172ee8 100644 --- a/n-api/napi_open_callback_scope.md +++ b/n-api/napi_open_callback_scope.md @@ -3,7 +3,7 @@ added: v9.6.0 napiVersion: 3 --> -```C +```c NAPI_EXTERN napi_status napi_open_callback_scope(napi_env env, napi_value resource_object, napi_async_context context, diff --git a/n-api/napi_open_escapable_handle_scope.md b/n-api/napi_open_escapable_handle_scope.md index b21aaf98..371a59e7 100644 --- a/n-api/napi_open_escapable_handle_scope.md +++ b/n-api/napi_open_escapable_handle_scope.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c NAPI_EXTERN napi_status napi_open_escapable_handle_scope(napi_env env, napi_handle_scope* result); @@ -14,6 +14,6 @@ NAPI_EXTERN napi_status Returns `napi_ok` if the API succeeded. -This API open a new scope from which one object can be promoted +This API opens a new scope from which one object can be promoted to the outer scope. diff --git a/n-api/napi_open_handle_scope.md b/n-api/napi_open_handle_scope.md index f3f9268d..7ef0dcb4 100644 --- a/n-api/napi_open_handle_scope.md +++ b/n-api/napi_open_handle_scope.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c NAPI_EXTERN napi_status napi_open_handle_scope(napi_env env, napi_handle_scope* result); ``` @@ -13,5 +13,5 @@ NAPI_EXTERN napi_status napi_open_handle_scope(napi_env env, Returns `napi_ok` if the API succeeded. -This API open a new scope. +This API opens a new scope. diff --git a/n-api/napi_property_attributes.md b/n-api/napi_property_attributes.md index 6a56581f..57017f70 100644 --- a/n-api/napi_property_attributes.md +++ b/n-api/napi_property_attributes.md @@ -1,5 +1,5 @@ -```C +```c typedef enum { napi_default = 0, napi_writable = 1 << 0, diff --git a/n-api/napi_property_descriptor.md b/n-api/napi_property_descriptor.md index 25cd9307..18d43eaf 100644 --- a/n-api/napi_property_descriptor.md +++ b/n-api/napi_property_descriptor.md @@ -1,5 +1,5 @@ -```C +```c typedef struct { // One of utf8name or name should be NULL. const char* utf8name; diff --git a/n-api/napi_queue_async_work.md b/n-api/napi_queue_async_work.md index 3c1fb6be..11688d35 100644 --- a/n-api/napi_queue_async_work.md +++ b/n-api/napi_queue_async_work.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_queue_async_work(napi_env env, napi_async_work work); ``` diff --git a/n-api/napi_ref_threadsafe_function.md b/n-api/napi_ref_threadsafe_function.md index bbb0b9de..5bb3bddf 100644 --- a/n-api/napi_ref_threadsafe_function.md +++ b/n-api/napi_ref_threadsafe_function.md @@ -4,7 +4,7 @@ added: v10.6.0 napiVersion: 4 --> -```C +```c NAPI_EXTERN napi_status napi_ref_threadsafe_function(napi_env env, napi_threadsafe_function func); ``` @@ -16,5 +16,10 @@ This API is used to indicate that the event loop running on the main thread should not exit until `func` has been destroyed. Similar to [`uv_ref`][] it is also idempotent. +Neither does `napi_unref_threadsafe_function` mark the thread-safe functions as +able to be destroyed nor does `napi_ref_threadsafe_function` prevent it from +being destroyed. `napi_acquire_threadsafe_function` and +`napi_release_threadsafe_function` are available for that purpose. + This API may only be called from the main thread. diff --git a/n-api/napi_reference_ref.md b/n-api/napi_reference_ref.md index 86ee4b77..455952d6 100644 --- a/n-api/napi_reference_ref.md +++ b/n-api/napi_reference_ref.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c NAPI_EXTERN napi_status napi_reference_ref(napi_env env, napi_ref ref, uint32_t* result); diff --git a/n-api/napi_reference_unref.md b/n-api/napi_reference_unref.md index 9f49749a..f6f37035 100644 --- a/n-api/napi_reference_unref.md +++ b/n-api/napi_reference_unref.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c NAPI_EXTERN napi_status napi_reference_unref(napi_env env, napi_ref ref, uint32_t* result); diff --git a/n-api/napi_reject_deferred.md b/n-api/napi_reject_deferred.md index 30f99280..b457e02b 100644 --- a/n-api/napi_reject_deferred.md +++ b/n-api/napi_reject_deferred.md @@ -3,7 +3,7 @@ added: v8.5.0 napiVersion: 1 --> -```C +```c napi_status napi_reject_deferred(napi_env env, napi_deferred deferred, napi_value rejection); diff --git a/n-api/napi_release_threadsafe_function.md b/n-api/napi_release_threadsafe_function.md index b24297dd..d1e256f7 100644 --- a/n-api/napi_release_threadsafe_function.md +++ b/n-api/napi_release_threadsafe_function.md @@ -4,7 +4,7 @@ added: v10.6.0 napiVersion: 4 --> -```C +```c NAPI_EXTERN napi_status napi_release_threadsafe_function(napi_threadsafe_function func, napi_threadsafe_function_release_mode mode); diff --git a/n-api/napi_remove_env_cleanup_hook.md b/n-api/napi_remove_env_cleanup_hook.md index db04e6d4..abcdf391 100644 --- a/n-api/napi_remove_env_cleanup_hook.md +++ b/n-api/napi_remove_env_cleanup_hook.md @@ -3,7 +3,7 @@ added: v10.2.0 napiVersion: 3 --> -```C +```c NAPI_EXTERN napi_status napi_remove_env_cleanup_hook(napi_env env, void (*fun)(void* arg), void* arg); diff --git a/n-api/napi_remove_wrap.md b/n-api/napi_remove_wrap.md index 9bd6491c..500bd9f4 100644 --- a/n-api/napi_remove_wrap.md +++ b/n-api/napi_remove_wrap.md @@ -3,7 +3,7 @@ added: v8.5.0 napiVersion: 1 --> -```C +```c napi_status napi_remove_wrap(napi_env env, napi_value js_object, void** result); diff --git a/n-api/napi_resolve_deferred.md b/n-api/napi_resolve_deferred.md index 63130fd0..4406d7cc 100644 --- a/n-api/napi_resolve_deferred.md +++ b/n-api/napi_resolve_deferred.md @@ -3,7 +3,7 @@ added: v8.5.0 napiVersion: 1 --> -```C +```c napi_status napi_resolve_deferred(napi_env env, napi_deferred deferred, napi_value resolution); diff --git a/n-api/napi_run_script.md b/n-api/napi_run_script.md index 8329af7f..1026ec61 100644 --- a/n-api/napi_run_script.md +++ b/n-api/napi_run_script.md @@ -3,7 +3,7 @@ added: v8.5.0 napiVersion: 1 --> -```C +```c NAPI_EXTERN napi_status napi_run_script(napi_env env, napi_value script, napi_value* result); diff --git a/n-api/napi_set_element.md b/n-api/napi_set_element.md index 1f8ed335..5748b8b3 100644 --- a/n-api/napi_set_element.md +++ b/n-api/napi_set_element.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_set_element(napi_env env, napi_value object, uint32_t index, diff --git a/n-api/napi_set_instance_data.md b/n-api/napi_set_instance_data.md index 948cf61c..28da6815 100644 --- a/n-api/napi_set_instance_data.md +++ b/n-api/napi_set_instance_data.md @@ -5,7 +5,7 @@ added: napiVersion: 6 --> -```C +```c napi_status napi_set_instance_data(napi_env env, void* data, napi_finalize finalize_cb, diff --git a/n-api/napi_set_named_property.md b/n-api/napi_set_named_property.md index bf84111a..605587e1 100644 --- a/n-api/napi_set_named_property.md +++ b/n-api/napi_set_named_property.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_set_named_property(napi_env env, napi_value object, const char* utf8Name, diff --git a/n-api/napi_set_property.md b/n-api/napi_set_property.md index d27535c6..48975ff8 100644 --- a/n-api/napi_set_property.md +++ b/n-api/napi_set_property.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_set_property(napi_env env, napi_value object, napi_value key, diff --git a/n-api/napi_status.md b/n-api/napi_status.md index 2179d153..8d50d5df 100644 --- a/n-api/napi_status.md +++ b/n-api/napi_status.md @@ -5,7 +5,7 @@ napiVersion: 1 Integral status code indicating the success or failure of a N-API call. Currently, the following status codes are supported. -```C +```c typedef enum { napi_ok, napi_invalid_arg, @@ -28,7 +28,7 @@ typedef enum { napi_date_expected, napi_arraybuffer_expected, napi_detachable_arraybuffer_expected, - napi_would_deadlock, + napi_would_deadlock, /* unused */ } napi_status; ``` diff --git a/n-api/napi_strict_equals.md b/n-api/napi_strict_equals.md index 8edd9a73..061c6016 100644 --- a/n-api/napi_strict_equals.md +++ b/n-api/napi_strict_equals.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_strict_equals(napi_env env, napi_value lhs, napi_value rhs, diff --git a/n-api/napi_threadsafe_function_call_js.md b/n-api/napi_threadsafe_function_call_js.md index 3e90cd42..1926dd9b 100644 --- a/n-api/napi_threadsafe_function_call_js.md +++ b/n-api/napi_threadsafe_function_call_js.md @@ -19,7 +19,7 @@ via `napi_make_callback`. Callback functions must satisfy the following signature: -```C +```c typedef void (*napi_threadsafe_function_call_js)(napi_env env, napi_value js_callback, void* context, diff --git a/n-api/napi_threadsafe_function_call_mode.md b/n-api/napi_threadsafe_function_call_mode.md index 1ef7c581..e2bacfa7 100644 --- a/n-api/napi_threadsafe_function_call_mode.md +++ b/n-api/napi_threadsafe_function_call_mode.md @@ -7,7 +7,7 @@ A value to be given to `napi_call_threadsafe_function()` to indicate whether the call should block whenever the queue associated with the thread-safe function is full. -```C +```c typedef enum { napi_tsfn_nonblocking, napi_tsfn_blocking diff --git a/n-api/napi_threadsafe_function_release_mode.md b/n-api/napi_threadsafe_function_release_mode.md index 181463ad..9eca5f7a 100644 --- a/n-api/napi_threadsafe_function_release_mode.md +++ b/n-api/napi_threadsafe_function_release_mode.md @@ -8,7 +8,7 @@ the thread-safe function is to be closed immediately (`napi_tsfn_abort`) or merely released (`napi_tsfn_release`) and thus available for subsequent use via `napi_acquire_threadsafe_function()` and `napi_call_threadsafe_function()`. -```C +```c typedef enum { napi_tsfn_release, napi_tsfn_abort diff --git a/n-api/napi_throw.md b/n-api/napi_throw.md index 1089ebad..ddd268d0 100644 --- a/n-api/napi_throw.md +++ b/n-api/napi_throw.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error); ``` diff --git a/n-api/napi_throw_error.md b/n-api/napi_throw_error.md index 3a1d9267..7cc6eb73 100644 --- a/n-api/napi_throw_error.md +++ b/n-api/napi_throw_error.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c NAPI_EXTERN napi_status napi_throw_error(napi_env env, const char* code, const char* msg); diff --git a/n-api/napi_throw_range_error.md b/n-api/napi_throw_range_error.md index e483fe4c..ee11fa83 100644 --- a/n-api/napi_throw_range_error.md +++ b/n-api/napi_throw_range_error.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c NAPI_EXTERN napi_status napi_throw_range_error(napi_env env, const char* code, const char* msg); diff --git a/n-api/napi_throw_type_error.md b/n-api/napi_throw_type_error.md index 5917210e..9d0078a9 100644 --- a/n-api/napi_throw_type_error.md +++ b/n-api/napi_throw_type_error.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c NAPI_EXTERN napi_status napi_throw_type_error(napi_env env, const char* code, const char* msg); diff --git a/n-api/napi_typedarray_type.md b/n-api/napi_typedarray_type.md index ac53753b..17e633c8 100644 --- a/n-api/napi_typedarray_type.md +++ b/n-api/napi_typedarray_type.md @@ -1,5 +1,5 @@ -```C +```c typedef enum { napi_int8_array, napi_uint8_array, diff --git a/n-api/napi_typeof.md b/n-api/napi_typeof.md index 2bb78798..ecfce340 100644 --- a/n-api/napi_typeof.md +++ b/n-api/napi_typeof.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_typeof(napi_env env, napi_value value, napi_valuetype* result) ``` diff --git a/n-api/napi_unref_threadsafe_function.md b/n-api/napi_unref_threadsafe_function.md index 22dd5190..cbd873dc 100644 --- a/n-api/napi_unref_threadsafe_function.md +++ b/n-api/napi_unref_threadsafe_function.md @@ -4,7 +4,7 @@ added: v10.6.0 napiVersion: 4 --> -```C +```c NAPI_EXTERN napi_status napi_unref_threadsafe_function(napi_env env, napi_threadsafe_function func); ``` diff --git a/n-api/napi_unwrap.md b/n-api/napi_unwrap.md index 55e726eb..7593a2a1 100644 --- a/n-api/napi_unwrap.md +++ b/n-api/napi_unwrap.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_unwrap(napi_env env, napi_value js_object, void** result); diff --git a/n-api/napi_valuetype.md b/n-api/napi_valuetype.md index e88fb1a6..7b22667f 100644 --- a/n-api/napi_valuetype.md +++ b/n-api/napi_valuetype.md @@ -1,5 +1,5 @@ -```C +```c typedef enum { // ES6 types (corresponds to typeof) napi_undefined, diff --git a/n-api/napi_wrap.md b/n-api/napi_wrap.md index 4bb68f11..d3db50ae 100644 --- a/n-api/napi_wrap.md +++ b/n-api/napi_wrap.md @@ -3,7 +3,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c napi_status napi_wrap(napi_env env, napi_value js_object, void* native_object, diff --git a/n-api/object_wrap.md b/n-api/object_wrap.md index 8600fe39..bf9162d2 100644 --- a/n-api/object_wrap.md +++ b/n-api/object_wrap.md @@ -18,7 +18,7 @@ called on a class prototype and a function called on an instance of a class. A common pattern used to address this problem is to save a persistent reference to the class constructor for later `instanceof` checks. -```C +```c napi_value MyClass_constructor = NULL; status = napi_get_reference_value(env, MyClass::es_constructor, &MyClass_constructor); assert(napi_ok == status); diff --git a/n-api/reference_counting_of_thread_safe_functions.md b/n-api/reference_counting_of_thread_safe_functions.md new file mode 100644 index 00000000..d2213d39 --- /dev/null +++ b/n-api/reference_counting_of_thread_safe_functions.md @@ -0,0 +1,43 @@ + +Threads can be added to and removed from a `napi_threadsafe_function` object +during its existence. Thus, in addition to specifying an initial number of +threads upon creation, `napi_acquire_threadsafe_function` can be called to +indicate that a new thread will start making use of the thread-safe function. +Similarly, `napi_release_threadsafe_function` can be called to indicate that an +existing thread will stop making use of the thread-safe function. + +`napi_threadsafe_function` objects are destroyed when every thread which uses +the object has called `napi_release_threadsafe_function()` or has received a +return status of `napi_closing` in response to a call to +`napi_call_threadsafe_function`. The queue is emptied before the +`napi_threadsafe_function` is destroyed. `napi_release_threadsafe_function()` +should be the last API call made in conjunction with a given +`napi_threadsafe_function`, because after the call completes, there is no +guarantee that the `napi_threadsafe_function` is still allocated. For the same +reason, do not make use of a thread-safe function +after receiving a return value of `napi_closing` in response to a call to +`napi_call_threadsafe_function`. Data associated with the +`napi_threadsafe_function` can be freed in its `napi_finalize` callback which +was passed to `napi_create_threadsafe_function()`. The parameter +`initial_thread_count` of `napi_create_threadsafe_function` marks the initial +number of aquisitions of the thread-safe functions, instead of calling +`napi_acquire_threadsafe_function` multiple times at creation. + +Once the number of threads making use of a `napi_threadsafe_function` reaches +zero, no further threads can start making use of it by calling +`napi_acquire_threadsafe_function()`. In fact, all subsequent API calls +associated with it, except `napi_release_threadsafe_function()`, will return an +error value of `napi_closing`. + +The thread-safe function can be "aborted" by giving a value of `napi_tsfn_abort` +to `napi_release_threadsafe_function()`. This will cause all subsequent APIs +associated with the thread-safe function except +`napi_release_threadsafe_function()` to return `napi_closing` even before its +reference count reaches zero. In particular, `napi_call_threadsafe_function()` +will return `napi_closing`, thus informing the threads that it is no longer +possible to make asynchronous calls to the thread-safe function. This can be +used as a criterion for terminating the thread. **Upon receiving a return value +of `napi_closing` from `napi_call_threadsafe_function()` a thread must make no +further use of the thread-safe function because it is no longer guaranteed to +be allocated.** + diff --git a/n-api/return_values.md b/n-api/return_values.md index 3d0b5ad9..7b99768a 100644 --- a/n-api/return_values.md +++ b/n-api/return_values.md @@ -30,7 +30,7 @@ added: v8.0.0 napiVersion: 1 --> -```C +```c typedef struct napi_extended_error_info { const char* error_message; void* engine_reserved; diff --git a/n-api/simple_asynchronous_operations.md b/n-api/simple_asynchronous_operations.md index fb1e88ea..9ffd60a8 100644 --- a/n-api/simple_asynchronous_operations.md +++ b/n-api/simple_asynchronous_operations.md @@ -24,7 +24,7 @@ it will likely execute JavaScript. These functions implement the following interfaces: -```C +```c typedef void (*napi_async_execute_callback)(napi_env env, void* data); typedef void (*napi_async_complete_callback)(napi_env env, @@ -39,7 +39,7 @@ addon-provided `void*` data that was passed into the Once created the async worker can be queued for execution using the [`napi_queue_async_work`][] function: -```C +```c napi_status napi_queue_async_work(napi_env env, napi_async_work work); ``` diff --git a/n-api/usage.md b/n-api/usage.md index a6cf18c2..5e259675 100644 --- a/n-api/usage.md +++ b/n-api/usage.md @@ -2,7 +2,7 @@ In order to use the N-API functions, include the file [`node_api.h`][] which is located in the src directory in the node development tree: -```C +```c #include ``` @@ -10,7 +10,7 @@ This will opt into the default `NAPI_VERSION` for the given release of Node.js. In order to ensure compatibility with specific versions of N-API, the version can be specified explicitly when including the header: -```C +```c #define NAPI_VERSION 3 #include ``` @@ -21,7 +21,7 @@ the specified (and earlier) versions. Some of the N-API surface is considered experimental and requires explicit opt-in to access those APIs: -```C +```c #define NAPI_EXPERIMENTAL #include ``` diff --git a/n-api/working_with_javascript_properties.md b/n-api/working_with_javascript_properties.md index c79271ad..b3777ec0 100644 --- a/n-api/working_with_javascript_properties.md +++ b/n-api/working_with_javascript_properties.md @@ -30,7 +30,7 @@ obj.myProp = 123; The equivalent can be done using N-API values with the following snippet: -```C +```c napi_status status = napi_generic_failure; // const obj = {} @@ -57,7 +57,7 @@ arr[123] = 'hello'; The equivalent can be done using N-API values with the following snippet: -```C +```c napi_status status = napi_generic_failure; // const arr = []; @@ -84,7 +84,7 @@ const value = arr[123]; The following is the approximate equivalent of the N-API counterpart: -```C +```c napi_status status = napi_generic_failure; // const arr = [] @@ -110,7 +110,7 @@ Object.defineProperties(obj, { The following is the approximate equivalent of the N-API counterpart: -```C +```c napi_status status = napi_status_generic_failure; // const obj = {}; diff --git a/perf_hooks/class_histogram.md b/perf_hooks/class_histogram.md index 595f0f26..aabe3d52 100644 --- a/perf_hooks/class_histogram.md +++ b/perf_hooks/class_histogram.md @@ -1,5 +1,8 @@ -Tracks the event loop delay at a given sampling rate. +Tracks the event loop delay at a given sampling rate. The constructor of +this class not exposed to users. + +_This property is an extension by Node.js. It is not available in Web browsers._ diff --git a/perf_hooks/class_performanceobserver.md b/perf_hooks/class_perf_hooks_performanceobserver.md similarity index 100% rename from perf_hooks/class_performanceobserver.md rename to perf_hooks/class_perf_hooks_performanceobserver.md diff --git a/perf_hooks/class_performancenodetiming_extends_performanceentry.md b/perf_hooks/class_performancenodetiming_extends_performanceentry.md index 75efba21..449793d9 100644 --- a/perf_hooks/class_performancenodetiming_extends_performanceentry.md +++ b/perf_hooks/class_performancenodetiming_extends_performanceentry.md @@ -2,5 +2,8 @@ added: v8.5.0 --> -Provides timing details for Node.js itself. +_This property is an extension by Node.js. It is not available in Web browsers._ + +Provides timing details for Node.js itself. The constructor of this class +is not exposed to users. diff --git a/perf_hooks/class_performanceobserverentrylist.md b/perf_hooks/class_performanceobserverentrylist.md index 1692cad3..5fa19c14 100644 --- a/perf_hooks/class_performanceobserverentrylist.md +++ b/perf_hooks/class_performanceobserverentrylist.md @@ -4,4 +4,5 @@ added: v8.5.0 The `PerformanceObserverEntryList` class is used to provide access to the `PerformanceEntry` instances passed to a `PerformanceObserver`. +The constructor of this class is not exposed to users. diff --git a/perf_hooks/measuring_how_long_it_takes_to_load_dependencies.md b/perf_hooks/measuring_how_long_it_takes_to_load_dependencies.md index d6e6fbcc..ef6fe082 100644 --- a/perf_hooks/measuring_how_long_it_takes_to_load_dependencies.md +++ b/perf_hooks/measuring_how_long_it_takes_to_load_dependencies.md @@ -33,3 +33,7 @@ require('some-module'); + + + + diff --git a/perf_hooks/perf_hooks_monitoreventloopdelay_options.md b/perf_hooks/perf_hooks_monitoreventloopdelay_options.md index 020b29ec..4cb789ac 100644 --- a/perf_hooks/perf_hooks_monitoreventloopdelay_options.md +++ b/perf_hooks/perf_hooks_monitoreventloopdelay_options.md @@ -7,6 +7,8 @@ added: v11.10.0 than zero. **Default:** `10`. * Returns: {Histogram} +_This property is an extension by Node.js. It is not available in Web browsers._ + Creates a `Histogram` object that samples and reports the event loop delay over time. The delays will be reported in nanoseconds. diff --git a/perf_hooks/perf_hooks_performance.md b/perf_hooks/perf_hooks_performance.md new file mode 100644 index 00000000..d6abcc8e --- /dev/null +++ b/perf_hooks/perf_hooks_performance.md @@ -0,0 +1,7 @@ + + +An object that can be used to collect performance metrics from the current +Node.js instance. It is similar to [`window.performance`][] in browsers. + diff --git a/perf_hooks/performance_timing_api.md b/perf_hooks/performance_measurement_apis.md similarity index 63% rename from perf_hooks/performance_timing_api.md rename to perf_hooks/performance_measurement_apis.md index 9fe9935c..de723252 100644 --- a/perf_hooks/performance_timing_api.md +++ b/perf_hooks/performance_measurement_apis.md @@ -3,10 +3,15 @@ > Stability: 2 - Stable -The Performance Timing API provides an implementation of the -[W3C Performance Timeline][] specification. The purpose of the API -is to support collection of high resolution performance metrics. -This is the same Performance API as implemented in modern Web browsers. +This module provides an implementation of a subset of the W3C +[Web Performance APIs][] as well as additional APIs for +Node.js-specific performance measurements. + +Node.js supports the following [Web Performance APIs][]: + +* [High Resolution Time][] +* [Performance Timeline][] +* [User Timing][] ```js const { PerformanceObserver, performance } = require('perf_hooks'); diff --git a/perf_hooks/performance_nodetiming.md b/perf_hooks/performance_nodetiming.md index c0b95fc3..91d7c9ab 100644 --- a/perf_hooks/performance_nodetiming.md +++ b/perf_hooks/performance_nodetiming.md @@ -4,6 +4,8 @@ added: v8.5.0 * {PerformanceNodeTiming} +_This property is an extension by Node.js. It is not available in Web browsers._ + An instance of the `PerformanceNodeTiming` class that provides performance metrics for specific Node.js operational milestones. diff --git a/perf_hooks/performance_timerify_fn.md b/perf_hooks/performance_timerify_fn.md index a52dede2..e711b65b 100644 --- a/perf_hooks/performance_timerify_fn.md +++ b/perf_hooks/performance_timerify_fn.md @@ -4,6 +4,8 @@ added: v8.5.0 * `fn` {Function} +_This property is an extension by Node.js. It is not available in Web browsers._ + Wraps a function within a new function that measures the running time of the wrapped function. A `PerformanceObserver` must be subscribed to the `'function'` event type in order for the timing details to be accessed. diff --git a/perf_hooks/performanceentry_entrytype.md b/perf_hooks/performanceentry_entrytype.md index e944847e..a927f975 100644 --- a/perf_hooks/performanceentry_entrytype.md +++ b/perf_hooks/performanceentry_entrytype.md @@ -4,6 +4,13 @@ added: v8.5.0 * {string} -The type of the performance entry. Currently it may be one of: `'node'`, -`'mark'`, `'measure'`, `'gc'`, `'function'`, `'http2'` or `'http'`. +The type of the performance entry. It may be one of: + +* `'node'` (Node.js only) +* `'mark'` (available on the Web) +* `'measure'` (available on the Web) +* `'gc'` (Node.js only) +* `'function'` (Node.js only) +* `'http2'` (Node.js only) +* `'http'` (Node.js only) diff --git a/perf_hooks/performanceentry_flags.md b/perf_hooks/performanceentry_flags.md index 8f7cffec..7b198908 100644 --- a/perf_hooks/performanceentry_flags.md +++ b/perf_hooks/performanceentry_flags.md @@ -4,6 +4,8 @@ added: v13.9.0 * {number} +_This property is an extension by Node.js. It is not available in Web browsers._ + When `performanceEntry.entryType` is equal to `'gc'`, the `performance.flags` property contains additional information about garbage collection operation. The value may be one of: diff --git a/perf_hooks/performanceentry_kind.md b/perf_hooks/performanceentry_kind.md index c76b8679..a6f3ccac 100644 --- a/perf_hooks/performanceentry_kind.md +++ b/perf_hooks/performanceentry_kind.md @@ -4,6 +4,8 @@ added: v8.5.0 * {number} +_This property is an extension by Node.js. It is not available in Web browsers._ + When `performanceEntry.entryType` is equal to `'gc'`, the `performance.kind` property identifies the type of garbage collection operation that occurred. The value may be one of: diff --git a/policy/enabling.md b/policy/enabling.md index 3311f87a..f30d16f1 100644 --- a/policy/enabling.md +++ b/policy/enabling.md @@ -7,7 +7,7 @@ when loading modules. Once this has been set, all modules must conform to a policy manifest file passed to the flag: -```sh +```bash node --experimental-policy=policy.json app.js ``` @@ -19,7 +19,7 @@ the policy file itself may be provided via `--policy-integrity`. This allows running `node` and asserting the policy file contents even if the file is changed on disk. -```sh +```bash node --experimental-policy=policy.json --policy-integrity="sha384-SggXRQHwCG8g+DktYYzxkXRIkTiEYWBHqev0xnpCxYlqMBufKZHAHQM3/boDaI/0" app.js ``` diff --git a/process/event_uncaughtexception.md b/process/event_uncaughtexception.md index d2accdb7..be6308d1 100644 --- a/process/event_uncaughtexception.md +++ b/process/event_uncaughtexception.md @@ -10,6 +10,7 @@ changes: * `err` {Error} 未捕获的异常。 * `origin` {string} 表明异常是来自未处理的拒绝还是来自同步的错误。 可以是 `'uncaughtException'` 或 `'unhandledRejection'`。 + The latter is only used in conjunction with the [`--unhandled-rejections`][] flag set to `strict` and an unhandled rejection. 当未捕获的 JavaScript 异常一直冒泡回到事件循环时，会触发 `'uncaughtException'` 事件。 默认情况下，Node.js 通过将堆栈跟踪打印到 `stderr` 并使用退出码 `1` 来处理此类异常，从而覆盖任何先前设置的 [`process.exitCode`]。 diff --git a/readline/rl_cursor.md b/readline/rl_cursor.md index 4c0fa6f6..5976ba41 100644 --- a/readline/rl_cursor.md +++ b/readline/rl_cursor.md @@ -7,7 +7,7 @@ added: v0.1.98 The cursor position relative to `rl.line`. This will track where the current cursor lands in the input string, when -reading input from a TTY stream. The position of cursor determines the +reading input from a TTY stream. The position of cursor determines the portion of the input string that will be modified as input is processed, as well as the column where the terminal caret will be rendered. diff --git a/readline/rl_getcursorpos.md b/readline/rl_getcursorpos.md index a267ee8b..8bdaa968 100644 --- a/readline/rl_getcursorpos.md +++ b/readline/rl_getcursorpos.md @@ -9,6 +9,6 @@ added: * `cols` {number} the screen column the cursor currently lands on Returns the real position of the cursor in relation to the input -prompt + string. Long input (wrapping) strings, as well as multiple +prompt + string. Long input (wrapping) strings, as well as multiple line prompts are included in the calculations. diff --git a/readline/rl_line.md b/readline/rl_line.md index e6f938c2..b6c5dd60 100644 --- a/readline/rl_line.md +++ b/readline/rl_line.md @@ -8,7 +8,7 @@ The current input data being processed by node. This can be used when collecting input from a TTY stream to retrieve the current value that has been processed thus far, prior to the `line` event -being emitted. Once the `line` event has been emitted, this property will +being emitted. Once the `line` event has been emitted, this property will be an empty string. Be aware that modifying the value during the instance runtime may have diff --git a/readline/tty_keybindings.md b/readline/tty_keybindings.md index 382d1b0f..ef2e87a8 100644 --- a/readline/tty_keybindings.md +++ b/readline/tty_keybindings.md @@ -13,7 +13,7 @@ ctrl + shift + delete Delete line right - Doesn't work on Linux and Mac + Doesn't work on Mac ctrl + c @@ -87,7 +87,7 @@ + backspace Delete backwards to a word boundary ctrl + backspace Doesn't - work as expected on Windows + work on Linux, Mac and Windows ctrl + delete diff --git a/repl/commands_and_special_keys.md b/repl/commands_and_special_keys.md index cacbb826..eabea2ca 100644 --- a/repl/commands_and_special_keys.md +++ b/repl/commands_and_special_keys.md @@ -2,7 +2,7 @@ 所有 REPL 的实例都支持下列特殊命令： * `.break` - 在输入一个多行表达式的过程中，输入 `.break` 命令（或按下 `-C` 组合键）将终止表达式的继续输入。 -* `.clear` - 重置 REPL 的 `context` 为一个空对象，并清除当前正输入的所有多行表达式。 +* `.clear` - 重置 REPL 的 `context` 为一个空对象，并清除正在输入中的所有多行表达式。 * `.exit` - 关闭输入输出流，退出 REPL。 * `.help` - 显示特定命令的帮助列表。 * `.save` - 保存当前 REPL 会话到一个文件： diff --git a/repl/repl_builtinmodules.md b/repl/repl_builtinmodules.md new file mode 100644 index 00000000..9b9454a9 --- /dev/null +++ b/repl/repl_builtinmodules.md @@ -0,0 +1,8 @@ + + +* {string[]} + +A list of the names of all Node.js modules, e.g., `'http'`. + diff --git a/report/usage.md b/report/usage.md index a6df455f..9cc6a2dd 100644 --- a/report/usage.md +++ b/report/usage.md @@ -112,7 +112,7 @@ containing `libuv` handle information and an OS platform information section showing CPU and memory usage and system limits. An example report can be triggered using the Node.js REPL: -```raw +```console $ node > process.report.writeReport(); Writing Node.js report to file: report.20181126.091102.8480.0.001.json diff --git a/stream/buffering.md b/stream/buffering.md index 3743bd0a..6c401146 100644 --- a/stream/buffering.md +++ b/stream/buffering.md @@ -19,6 +19,11 @@ `stream` API 的主要目标，特别是 [`stream.pipe()`]，是为了限制数据的缓冲到可接受的程度，也就是读写速度不一致的源头与目的地不会压垮内存。 +The `highWaterMark` option is a threshold, not a limit: it dictates the amount +of data that a stream buffers before it stops asking for more data. It does not +enforce a strict memory limitation in general. Specific stream implementations +may choose to enforce stricter limits but doing so is optional. + 因为 [`Duplex`] 和 [`Transform`] 都是可读又可写的，所以它们各自维护着两个相互独立的内部缓冲器用于读取和写入， 这使得它们在维护数据流时，读取和写入两边可以各自独立地运作。 例如，[`net.Socket`] 实例是 [`Duplex`] 流，它的可读端可以消费从 socket 接收的数据，而可写端则可以将数据写入到 socket。 diff --git a/stream/event_end_1.md b/stream/event_end_1.md new file mode 100644 index 00000000..f2862cfc --- /dev/null +++ b/stream/event_end_1.md @@ -0,0 +1,4 @@ + +[`'end'`] 事件来自 `stream.Readable` 类。 +当调用了 [`transform._flush()`][stream-_flush] 中的回调函数并且所有数据已经输出之后，触发 `'end'` 事件。 +如果出现错误，则不应触发 `'end'`。 diff --git a/stream/event_finish_1.md b/stream/event_finish_1.md new file mode 100644 index 00000000..a9183b04 --- /dev/null +++ b/stream/event_finish_1.md @@ -0,0 +1,5 @@ + +[`'finish'`] 事件来自 `stream.Writable` 类。 +当调用了 [`stream.end()`][stream-end] 并且 [`stream._transform()`][stream-_transform] 处理完全部数据块之后，触发 `'finish'` 事件。 +如果出现错误，则不应触发 `'finish'`。 + diff --git a/stream/event_readable.md b/stream/event_readable.md index c19006a2..730cbfa0 100644 --- a/stream/event_readable.md +++ b/stream/event_readable.md @@ -13,7 +13,7 @@ changes: 当有数据可从流中读取时，就会触发 `'readable'` 事件。 在某些情况下，为 `'readable'` 事件附加监听器将会导致将一些数据读入内部缓冲区。 -```javascript +```js const readable = getReadableStreamSomehow(); readable.on('readable', function() { // 有数据可读取。 diff --git a/stream/events_finish_and_end.md b/stream/events_finish_and_end.md deleted file mode 100644 index b0d47ea5..00000000 --- a/stream/events_finish_and_end.md +++ /dev/null @@ -1,5 +0,0 @@ -[`'finish'`] 事件来自 `stream.Writable` 类，[`'end'`] 事件来自 `stream.Readable` 类。 -当调用了 [`stream.end()`][stream-end] 并且 [`stream._transform()`][stream-_transform] 处理完全部数据块之后，触发 `'finish'` 事件。 -当调用了 [`transform._flush()`][stream-_flush] 中的回调函数并且所有数据已经输出之后，触发 `'end'` 事件。 -如果出现错误，则不应触发 `'finish'` 或 `'end'`。 - diff --git a/stream/implementing_a_duplex_stream.md b/stream/implementing_a_duplex_stream.md index ddc041f4..664a4dc6 100644 --- a/stream/implementing_a_duplex_stream.md +++ b/stream/implementing_a_duplex_stream.md @@ -5,4 +5,4 @@ `stream.Duplex` 类的原型继承自 `stream.Readable` 和寄生自 `stream.Writable`，但是 `instanceof` 对这两个基础类都可用，因为重写了 `stream.Writable` 的 [`Symbol.hasInstance`]。 -自定义的双工流必须调用 `new stream.Duplex([options])` 构造函数并实现 `readable._read()` 和 `writable._write()` 方法。 +自定义的双工流必须调用 `new stream.Duplex([options])` 构造函数并实现 [`readable._read()`] 和 `writable._write()` 方法。 diff --git a/stream/implementing_a_readable_stream.md b/stream/implementing_a_readable_stream.md index 89c48082..41f3cc42 100644 --- a/stream/implementing_a_readable_stream.md +++ b/stream/implementing_a_readable_stream.md @@ -1,5 +1,5 @@ `stream.Readable` 类可用于实现可读流。 -自定义的可读流必须调用 `new stream.Readable([options])` 构造函数并实现 `readable._read()` 方法。 +自定义的可读流必须调用 `new stream.Readable([options])` 构造函数并实现 [`readable._read()`] 方法。 diff --git a/stream/implementing_a_transform_stream.md b/stream/implementing_a_transform_stream.md index 619f4c31..923884e8 100644 --- a/stream/implementing_a_transform_stream.md +++ b/stream/implementing_a_transform_stream.md @@ -7,7 +7,7 @@ `stream.Transform` 类可用于实现了一个[转换流]。 -`stream.Transform` 类继承自 `stream.Duplex`，并且实现了自有的 `writable._write()` 和 `readable._read()` 方法。 +`stream.Transform` 类继承自 `stream.Duplex`，并且实现了自有的 `writable._write()` 和 [`readable._read()`] 方法。 自定义的转换流必须实现 [`transform._transform()`][stream-_transform] 方法，[`transform._flush()`][stream-_flush] 方法是可选的。 当使用转换流时，如果可读端的输出没有被消费，则写入流的数据可能会导致可写端被暂停。 diff --git a/stream/constructor_new_stream_writable_options.md b/stream/new_stream_writable_options.md similarity index 100% rename from stream/constructor_new_stream_writable_options.md rename to stream/new_stream_writable_options.md diff --git a/stream/piping_to_writable_streams_from_async_iterators.md b/stream/piping_to_writable_streams_from_async_iterators.md index 43acef5f..fe6fbe5c 100644 --- a/stream/piping_to_writable_streams_from_async_iterators.md +++ b/stream/piping_to_writable_streams_from_async_iterators.md @@ -1,71 +1,31 @@ -在从异步迭代器写入可写流的场景中，应确保正确地处理背压和错误。 +When writing to a writable stream from an async iterator, ensure correct +handling of backpressure and errors. [`stream.pipeline()`][] abstracts away +the handling of backpressure and backpressure-related errors: ```js -const { once } = require('events'); -const finished = util.promisify(stream.finished); +const { pipeline } = require('stream'); +const util = require('util'); +const fs = require('fs'); const writable = fs.createWriteStream('./file'); -function drain(writable) { - if (writable.destroyed) { - return Promise.reject(new Error('过早关闭')); +// Callback Pattern +pipeline(iterator, writable, (err, value) => { + if (err) { + console.error(err); + } else { + console.log(value, 'value returned'); } - return Promise.race([ - once(writable, 'drain'), - once(writable, 'close') - .then(() => Promise.reject(new Error('过早关闭'))) - ]); -} - -async function pump(iterable, writable) { - for await (const chunk of iterable) { - // 处理 write() 上的背压。 - if (!writable.write(chunk)) { - await drain(writable); - } - } - writable.end(); -} - -(async function() { - // 确保完成没有错误。 - await Promise.all([ - pump(iterable, writable), - finished(writable) - ]); -})(); -``` - -在上面的示例中，`once()` 监听器会为 `'drain'` 事件捕获并抛出 `write()` 上的错误，因为 `once()` 也会处理 `'error'` 事件。 -为了确保写入流的完成且没有错误，使用上面的 `finished()` 方法比使用 `'finish'` 事件的 `once()` 监听器更为安全。 -在某些情况下，`'finish'` 之后可写流可能会触发 `'error'` 事件，并且 `once()` 将会在处理 `'finish'` 事件时释放 `'error'` 处理程序，这可能导致未处理的错误。 - -另外，可读流可以用 `Readable.from()` 封装，然后通过 `.pipe()` 传送： - -```js -const finished = util.promisify(stream.finished); - -const writable = fs.createWriteStream('./file'); - -(async function() { - const readable = Readable.from(iterable); - readable.pipe(writable); - // 确保完成没有错误。 - await finished(writable); -})(); -``` - -或者，使用 `stream.pipeline()` 传送流： - -```js -const pipeline = util.promisify(stream.pipeline); - -const writable = fs.createWriteStream('./file'); - -(async function() { - await pipeline(iterable, writable); -})(); +}); + +// Promise Pattern +const pipelinePromise = util.promisify(pipeline); +pipelinePromise(iterator, writable) + .then((value) => { + console.log(value, 'value returned'); + }) + .catch(console.error); ``` diff --git a/stream/readable_push_chunk_encoding.md b/stream/readable_push_chunk_encoding.md index 58b71793..09745209 100644 --- a/stream/readable_push_chunk_encoding.md +++ b/stream/readable_push_chunk_encoding.md @@ -53,7 +53,7 @@ class SourceWrapper extends Readable { ``` `readable.push()` 方法用于将内容推入内部的 buffer。 -它可以由 `readable._read()` 方法驱动。 +它可以由 [`readable._read()`] 方法驱动。 对于非对象模式的流，如果 `readable.push()` 的 `chunk` 参数为 `undefined`，则它会被当成空字符串或 buffer。 详见 [`readable.push('')`]。 diff --git a/stream/readable_read_size_1.md b/stream/readable_read_size_1.md index 5c2d79f3..64941a21 100644 --- a/stream/readable_read_size_1.md +++ b/stream/readable_read_size_1.md @@ -7,18 +7,18 @@ added: v0.9.4 该函数不能被应用程序代码直接调用。 它应该由子类实现，且只能被内部的 `Readable` 类的方法调用。 -所有可读流的实现必须提供 `readable._read()` 方法从底层资源获取数据。 +所有可读流的实现必须提供 [`readable._read()`] 方法从底层资源获取数据。 -当 `readable._read()` 被调用时，如果从资源读取到数据，则需要开始使用 [`this.push(dataChunk)`][stream-push] 推送数据到读取队列。 +当 [`readable._read()`] 被调用时，如果从资源读取到数据，则需要开始使用 [`this.push(dataChunk)`][stream-push] 推送数据到读取队列。 `_read()` 应该持续从资源读取数据并推送数据，直到 `readable.push()` 返回 `false`。 若想再次调用 `_read()` 方法，则需要恢复推送数据到队列。 -一旦 `readable._read()` 方法被调用，将不会再次调用它，直到更多数据通过 [`readable.push()`][stream-push] 方法被推送。 -空的数据（例如空的 buffer 和字符串）将不会导致 `readable._read()` 被调用。 +一旦 [`readable._read()`] 方法被调用，将不会再次调用它，直到更多数据通过 [`readable.push()`][stream-push] 方法被推送。 +空的数据（例如空的 buffer 和字符串）将不会导致 [`readable._read()`] 被调用。 `size` 是可选的参数。 对于读取是一个单一操作的实现，可以使用 `size` 参数来决定要读取多少数据。 对于其他的实现，可以忽略这个参数，只要有数据就提供数据。 不需要等待指定 `size` 字节的数据在调用 [`stream.push(chunk)`][stream-push]。 -`readable._read()` 方法有下划线前缀，因为它是在定义在类的内部，不应该被用户程序直接调用。 +[`readable._read()`] 方法有下划线前缀，因为它是在定义在类的内部，不应该被用户程序直接调用。 diff --git a/stream/writable_write_chunk_encoding_callback.md b/stream/writable_write_chunk_encoding_callback.md index 5465fcd4..b642b5ae 100644 --- a/stream/writable_write_chunk_encoding_callback.md +++ b/stream/writable_write_chunk_encoding_callback.md @@ -13,7 +13,7 @@ changes: * `chunk` {string|Buffer|Uint8Array|any} 要写入的数据。  对于非对象模式的流，`chunk` 必须是字符串、`Buffer` 或 `Uint8Array`。 对于对象模式的流，`chunk` 可以是任何 JavaScript 值，除了 `null`。 -* `encoding` {string} 如果 `chunk` 是字符串，则指定字符编码。 +* `encoding` {string} 如果 `chunk` 是字符串，则指定字符编码。**默认值:** `'utf8'`。 * `callback` {Function} 当数据块被输出到目标后的回调函数。 * 返回: {boolean} 如果流需要等待 `'drain'` 事件触发才能继续写入更多数据，则返回 `false`，否则返回 `true`。 diff --git a/tls/event_session.md b/tls/event_session.md index 9ed4dbc9..5ec4c385 100644 --- a/tls/event_session.md +++ b/tls/event_session.md @@ -18,12 +18,12 @@ On the client, the `session` can be provided to the `session` option of See [Session Resumption][] for more information. For TLSv1.2 and below, [`tls.TLSSocket.getSession()`][] can be called once -the handshake is complete. For TLSv1.3, only ticket-based resumption is allowed +the handshake is complete. For TLSv1.3, only ticket-based resumption is allowed by the protocol, multiple tickets are sent, and the tickets aren't sent until after the handshake completes. So it is necessary to wait for the -`'session'` event to get a resumable session. Applications +`'session'` event to get a resumable session. Applications should use the `'session'` event instead of `getSession()` to ensure -they will work for all TLS versions. Applications that only expect to +they will work for all TLS versions. Applications that only expect to get or use one session should listen for this event only once: ```js diff --git a/tls/modifying_the_default_tls_cipher_suite.md b/tls/modifying_the_default_tls_cipher_suite.md index e11d94c0..d58e1f2e 100644 --- a/tls/modifying_the_default_tls_cipher_suite.md +++ b/tls/modifying_the_default_tls_cipher_suite.md @@ -1,40 +1,45 @@ -Node.js 构造时包含了默认的 TLS 开启和关闭的加密组件。 -目前默认的加密组件是： - -```txt -TLS_AES_256_GCM_SHA384: -TLS_CHACHA20_POLY1305_SHA256: -TLS_AES_128_GCM_SHA256: -ECDHE-RSA-AES128-GCM-SHA256: -ECDHE-ECDSA-AES128-GCM-SHA256: -ECDHE-RSA-AES256-GCM-SHA384: -ECDHE-ECDSA-AES256-GCM-SHA384: -DHE-RSA-AES128-GCM-SHA256: -ECDHE-RSA-AES128-SHA256: -DHE-RSA-AES128-SHA256: -ECDHE-RSA-AES256-SHA384: -DHE-RSA-AES256-SHA384: -ECDHE-RSA-AES256-SHA256: -DHE-RSA-AES256-SHA256: -HIGH: -!aNULL: -!eNULL: -!EXPORT: -!DES: -!RC4: -!MD5: -!PSK: -!SRP: +Node.js 构造时包含了默认的 TLS 开启和关闭的加密组件。This +default cipher list can be configured when building Node.js to allow +distributions to provide their own default list. + +The following command can be used to show the default cipher suite: + +```console +node -p crypto.constants.defaultCoreCipherList | tr ':' '\n' +TLS_AES_256_GCM_SHA384 +TLS_CHACHA20_POLY1305_SHA256 +TLS_AES_128_GCM_SHA256 +ECDHE-RSA-AES128-GCM-SHA256 +ECDHE-ECDSA-AES128-GCM-SHA256 +ECDHE-RSA-AES256-GCM-SHA384 +ECDHE-ECDSA-AES256-GCM-SHA384 +DHE-RSA-AES128-GCM-SHA256 +ECDHE-RSA-AES128-SHA256 +DHE-RSA-AES128-SHA256 +ECDHE-RSA-AES256-SHA384 +DHE-RSA-AES256-SHA384 +ECDHE-RSA-AES256-SHA256 +DHE-RSA-AES256-SHA256 +HIGH +!aNULL +!eNULL +!EXPORT +!DES +!RC4 +!MD5 +!PSK +!SRP !CAMELLIA ``` + 默认加密组件可以使用 [`--tls-cipher-list`] 命令进行替换（直接或通过 [`NODE_OPTIONS`] 环境变量）。 比如，生成 `ECDHE-RSA-AES128-GCM-SHA256:!RC4` 的 TLS 加密组件： -```sh -node --tls-cipher-list="ECDHE-RSA-AES128-GCM-SHA256:!RC4" server.js +```bash +node --tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4' server.js -export NODE_OPTIONS=--tls-cipher-list="ECDHE-RSA-AES128-GCM-SHA256:!RC4" +export NODE_OPTIONS=--tls-cipher-list='ECDHE-RSA-AES128-GCM-SHA256:!RC4' node server.js ``` diff --git a/tls/perfect_forward_secrecy.md b/tls/perfect_forward_secrecy.md index bcc2a3ee..4c14fea4 100644 --- a/tls/perfect_forward_secrecy.md +++ b/tls/perfect_forward_secrecy.md @@ -18,7 +18,7 @@ TLS/SSL 握手时，使用完全前向即每次会话都会随机生成一个临 如需使用完全前向加密，例如使用 `tls` 模块的 `DHE` 算法，使用之前需要生成一个 Diffie-Hellman 参数并将其用 `dhparam` 声明在 [`tls.createSecureContext()`][] 中。 如下例子展示了如何使用 OpenSSL 命令生成参数： -```sh +```bash openssl dhparam -outform PEM -out dhparam.pem 2048 ``` 如需使用 `ECDHE` 算法，则不需要生成 Diffie-Hellman 参数，因为可以使用默认的 ECDHE 曲线。 diff --git a/tls/session_resumption.md b/tls/session_resumption.md index fbf7f9d3..497f95bf 100644 --- a/tls/session_resumption.md +++ b/tls/session_resumption.md @@ -72,7 +72,7 @@ failures, it is easy to not notice unnecessarily poor TLS performance. The OpenSSL CLI can be used to verify that servers are resuming sessions. Use the `-reconnect` option to `openssl s_client`, for example: -```sh +```console $ openssl s_client -connect localhost:443 -reconnect ``` diff --git a/tls/tls_connect_options_callback.md b/tls/tls_connect_options_callback.md index 006bf61b..ebf84d9b 100644 --- a/tls/tls_connect_options_callback.md +++ b/tls/tls_connect_options_callback.md @@ -121,6 +121,12 @@ The `callback` function, if specified, will be added as a listener for the `tls.connect()` returns a [`tls.TLSSocket`][] object. +Unlike the `https` API, `tls.connect()` does not enable the +SNI (Server Name Indication) extension by default, which may cause some +servers to return an incorrect certificate or reject the connection +altogether. To enable SNI, set the `servername` option in addition +to `host`. + The following illustrates a client for the echo server example from [`tls.createServer()`][]: diff --git a/tls/tls_createsecurecontext_options.md b/tls/tls_createsecurecontext_options.md index d57480d6..a36bdd91 100644 --- a/tls/tls_createsecurecontext_options.md +++ b/tls/tls_createsecurecontext_options.md @@ -144,11 +144,11 @@ changes: [OpenSSL Options][]. * `secureProtocol` {string} Legacy mechanism to select the TLS protocol version to use, it does not support independent control of the minimum and - maximum version, and does not support limiting the protocol to TLSv1.3. Use - `minVersion` and `maxVersion` instead. The possible values are listed as - [SSL_METHODS][], use the function names as strings. For example, use + maximum version, and does not support limiting the protocol to TLSv1.3. Use + `minVersion` and `maxVersion` instead. The possible values are listed as + [SSL_METHODS][], use the function names as strings. For example, use `'TLSv1_1_method'` to force TLS version 1.1, or `'TLS_method'` to allow any - TLS protocol version up to TLSv1.3. It is not recommended to use TLS + TLS protocol version up to TLSv1.3. It is not recommended to use TLS versions less than 1.2, but it may be required for interoperability. **Default:** none, see `minVersion`. * `sessionIdContext` {string} Opaque identifier used by servers to ensure diff --git a/tls/tls_default_max_version.md b/tls/tls_default_max_version.md index 7a4bec52..9456be65 100644 --- a/tls/tls_default_max_version.md +++ b/tls/tls_default_max_version.md @@ -6,7 +6,7 @@ added: v11.4.0 [`tls.createSecureContext()`][]. It can be assigned any of the supported TLS protocol versions, `'TLSv1.3'`, `'TLSv1.2'`, `'TLSv1.1'`, or `'TLSv1'`. **Default:** `'TLSv1.3'`, unless changed using CLI options. Using - `--tls-max-v1.2` sets the default to `'TLSv1.2'`. Using `--tls-max-v1.3` sets + `--tls-max-v1.2` sets the default to `'TLSv1.2'`. Using `--tls-max-v1.3` sets the default to `'TLSv1.3'`. If multiple of the options are provided, the highest maximum is used. diff --git a/tls/tls_rootcertificates.md b/tls/tls_rootcertificates.md index 879dd5f4..566b5bea 100644 --- a/tls/tls_rootcertificates.md +++ b/tls/tls_rootcertificates.md @@ -5,6 +5,8 @@ added: v12.3.0 * {string[]} An immutable array of strings representing the root certificates (in PEM format) -used for verifying peer certificates. This is the default value of the `ca` -option to [`tls.createSecureContext()`][]. +from the bundled Mozilla CA store as supplied by current Node.js version. + +The bundled CA store, as supplied by Node.js, is a snapshot of Mozilla CA store +that is fixed at release time. It is identical on all supported platforms. diff --git a/tracing/trace_events.md b/tracing/trace_events.md index 39c283b0..ff958faa 100644 --- a/tracing/trace_events.md +++ b/tracing/trace_events.md @@ -35,7 +35,7 @@ The available categories are: By default the `node`, `node.async_hooks`, and `v8` categories are enabled. -```txt +```bash node --trace-event-categories v8,node,node.async_hooks server.js ``` @@ -44,10 +44,10 @@ flag to enable trace events. This requirement has been removed. However, the `--trace-events-enabled` flag *may* still be used and will enable the `node`, `node.async_hooks`, and `v8` trace event categories by default. -```txt +```bash node --trace-events-enabled -// is equivalent to +# is equivalent to node --trace-event-categories v8,node,node.async_hooks ``` @@ -73,7 +73,7 @@ The logging file is by default called `node_trace.${rotation}.log`, where be specified with `--trace-event-file-pattern` that accepts a template string that supports `${rotation}` and `${pid}`: -```txt +```bash node --trace-event-categories v8 --trace-event-file-pattern '${pid}-${rotation}.log' server.js ``` diff --git a/tty/tty.md b/tty/tty.md index 0160db32..9d19648a 100644 --- a/tty/tty.md +++ b/tty/tty.md @@ -14,7 +14,7 @@ const tty = require('tty'); 当 Node.js 检测到它被运行时附加了一个文本终端（TTY），则默认情况下，[`process.stdin`] 会被初始化为 `tty.ReadStream` 的实例，[`process.stdout`] 和 [`process.stderr`] 会被初始化为 `tty.WriteStream` 的实例。 判断 Node.js 是否被运行在一个 TTY 上下文中的首选方法是检查 `process.stdout.isTTY` 属性的值是否为 `true`： -```sh +```console $ node -p -e "Boolean(process.stdout.isTTY)" true $ node -p -e "Boolean(process.stdout.isTTY)" | cat diff --git a/url/constructor_new_urlsearchparams.md b/url/constructor_new_urlsearchparams.md deleted file mode 100644 index 42953528..00000000 --- a/url/constructor_new_urlsearchparams.md +++ /dev/null @@ -1,3 +0,0 @@ - -实例化一个新的空的`URLSearchParams`对象。 - diff --git a/url/legacy_api.md b/url/legacy_api.md index f8b64a9a..5ad2c0cc 100644 --- a/url/legacy_api.md +++ b/url/legacy_api.md @@ -1,7 +1,7 @@ 在传统的 API 中，空格（`' '`）及以下字符将自动转义为 URL 对象的属性： -```txt +```text < > " ` \r \n \t { } | \ ^ ' ``` diff --git a/url/constructor_new_url_input_base.md b/url/new_url_input_base.md similarity index 100% rename from url/constructor_new_url_input_base.md rename to url/new_url_input_base.md diff --git a/url/new_urlsearchparams.md b/url/new_urlsearchparams.md new file mode 100644 index 00000000..00d7beb5 --- /dev/null +++ b/url/new_urlsearchparams.md @@ -0,0 +1,3 @@ + +实例化一个新的空的 `URLSearchParams` 对象。 + diff --git a/url/constructor_new_urlsearchparams_iterable.md b/url/new_urlsearchparams_iterable.md similarity index 100% rename from url/constructor_new_urlsearchparams_iterable.md rename to url/new_urlsearchparams_iterable.md diff --git a/url/constructor_new_urlsearchparams_obj.md b/url/new_urlsearchparams_obj.md similarity index 100% rename from url/constructor_new_urlsearchparams_obj.md rename to url/new_urlsearchparams_obj.md diff --git a/url/constructor_new_urlsearchparams_string.md b/url/new_urlsearchparams_string.md similarity index 100% rename from url/constructor_new_urlsearchparams_string.md rename to url/new_urlsearchparams_string.md diff --git a/url/url_pathtofileurl_path.md b/url/url_pathtofileurl_path.md index e541583a..381a92ee 100644 --- a/url/url_pathtofileurl_path.md +++ b/url/url_pathtofileurl_path.md @@ -16,7 +16,7 @@ pathToFileURL(__filename); // 正确: file:///C:/... (Windows) new URL('/foo#1', 'file:'); // 错误: file:///foo#1 pathToFileURL('/foo#1'); // 正确: file:///foo%231 (POSIX) -new URL('/some/path%.js', 'file:'); // 错误: file:///some/path% -pathToFileURL('/some/path%.js'); // 正确: file:///some/path%25 (POSIX) +new URL('/some/path%.c', 'file:'); // 错误: file:///some/path%.c +pathToFileURL('/some/path%.c'); // 正确: file:///some/path%25.c (POSIX) ``` diff --git a/url/url_strings_and_url_objects.md b/url/url_strings_and_url_objects.md index e8213978..08a8cd2e 100644 --- a/url/url_strings_and_url_objects.md +++ b/url/url_strings_and_url_objects.md @@ -10,7 +10,7 @@ WHATWG 的 API 与传统的 API 的区别如下。 WHATWG 的 `origin` 属性包括 `protocol` 和 `host`，但不包括 `username` 或 `password`。 -```txt +```text ┌────────────────────────────────────────────────────────────────────────────────────────────────┐ │ href │ ├──────────┬──┬─────────────────────┬────────────────────────┬───────────────────────────┬───────┤ diff --git a/util/util_callbackify_original.md b/util/util_callbackify_original.md index b7d30da8..9da96c5c 100644 --- a/util/util_callbackify_original.md +++ b/util/util_callbackify_original.md @@ -24,7 +24,7 @@ callbackFunction((err, ret) => { 将会打印出： -```txt +```text hello world ``` diff --git a/util/util_debuglog_section.md b/util/util_debuglog_section.md index ce139af5..af5e7e8a 100644 --- a/util/util_debuglog_section.md +++ b/util/util_debuglog_section.md @@ -18,7 +18,7 @@ debuglog('hello from foo [%d]', 123); 如果程序在环境中运行时带上 `NODE_DEBUG=foo`，则输出类似如下： -```txt +```console FOO 3245: hello from foo [123] ``` @@ -36,7 +36,7 @@ debuglog('hi there, it\'s foo-bar [%d]', 2333); 如果在环境中使用 `NODE_DEBUG=foo*` 运行，那么它将输出如下内容： -```txt +```console FOO-BAR 3257: hi there, it's foo-bar [2333] ``` diff --git a/util/util_format_format_args.md b/util/util_format_format_args.md index c02acc60..6beff3d3 100644 --- a/util/util_format_format_args.md +++ b/util/util_format_format_args.md @@ -47,7 +47,7 @@ changes: * `%j` - JSON。如果参数包含循环引用，则替换为字符串 `'[Circular]'`。 * `%o` - `Object`。具有通用 JavaScript 对象格式的对象的字符串表示形式。 类似于带有选项 `{ showHidden: true, showProxy: true }` 的 `util.inspect()`。 这将显示完整对象，包括非可枚举属性和代理。 * `%O` - `Object`。具有通用 JavaScript 对象格式的对象的字符串表示形式。 类似于 `util.inspect()` 但没有选项。 这将显示完整对象，不包括非可枚举属性和代理。 -* `%c` - `CSS`。该说明符当前会被忽略，将会跳过任何传入的 CSS。 +* `%c` - `CSS`。该说明符会被忽略，将会跳过任何传入的 CSS。 * `%%` - 单个百分号（`'%'`）。这不会消耗参数。 * 返回: {string} 格式化的字符串。 diff --git a/util/util_types_isarraybufferview_value.md b/util/util_types_isarraybufferview_value.md index 1a31ca30..b14009bf 100644 --- a/util/util_types_isarraybufferview_value.md +++ b/util/util_types_isarraybufferview_value.md @@ -6,7 +6,7 @@ added: v10.0.0 * Returns: {boolean} Returns `true` if the value is an instance of one of the [`ArrayBuffer`][] -views, such as typed array objects or [`DataView`][]. Equivalent to +views, such as typed array objects or [`DataView`][]. Equivalent to [`ArrayBuffer.isView()`][]. ```js diff --git a/vm/class_vm_module.md b/vm/class_vm_module.md index bfbec3e5..0ea21575 100644 --- a/vm/class_vm_module.md +++ b/vm/class_vm_module.md @@ -24,7 +24,7 @@ linking, and evaluation. These three steps are illustrated in the following example. This implementation lies at a lower level than the [ECMAScript Module -loader][]. There is also currently no way to interact with the Loader, though +loader][]. There is also no way to interact with the Loader yet, though support is planned. ```js diff --git a/vm/constructor_new_vm_script_code_options.md b/vm/new_vm_script_code_options.md similarity index 100% rename from vm/constructor_new_vm_script_code_options.md rename to vm/new_vm_script_code_options.md diff --git a/vm/constructor_new_vm_sourcetextmodule_code_options.md b/vm/new_vm_sourcetextmodule_code_options.md similarity index 100% rename from vm/constructor_new_vm_sourcetextmodule_code_options.md rename to vm/new_vm_sourcetextmodule_code_options.md diff --git a/vm/constructor_new_vm_syntheticmodule_exportnames_evaluatecallback_options.md b/vm/new_vm_syntheticmodule_exportnames_evaluatecallback_options.md similarity index 100% rename from vm/constructor_new_vm_syntheticmodule_exportnames_evaluatecallback_options.md rename to vm/new_vm_syntheticmodule_exportnames_evaluatecallback_options.md diff --git a/wasi/new_wasi_options.md b/wasi/new_wasi_options.md index 42685023..588aa3c2 100644 --- a/wasi/new_wasi_options.md +++ b/wasi/new_wasi_options.md @@ -18,4 +18,10 @@ added: process via the `__wasi_proc_exit()` function. Setting this option to `true` causes `wasi.start()` to return the exit code rather than terminate the process. **Default:** `false`. + * `stdin` {integer} The file descriptor used as standard input in the + WebAssembly application. **Default:** `0`. + * `stdout` {integer} The file descriptor used as standard output in the + WebAssembly application. **Default:** `1`. + * `stderr` {integer} The file descriptor used as standard error in the + WebAssembly application. **Default:** `2`. diff --git a/wasi/webassembly_system_interface_wasi.md b/wasi/webassembly_system_interface_wasi.md index fc926366..6d20ea81 100644 --- a/wasi/webassembly_system_interface_wasi.md +++ b/wasi/webassembly_system_interface_wasi.md @@ -21,13 +21,52 @@ const wasi = new WASI({ const importObject = { wasi_snapshot_preview1: wasi.wasiImport }; (async () => { - const wasm = await WebAssembly.compile(fs.readFileSync('./binary.wasm')); + const wasm = await WebAssembly.compile(fs.readFileSync('./demo.wasm')); const instance = await WebAssembly.instantiate(wasm, importObject); wasi.start(instance); })(); ``` +To run the above example, create a new WebAssembly text format file named +`demo.wat`: + +```text +(module + ;; Import the required fd_write WASI function which will write the given io vectors to stdout + ;; The function signature for fd_write is: + ;; (File Descriptor, *iovs, iovs_len, nwritten) -> Returns number of bytes written + (import "wasi_snapshot_preview1" "fd_write" (func $fd_write (param i32 i32 i32 i32) (result i32))) + + (memory 1) + (export "memory" (memory 0)) + + ;; Write 'hello world\n' to memory at an offset of 8 bytes + ;; Note the trailing newline which is required for the text to appear + (data (i32.const 8) "hello world\n") + + (func $main (export "_start") + ;; Creating a new io vector within linear memory + (i32.store (i32.const 0) (i32.const 8)) ;; iov.iov_base - This is a pointer to the start of the 'hello world\n' string + (i32.store (i32.const 4) (i32.const 12)) ;; iov.iov_len - The length of the 'hello world\n' string + + (call $fd_write + (i32.const 1) ;; file_descriptor - 1 for stdout + (i32.const 0) ;; *iovs - The pointer to the iov array, which is stored at memory location 0 + (i32.const 1) ;; iovs_len - We're printing 1 string stored in an iov - so one. + (i32.const 20) ;; nwritten - A place in memory to store the number of bytes written + ) + drop ;; Discard the number of bytes written from the top of the stack + ) +) +``` + +Use [wabt](https://github.com/WebAssembly/wabt) to compile `.wat` to `.wasm` + +```console +$ wat2wasm demo.wat +``` + The `--experimental-wasi-unstable-preview1` and `--experimental-wasm-bigint` -CLI arguments are needed for the previous example to run. +CLI arguments are needed for this example to run. diff --git a/worker_threads/considerations_when_transferring_typedarrays_and_buffers.md b/worker_threads/considerations_when_transferring_typedarrays_and_buffers.md index 85a04fbe..1b3df639 100644 --- a/worker_threads/considerations_when_transferring_typedarrays_and_buffers.md +++ b/worker_threads/considerations_when_transferring_typedarrays_and_buffers.md @@ -25,6 +25,9 @@ For `Buffer` instances, specifically, whether the underlying `ArrayBuffer` can be transferred or cloned depends entirely on how instances were created, which often cannot be reliably determined. +An `ArrayBuffer` can be marked with [`markAsUntransferable()`][] to indicate +that it should always be cloned and never transferred. + Depending on how a `Buffer` instance was created, it may or may not own its underlying `ArrayBuffer`. An `ArrayBuffer` must not be transferred unless it is known that the `Buffer` instance diff --git a/worker_threads/event_messageerror.md b/worker_threads/event_messageerror.md new file mode 100644 index 00000000..553400a3 --- /dev/null +++ b/worker_threads/event_messageerror.md @@ -0,0 +1,8 @@ + + +* `error` {Error} An Error object + +The `'messageerror'` event is emitted when deserializing a message failed. + diff --git a/worker_threads/event_messageerror_1.md b/worker_threads/event_messageerror_1.md new file mode 100644 index 00000000..553400a3 --- /dev/null +++ b/worker_threads/event_messageerror_1.md @@ -0,0 +1,8 @@ + + +* `error` {Error} An Error object + +The `'messageerror'` event is emitted when deserializing a message failed. + diff --git a/worker_threads/port_postmessage_value_transferlist.md b/worker_threads/port_postmessage_value_transferlist.md index 6018d533..898deaa2 100644 --- a/worker_threads/port_postmessage_value_transferlist.md +++ b/worker_threads/port_postmessage_value_transferlist.md @@ -1,5 +1,12 @@ * `value` {any} @@ -17,7 +24,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, + [`FileHandle`][]s, and [`KeyObject`][]s. ```js const { MessageChannel } = require('worker_threads'); @@ -31,7 +39,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 diff --git a/worker_threads/worker_markasuntransferable_object.md b/worker_threads/worker_markasuntransferable_object.md new file mode 100644 index 00000000..10e29ba0 --- /dev/null +++ b/worker_threads/worker_markasuntransferable_object.md @@ -0,0 +1,35 @@ + + +Mark an object as not transferable. If `object` occurs in the transfer list of +a [`port.postMessage()`][] call, it will be ignored. + +In particular, this makes sense for objects that can be cloned, rather than +transferred, and which are used by other objects on the sending side. +For example, Node.js marks the `ArrayBuffer`s it uses for its +[`Buffer` pool][`Buffer.allocUnsafe()`] with this. + +This operation cannot be undone. + +```js +const { MessageChannel, markAsUntransferable } = require('worker_threads'); + +const pooledBuffer = new ArrayBuffer(8); +const typedArray1 = new Uint8Array(pooledBuffer); +const typedArray2 = new Float64Array(pooledBuffer); + +markAsUntransferable(pooledBuffer); + +const { port1 } = new MessageChannel(); +port1.postMessage(typedArray1, [ typedArray1.buffer ]); + +// The following line prints the contents of typedArray1 -- it still owns its +// memory and has been cloned, not transfered. Without `markAsUntransferable()`, +// this would print an empty Uint8Array. typedArray2 is intact as well. +console.log(typedArray1); +console.log(typedArray2); +``` + +There is no equivalent to this API in browsers. + diff --git a/worker_threads/worker_unref.md b/worker_threads/worker_unref.md index 316e06d0..d5ef39c1 100644 --- a/worker_threads/worker_unref.md +++ b/worker_threads/worker_unref.md @@ -52,6 +52,10 @@ active handle in the event system. If the worker is already `unref()`ed calling + + + + diff --git a/zlib/class_brotlioptions.md b/zlib/class_brotlioptions.md index 433413a3..b4c07069 100644 --- a/zlib/class_brotlioptions.md +++ b/zlib/class_brotlioptions.md @@ -1,5 +1,9 @@ @@ -10,6 +14,8 @@ Each Brotli-based class takes an `options` object. All options are optional. * `finishFlush` {integer} **Default:** `zlib.constants.BROTLI_OPERATION_FINISH` * `chunkSize` {integer} **Default:** `16 * 1024` * `params` {Object} Key-value object containing indexed [Brotli parameters][]. +* `maxOutputLength` {integer} Limits output size when using + [convenience methods][]. **Default:** [`buffer.kMaxLength`][] For example: diff --git a/zlib/class_options.md b/zlib/class_options.md index c5e2b070..a36fa965 100644 --- a/zlib/class_options.md +++ b/zlib/class_options.md @@ -1,6 +1,9 @@