From ac3a32497102f88132e7a00f43d10e835228daab Mon Sep 17 00:00:00 2001 From: Joyee Cheung Date: Thu, 29 Feb 2024 16:50:20 +0100 Subject: [PATCH 1/2] v8: implement v8.queryObjects() for memory leak regression testing 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. --- 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 399cb1e82adf12..a7120cb5148747 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 +filer 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)`