Memory Diagnotics feature: track the allocation of XmlDisposable (#16)

Author: jameslan

package.json

@@ -13,7 +13,7 @@
         "link": "npm run bind && npm run dist",
         "wasm": "npm run clean && npm run libxml && npm run link",
         "unit": "mocha --v8-expose-gc",
-        "integ": "TS_NODE_PROJECT=tsconfig.integ.json mocha test/crossplatform",
+        "integ": "TS_NODE_PROJECT=tsconfig.integ.json mocha --v8-expose-gc test/crossplatform",
         "test": "npm run cov && npm run lint",
         "cov": "c8 npm run unit",
         "build": "npm run wasm && tsc -p tsconfig.prod.json --declaration",

src/disposable.mts

@@ -2,12 +2,136 @@ import type { Pointer } from './libxml2raw';
 import './disposeShim.mjs';
 import './metadataShim.mjs';
 
+interface MemTracker {
+    trackAllocate(obj: XmlDisposable): void;
+    trackDeallocate(obj: XmlDisposable): void;
+    report(): any;
+}
+
+const noopTracker: MemTracker = {
+    trackAllocate(): void {
+    },
+
+    trackDeallocate(): void {
+    },
+
+    report(): any {
+    },
+};
+
+interface MemTrackingInfo {
+    object: WeakRef<XmlDisposable>;
+    classname: string;
+}
+
+class MemTrackerImpl implements MemTracker {
+    // js/ts doesn't have a builtin universal id for objects as in python,
+    // we build a similar thing
+    idCounter: number;
+
+    // from object to id
+    disposableId: WeakMap<XmlDisposable, number>;
+
+    // from id to tracking info
+    disposableInfo: Map<number, MemTrackingInfo>;
+
+    constructor() {
+        this.idCounter = 0;
+        this.disposableId = new WeakMap<XmlDisposable, number>();
+        this.disposableInfo = new Map<number, MemTrackingInfo>();
+    }
+
+    trackAllocate(obj: XmlDisposable): void {
+        this.idCounter += 1;
+        this.disposableId.set(obj, this.idCounter);
+        this.disposableInfo.set(this.idCounter, {
+            object: new WeakRef(obj),
+            classname: obj.constructor.name,
+        });
+    }
+
+    trackDeallocate(obj: XmlDisposable): void {
+        const id = this.disposableId.get(obj);
+        if (id) { // the object may be created before the diagnosis enabled
+            this.disposableInfo.delete(id);
+            this.disposableId.delete(obj);
+        }
+    }
+
+    report(): any {
+        const report: any = {};
+        this.disposableInfo.forEach((info) => {
+            const classReport = report[info.classname] ||= { // eslint-disable-line no-multi-assign
+                garbageCollected: 0,
+                totalInstances: 0,
+                instances: [],
+            };
+            classReport.totalInstances += 1;
+            const obj = info.object.deref();
+            if (obj != null) {
+                classReport.instances.push({ instance: obj });
+            } else {
+                classReport.garbageCollected += 1;
+            }
+        });
+        return report;
+    }
+}
+
+/**
+ * Memory Diagnostic options.
+ */
+export interface MemDiagOptions {
+    /**
+     * Enabling the memory diagnostics.
+     * Note the tracking information will be lost when it is disabled.
+     */
+    enabled: boolean;
+}
+
+/**
+ * Set up memory diagnostic helpers.
+ *
+ * When enabled, it will record allocated {@link XmlDisposable} objects
+ * (and its subclass objects) and track if
+ * {@link XmlDisposable#dispose} is called.
+ *
+ * Note that the allocation will not be monitored before memory diagnostics is enabled.
+ *
+ * @param options
+ * @see {@link memReport}
+ */
+export function memDiag(options: MemDiagOptions) {
+    if (options.enabled) {
+        tracker = new MemTrackerImpl();
+    } else {
+        tracker = noopTracker;
+    }
+}
+
+/**
+ * Get the report of un-disposed objects.
+ * @returns The report (JSON) object, whose format may vary according to the settings,
+ * and is subject to change.
+ * Returns undefined if memory diagnostic is not enabled.
+ * @see {@link memDiag}
+ */
+export function memReport(): any {
+    return tracker.report();
+}
+
+let tracker: MemTracker = noopTracker;
+
 /**
  * Base implementation of interface Disposable to handle wasm memory.
  *
  * Remember to call `dispose()` for any subclass object.
  */
 export abstract class XmlDisposable implements Disposable {
+    protected constructor() {
+        tracker.trackAllocate(this);
+    }
+
     /**
      * Alias of {@link "[dispose]"}.
      *
@@ -18,6 +142,7 @@ export abstract class XmlDisposable implements Disposable {
         const metadata = (this.constructor as any)[Symbol.metadata];
         const propsToRelease = metadata[Symbol.dispose] as Array<string | symbol>;
         propsToRelease.forEach((prop) => { (this as any)[prop] = 0; });
+        tracker.trackDeallocate(this);
     }
 
     /**
@@ -44,7 +169,7 @@ export abstract class XmlDisposable implements Disposable {
  * @param free function to release the managed wasm resource
  * @returns the decorator
  */
-export function disposeBy<This extends object>(free: (value: Pointer) => void) {
+export function disposeBy<This extends XmlDisposable>(free: (value: Pointer) => void) {
     return function decorator(
         target: ClassAccessorDecoratorTarget<This, Pointer>,
         ctx: ClassAccessorDecoratorContext<This, Pointer>,

test/crossplatform/diag.spec.mts

@@ -0,0 +1,54 @@
+import { expect } from 'chai';
+import { disposable, XmlDocument } from '@libxml2-wasm/lib/index.mjs';
+
+describe('memDiag', () => {
+    it('should report remaining objects', () => {
+        disposable.memDiag({ enabled: true });
+        const xml1 = XmlDocument.fromString('<doc/>');
+        const xml2 = XmlDocument.fromString('<doc/>');
+
+        xml1.dispose();
+        const report = disposable.memReport();
+
+        expect(report.XmlDocument).is.not.null;
+        expect(report.XmlDocument.totalInstances).to.equal(1);
+        expect(report.XmlDocument.garbageCollected).to.equal(0);
+        expect(report.XmlDocument.instances[0].instance).to.equal(xml2);
+        xml2.dispose();
+        disposable.memDiag({ enabled: false });
+    });
+
+    it('should report GC\'ed objects', async () => {
+        disposable.memDiag({ enabled: true });
+        const xml1 = XmlDocument.fromString('<doc/>');
+        XmlDocument.fromString('<doc/>'); // to be GC'ed
+
+        // allow finalizer to run
+        await new Promise((resolve) => { setTimeout(resolve, 0); });
+        (global as any).gc();
+        const report = disposable.memReport();
+
+        expect(report.XmlDocument).is.not.null;
+        expect(report.XmlDocument.totalInstances).to.equal(2);
+        expect(report.XmlDocument.garbageCollected).to.equal(1);
+        expect(report.XmlDocument.instances[0].instance).to.equal(xml1);
+        xml1.dispose();
+        disposable.memDiag({ enabled: false });
+    });
+
+    it('will not track allocation before enabled', () => {
+        const xml1 = XmlDocument.fromString('<doc/>');
+        disposable.memDiag({ enabled: true });
+        const xml2 = XmlDocument.fromString('<doc/>');
+
+        const report = disposable.memReport();
+
+        expect(report.XmlDocument).is.not.null;
+        expect(report.XmlDocument.totalInstances).to.equal(1);
+        expect(report.XmlDocument.garbageCollected).to.equal(0);
+        expect(report.XmlDocument.instances[0].instance).to.equal(xml2);
+        xml2.dispose();
+        xml1.dispose();
+        disposable.memDiag({ enabled: false });
+    });
+});