diff --git a/doc/api/cli.md b/doc/api/cli.md index aeb901973c2af6..4e2a44e868f741 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -403,10 +403,13 @@ Error: Access to this API has been restricted -> Stability: 1 - Experimental - Generates a snapshot blob when the process exits and writes it to disk, which can be loaded later with `--snapshot-blob`. @@ -442,18 +445,25 @@ I am from the snapshot For more information, check out the [`v8.startupSnapshot` API][] documentation. -Currently the support for run-time snapshot is experimental in that: - -1. User-land modules are not yet supported in the snapshot, so only - one single file can be snapshotted. Users can bundle their applications - into a single script with their bundler of choice before building - a snapshot, however. -2. Only a subset of the built-in modules work in the snapshot, though the - Node.js core test suite checks that a few fairly complex applications - can be snapshotted. Support for more modules are being added. If any - crashes or buggy behaviors occur when building a snapshot, please file - a report in the [Node.js issue tracker][] and link to it in the - [tracking issue for user-land snapshots][]. +The snapshot currently only supports loding a single entrypoint during the +snapshot building process, which can load built-in modules, but not additional user-land modules. +Users can bundle their applications into a single script with their bundler +of choice before building a snapshot. + +As it's complicated to ensure the serializablility of all built-in modules, +which are also growing over time, only a subset of the built-in modules are +well tested to be serializable during the snapshot building process. +The Node.js core test suite checks that a few fairly complex applications +can be snapshotted. The list of built-in modules being +[captured by the built-in snapshot of Node.js][] is considered supported. +When the snapshot builder encounters a built-in module that cannot be +serialized, it may crash the snapshot building process. In that case a typical +workaround would be to delay loading that module until +runtime, using either [`v8.startupSnapshot.setDeserializeMainFunction()`][] or +[`v8.startupSnapshot.addDeserializeCallback()`][]. If serialization for +an additional module during the snapshot building process is needed, +please file a request in the [Node.js issue tracker][] and link to it in the +[tracking issue for user-land snapshots][]. ### `--build-snapshot-config` @@ -461,10 +471,13 @@ Currently the support for run-time snapshot is experimental in that: added: - v21.6.0 - v20.12.0 +changes: + - version: + - REPLACEME + pr-url: https://github.com/nodejs/node/pull/60954 + description: The snapshot building process is no longer experimental. --> -> Stability: 1 - Experimental - Specifies the path to a JSON configuration file which configures snapshot creation behavior. @@ -1499,10 +1512,13 @@ Specify the file name of the heap profile generated by `--heap-prof`. added: - v15.1.0 - v14.18.0 +changes: + - version: + - REPLACEME + pr-url: https://github.com/nodejs/node/pull/60956 + description: The flag is no longer experimental. --> -> Stability: 1 - Experimental - Writes a V8 heap snapshot to disk when the V8 heap usage is approaching the heap limit. `count` should be a non-negative integer (in which case Node.js will write no more than `max_count` snapshots to disk). @@ -3387,10 +3403,12 @@ Any other value will result in colorized output being disabled. -> Stability: 1.1 - Active Development - Enable the [module compile cache][] for the Node.js instance. See the documentation of [module compile cache][] for details. @@ -4183,7 +4201,10 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12 [`tls.DEFAULT_MAX_VERSION`]: tls.md#tlsdefault_max_version [`tls.DEFAULT_MIN_VERSION`]: tls.md#tlsdefault_min_version [`unhandledRejection`]: process.md#event-unhandledrejection +[`v8.startupSnapshot.addDeserializeCallback()`]: v8.md#v8startupsnapshotadddeserializecallbackcallback-data +[`v8.startupSnapshot.setDeserializeMainFunction()`]: v8.md#v8startupsnapshotsetdeserializemainfunctioncallback-data [`v8.startupSnapshot` API]: v8.md#startup-snapshot-api +[captured by the built-in snapshot of Node.js]: https://github.com/nodejs/node/blob/b19525a33cc84033af4addd0f80acd4dc33ce0cf/test/parallel/test-bootstrap-modules.js#L24 [collecting code coverage from tests]: test.md#collecting-code-coverage [conditional exports]: packages.md#conditional-exports [context-aware]: addons.md#context-aware-addons diff --git a/doc/api/module.md b/doc/api/module.md index d9a12895244c8a..efb85efc4c93ca 100644 --- a/doc/api/module.md +++ b/doc/api/module.md @@ -410,6 +410,11 @@ to disk when the Node.js instance is about to exit. This is subject to change. T is flushed to disk in case the application wants to spawn other Node.js instances and let them share the cache long before the parent exits. +The compile cache layout on disk is an implementation detail and should not be +relied upon. The compile cache generated is typically only reusable in the same +version of Node.js, and should be not assumed to be compatible across different +versions of Node.js. + ### Portability of the compile cache By default, caches are invalidated when the absolute paths of the modules being @@ -449,10 +454,12 @@ separately if the same base directory is used to persist the cache, so they can -> Stability: 1.1 - Active Development - The following constants are returned as the `status` field in the object returned by [`module.enableCompileCache()`][] to indicate the result of the attempt to enable the [module compile cache][]. @@ -503,6 +510,9 @@ The following constants are returned as the `status` field in the object returne -> Stability: 1.1 - Active Development - * `options` {string|Object} Optional. If a string is passed, it is considered to be `options.directory`. * `directory` {string} Optional. Directory to store the compile cache. If not specified, the directory specified by the [`NODE_COMPILE_CACHE=dir`][] environment variable @@ -557,10 +565,12 @@ be inherited into the child workers. The directory can be obtained either from t added: - v23.0.0 - v22.10.0 +changes: + - version: REPLACEME + pr-url: https://github.com/nodejs/node/pull/60971 + description: This feature is no longer experimental. --> -> Stability: 1.1 - Active Development - Flush the [module compile cache][] accumulated from modules already loaded in the current Node.js instance to disk. This returns after all the flushing file system operations come to an end, no matter they succeed or not. If there @@ -571,10 +581,12 @@ interfere with the actual operation of the application. -> Stability: 1.1 - Active Development - * Returns: {string|undefined} Path to the [module compile cache][] directory if it is enabled, or `undefined` otherwise. diff --git a/doc/api/v8.md b/doc/api/v8.md index ace8ea2d261d25..7d7f7c56791058 100644 --- a/doc/api/v8.md +++ b/doc/api/v8.md @@ -367,10 +367,13 @@ for more information about the properties of the object. added: - v22.0.0 - v20.13.0 +changes: + - version: + - REPLACEME + pr-url: https://github.com/nodejs/node/pull/60957 + description: This API is no longer experimental. --> -> Stability: 1.1 - Active development - * `ctor` {Function} The constructor that can be used to search on the prototype chain in order to filter target objects in the heap. * `options` {undefined|Object} diff --git a/test/parallel/test-repl-paste-big-data.js b/test/pummel/test-repl-paste-big-data.js similarity index 88% rename from test/parallel/test-repl-paste-big-data.js rename to test/pummel/test-repl-paste-big-data.js index 78cdd93c5ba35c..2265a1af8e393c 100644 --- a/test/parallel/test-repl-paste-big-data.js +++ b/test/pummel/test-repl-paste-big-data.js @@ -14,10 +14,10 @@ replServer.input.emit('keypress', '', { name: 'left' }); replServer.input.emit('data', 'node'); assert.strictEqual(replServer.line, '{node}'); -replServer.input.emit('data', 'a'.repeat(2e4) + '\n'); +replServer.input.emit('data', 'a'.repeat(4e4) + '\n'); replServer.input.emit('data', '.exit\n'); replServer.once('exit', common.mustCall(() => { const diff = process.cpuUsage(cpuUsage); - assert.ok(diff.user < 1e6); + assert.ok(diff.user < 4e6); }));