diff --git a/doc/api/v8.md b/doc/api/v8.md index 7ee7a748674cae..a3fa7889dc8291 100644 --- a/doc/api/v8.md +++ b/doc/api/v8.md @@ -1617,6 +1617,30 @@ added: Stopping collecting the profile and the profile will be discarded. +## Class: `SyncHeapProfileHandle` + + + +### `syncHeapProfileHandle.stop()` + + + +* Returns: {string} + +Stopping collecting the profile and return the profile data. + +### `syncHeapProfileHandle[Symbol.dispose]()` + + + +Stopping collecting the profile and the profile will be discarded. + ## Class: `CPUProfileHandle` + +* `options` {Object} + * `sampleInterval` {number} The average sampling interval in bytes. + **Default:** `524288` (512 KiB). + * `stackDepth` {integer} The maximum stack depth for samples. + **Default:** `16`. + * `forceGC` {boolean} Force garbage collection before taking the profile. + **Default:** `false`. + * `includeObjectsCollectedByMajorGC` {boolean} Include objects collected + by major GC. **Default:** `false`. + * `includeObjectsCollectedByMinorGC` {boolean} Include objects collected + by minor GC. **Default:** `false`. +* Returns: {SyncHeapProfileHandle} + +Starting a heap profile then return a `SyncHeapProfileHandle` object. +This API supports `using` syntax. + +```cjs +const v8 = require('node:v8'); + +const handle = v8.startHeapProfile(); +const profile = handle.stop(); +console.log(profile); +``` + +```mjs +import v8 from 'node:v8'; + +const handle = v8.startHeapProfile(); +const profile = handle.stop(); +console.log(profile); +``` + +With custom parameters: + +```cjs +const v8 = require('node:v8'); + +const handle = v8.startHeapProfile({ + sampleInterval: 1024, + stackDepth: 8, + forceGC: true, + includeObjectsCollectedByMajorGC: true, +}); +const profile = handle.stop(); +console.log(profile); +``` + +```mjs +import v8 from 'node:v8'; + +const handle = v8.startHeapProfile({ + sampleInterval: 1024, + stackDepth: 8, + forceGC: true, + includeObjectsCollectedByMajorGC: true, +}); +const profile = handle.stop(); +console.log(profile); +``` + [CppHeap]: https://v8docs.nodesource.com/node-22.4/d9/dc4/classv8_1_1_cpp_heap.html [HTML structured clone algorithm]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm [Hook Callbacks]: #hook-callbacks diff --git a/doc/api/worker_threads.md b/doc/api/worker_threads.md index 32024e972932cd..6fee0d8368a914 100644 --- a/doc/api/worker_threads.md +++ b/doc/api/worker_threads.md @@ -2005,7 +2005,7 @@ w.on('online', async () => { }); ``` -### `worker.startHeapProfile()` +### `worker.startHeapProfile([options])` +* `options` {Object} + * `sampleInterval` {number} The average sampling interval in bytes. + **Default:** `524288` (512 KiB). + * `stackDepth` {integer} The maximum stack depth for samples. + **Default:** `16`. + * `forceGC` {boolean} Force garbage collection before taking the profile. + **Default:** `false`. + * `includeObjectsCollectedByMajorGC` {boolean} Include objects collected + by major GC. **Default:** `false`. + * `includeObjectsCollectedByMinorGC` {boolean} Include objects collected + by minor GC. **Default:** `false`. * Returns: {Promise} Starting a Heap profile then return a Promise that fulfills with an error @@ -2034,6 +2045,22 @@ worker.on('online', async () => { }); ``` +```mjs +import { Worker } from 'node:worker_threads'; + +const worker = new Worker(` + const { parentPort } = require('node:worker_threads'); + parentPort.on('message', () => {}); + `, { eval: true }); + +worker.on('online', async () => { + const handle = await worker.startHeapProfile(); + const profile = await handle.stop(); + console.log(profile); + worker.terminate(); +}); +``` + `await using` example. ```cjs @@ -2050,6 +2077,20 @@ w.on('online', async () => { }); ``` +```mjs +import { Worker } from 'node:worker_threads'; + +const w = new Worker(` + const { parentPort } = require('node:worker_threads'); + parentPort.on('message', () => {}); + `, { eval: true }); + +w.on('online', async () => { + // Stop profile automatically when return and profile will be discarded + await using handle = await w.startHeapProfile(); +}); +``` + ### `worker.stderr`