From d30cccdf8cfadc5910cddcc172291542a07125c0 Mon Sep 17 00:00:00 2001 From: Joyee Cheung Date: Sat, 2 Mar 2024 23:11:30 +0100 Subject: [PATCH] v8: implement v8.queryObjects() for memory leak regression testing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This is similar to the `queryObjects()` console API provided by the Chromium DevTools console. It can be used to search for objects that have the matching constructor on its prototype chain in the entire heap, which can be useful for memory leak regression tests. To avoid surprising results, users should avoid using this API on constructors whose implementation they don't control, or on constructors that can be invoked by other parties in the application. To avoid accidental leaks, this API does not return raw references to the objects found. By default, it returns the count of the objects found. If `options.format` is `'summary'`, it returns an array containing brief string representations for each object. The visibility provided in this API is similar to what the heap snapshot provides, while users can save the cost of serialization and parsing and directly filer the target objects during the search. We have been using this API internally for the test suite, which has been more stable than any other leak regression testing strategies in the CI. With a public implementation we can now use the public API instead. PR-URL: https://github.com/nodejs/node/pull/51927 Reviewed-By: Anna Henningsen Reviewed-By: Stephen Belanger Reviewed-By: Vinícius Lourenço Claro Cardoso Reviewed-By: Gerhard Stöbich Reviewed-By: Rafael Gonzaga --- doc/api/v8.md | 84 ++++++++++++++ lib/internal/heap_utils.js | 45 +++++++- lib/internal/test/binding.js | 21 +++- lib/v8.js | 2 + node.gyp | 1 + src/heap_utils.cc | 36 ------ src/internal_only_v8.cc | 85 ++++++++++++++ src/node_binding.cc | 3 + src/node_external_reference.h | 1 + test/common/gc.js | 15 ++- .../test-vm-source-text-module-leak.js | 2 +- .../test-diagnostics-channel-memory-leak.js | 2 +- test/parallel/test-internal-only-binding.js | 9 ++ test/parallel/test-v8-query-objects.js | 104 ++++++++++++++++++ 14 files changed, 359 insertions(+), 51 deletions(-) create mode 100644 src/internal_only_v8.cc create mode 100644 test/parallel/test-internal-only-binding.js create mode 100644 test/parallel/test-v8-query-objects.js diff --git a/doc/api/v8.md b/doc/api/v8.md index 61ccbd8b9aa0f1..a3ab7f04d64366 100644 --- a/doc/api/v8.md +++ b/doc/api/v8.md @@ -242,6 +242,89 @@ buffers and external strings. } ``` +## `v8.queryObjects(ctor[, options])` + + + +> 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} + * `format` {string} If it's `'count'`, the count of matched objects + is returned. If it's `'summary'`, an array with summary strings + of the matched objects is returned. +* Returns: {number|Array} + +This is similar to the [`queryObjects()` console API][] provided by the +Chromium DevTools console. It can be used to search for objects that +have the matching constructor on its prototype chain in the heap after +a full garbage collection, which can be useful for memory leak +regression tests. To avoid surprising results, users should avoid using +this API on constructors whose implementation they don't control, or on +constructors that can be invoked by other parties in the application. + +To avoid accidental leaks, this API does not return raw references to +the objects found. By default, it returns the count of the objects +found. If `options.format` is `'summary'`, it returns an array +containing brief string representations for each object. The visibility +provided in this API is similar to what the heap snapshot provides, +while users can save the cost of serialization and parsing and directly +filter the target objects during the search. + +Only objects created in the current execution context are included in the +results. + +```cjs +const { queryObjects } = require('node:v8'); +class A { foo = 'bar'; } +console.log(queryObjects(A)); // 0 +const a = new A(); +console.log(queryObjects(A)); // 1 +// [ "A { foo: 'bar' }" ] +console.log(queryObjects(A, { format: 'summary' })); + +class B extends A { bar = 'qux'; } +const b = new B(); +console.log(queryObjects(B)); // 1 +// [ "B { foo: 'bar', bar: 'qux' }" ] +console.log(queryObjects(B, { format: 'summary' })); + +// Note that, when there are child classes inheriting from a constructor, +// the constructor also shows up in the prototype chain of the child +// classes's prototoype, so the child classes's prototoype would also be +// included in the result. +console.log(queryObjects(A)); // 3 +// [ "B { foo: 'bar', bar: 'qux' }", 'A {}', "A { foo: 'bar' }" ] +console.log(queryObjects(A, { format: 'summary' })); +``` + +```mjs +import { queryObjects } from 'node:v8'; +class A { foo = 'bar'; } +console.log(queryObjects(A)); // 0 +const a = new A(); +console.log(queryObjects(A)); // 1 +// [ "A { foo: 'bar' }" ] +console.log(queryObjects(A, { format: 'summary' })); + +class B extends A { bar = 'qux'; } +const b = new B(); +console.log(queryObjects(B)); // 1 +// [ "B { foo: 'bar', bar: 'qux' }" ] +console.log(queryObjects(B, { format: 'summary' })); + +// Note that, when there are child classes inheriting from a constructor, +// the constructor also shows up in the prototype chain of the child +// classes's prototoype, so the child classes's prototoype would also be +// included in the result. +console.log(queryObjects(A)); // 3 +// [ "B { foo: 'bar', bar: 'qux' }", 'A {}', "A { foo: 'bar' }" ] +console.log(queryObjects(A, { format: 'summary' })); +``` + ## `v8.setFlagsFromString(flags)`