Replace manual memory management with FinalizationRegistry (#1908)

Summary:
Pull Request resolved: #1908

Fixes #1818
Fixes #1572

Yoga's JavaScript API currently requires users to manually call
`node.free()`, `node.freeRecursive()`, or `config.free()` to release
WASM memory. This is error-prone and unusual for a JavaScript library.

This diff uses `FinalizationRegistry` (available in all modern JS
engines) to automatically free WASM memory when JS objects are garbage
collected, removing this footgun entirely.

Changes:
- Added `FinalizationRegistry` instances for `Node` and `Config` in
  `wrapAssembly.ts`. When a `NodeImpl`/`ConfigImpl` is constructed, it
  is registered with the appropriate registry. The weak reference
  callback receives the WASM pointer and calls the appropriate C free
  function.
- The Node finalizer calls `YGNodeFinalize` (not `YGNodeFree`) to
  safely deallocate without disconnecting nodes from their
  owner/children, since an entire tree may be garbage collected
  together.
- Removed `free()` and `freeRecursive()` from the public `Node` type
  and `free()` from the public `Config` type.
- Removed `Yoga.Node.destroy()` and `Yoga.Config.destroy()` factory
  methods.
- Fixed `setDirtiedFunc` to use `WeakRef(this)` instead of capturing
  `this` directly in the closure stored in the dirtied func Map. The
  previous `() => dirtiedFunc(this)` pattern created a strong reference
  from the Map to the Node, preventing GC of detached nodes with a
  dirtied func set.
- Updated `gentest-javascript.js` to stop generating `try`/`finally`
  cleanup blocks and `let root` declarations in test prologues/epilogues.
- Removed all `free()`/`freeRecursive()`/`config.free()` calls from 25
  generated test files and 9 hand-written test files.
- Re-signed all generated test files with signedsource.
- Updated `README.md` to remove manual memory management documentation.

Reviewed By: cipolleschi

Differential Revision: D95014519

Author: NickGerleman

gentest/gentest-javascript.js

@@ -59,7 +59,6 @@ JavascriptEmitter.prototype = Object.create(Emitter.prototype, {
       this.push(`${testFn}('${name}', () => {`);
       this.pushIndent();
       this.push('const config = Yoga.Config.create();');
-      this.push('let root;');
       this.push('');
 
       if (experiments.length > 0) {
@@ -70,39 +69,17 @@ JavascriptEmitter.prototype = Object.create(Emitter.prototype, {
         }
         this.push('');
       }
-
-      this.push('try {');
-      this.pushIndent();
     },
   },
 
   emitTestTreePrologue: {
     value: function (nodeName) {
-      if (nodeName === 'root') {
-        this.push(`root = Yoga.Node.create(config);`);
-      } else {
-        this.push(`const ${nodeName} = Yoga.Node.create(config);`);
-      }
+      this.push(`const ${nodeName} = Yoga.Node.create(config);`);
     },
   },
 
   emitTestEpilogue: {
     value: function (_experiments) {
-      this.popIndent();
-      this.push('} finally {');
-      this.pushIndent();
-
-      this.push("if (typeof root !== 'undefined') {");
-      this.pushIndent();
-      this.push('root.freeRecursive();');
-      this.popIndent();
-      this.push('}');
-      this.push('');
-      this.push('config.free();');
-
-      this.popIndent();
-      this.push('}');
-
       this.popIndent();
       this.push('});');
     },

javascript/README.md

@@ -13,19 +13,6 @@ const node = Yoga.Node.create();
 node.setAlignContent(Align.Center);
 ```
 
-Objects created by `Yoga.<>.create()` are not automatically garbage collected and should be freed once they are no longer in use.
-
-```ts
-// Free a config
-config.free();
-
-// Free a tree of Nodes
-node.freeRecursive();
-
-// Free a single Node
-node.free();
-```
-
 ## Requirements
 
 `yoga-layout` requires a toolchain that supports ES Modules and top-level await.

javascript/src/wrapAssembly.ts

@@ -48,7 +48,6 @@ type Value = {
 };
 
 export type Config = {
-  free(): void;
   isExperimentalFeatureEnabled(feature: ExperimentalFeature): boolean;
   setExperimentalFeatureEnabled(
     feature: ExperimentalFeature,
@@ -77,8 +76,6 @@ export type Node = {
     direction?: Direction,
   ): void;
   copyStyle(node: Node): void;
-  free(): void;
-  freeRecursive(): void;
   getAlignContent(): Align;
   getAlignItems(): Align;
   getAlignSelf(): Align;
@@ -263,13 +260,11 @@ export type Node = {
 export type Yoga = {
   Config: {
     create(): Config;
-    destroy(config: Config): void;
   };
   Node: {
     create(config?: Config): Node;
     createDefault(): Node;
     createWithConfig(config: Config): Node;
-    destroy(node: Node): void;
   };
 } & typeof YGEnums;
 
@@ -365,16 +360,24 @@ export default function wrapAssembly(lib: any): Yoga {
     }
   }
 
+  // --- FinalizationRegistry for automatic cleanup ---
+  const configRegistry = new FinalizationRegistry((ptr: number) => {
+    lib._YGConfigFree(ptr);
+  });
+
+  const nodeRegistry = new FinalizationRegistry((ptr: number) => {
+    lib._yogaMeasureFuncs.delete(ptr);
+    lib._yogaDirtiedFuncs.delete(ptr);
+    lib._YGNodeFinalize(ptr);
+  });
+
   // --- Config class ---
   class ConfigImpl {
     _ptr: number;
 
     constructor(ptr: number) {
       this._ptr = ptr;
-    }
-
-    free(): void {
-      lib._YGConfigFree(this._ptr);
+      configRegistry.register(this, ptr, this);
     }
 
     setExperimentalFeatureEnabled(
@@ -423,6 +426,7 @@ export default function wrapAssembly(lib: any): Yoga {
       this._ptr = ptr;
       this._children = [];
       this._parent = null;
+      nodeRegistry.register(this, ptr, this);
     }
 
     // --- Tree hierarchy ---
@@ -454,31 +458,6 @@ export default function wrapAssembly(lib: any): Yoga {
     }
 
     // --- Lifecycle ---
-    free(): void {
-      lib._yogaMeasureFuncs.delete(this._ptr);
-      lib._yogaDirtiedFuncs.delete(this._ptr);
-
-      // Clear JS tree references
-      if (this._parent) {
-        const idx = this._parent._children.indexOf(this);
-        if (idx !== -1) {
-          this._parent._children.splice(idx, 1);
-        }
-        this._parent = null;
-      }
-      this._children = [];
-
-      lib._YGNodeFree(this._ptr);
-    }
-
-    freeRecursive(): void {
-      // Walk children in JS, calling freeRecursive on each
-      while (this._children.length > 0) {
-        this._children[0].freeRecursive();
-      }
-      this.free();
-    }
-
     reset(): void {
       lib._yogaMeasureFuncs.delete(this._ptr);
       lib._yogaDirtiedFuncs.delete(this._ptr);
@@ -920,7 +899,11 @@ export default function wrapAssembly(lib: any): Yoga {
 
     setDirtiedFunc(dirtiedFunc: DirtiedFunction | null): void {
       if (dirtiedFunc) {
-        lib._yogaDirtiedFuncs.set(this._ptr, () => dirtiedFunc(this));
+        const nodeWeakRef = new WeakRef(this);
+        lib._yogaDirtiedFuncs.set(this._ptr, () => {
+          const node = nodeWeakRef.deref();
+          if (node) dirtiedFunc(node);
+        });
         lib._jswrap_YGNodeSetDirtiedFunc(this._ptr);
       } else {
         this.unsetDirtiedFunc();
@@ -1011,9 +994,6 @@ export default function wrapAssembly(lib: any): Yoga {
       create(): Config {
         return new ConfigImpl(lib._YGConfigNew());
       },
-      destroy(config: Config): void {
-        (config as ConfigImpl).free();
-      },
     },
     Node: {
       create(config?: Config): Node {
@@ -1032,9 +1012,6 @@ export default function wrapAssembly(lib: any): Yoga {
           lib._YGNodeNewWithConfig((config as ConfigImpl)._ptr),
         );
       },
-      destroy(node: Node): void {
-        (node as NodeImpl).free();
-      },
     },
     ...YGEnums,
   };

javascript/tests/Benchmarks/YGBenchmark.test.ts

@@ -27,7 +27,6 @@ YGBENCHMARK('Stack with flex', () => {
   }
 
   root.calculateLayout(undefined, undefined, Yoga.DIRECTION_LTR);
-  root.freeRecursive();
 });
 
 YGBENCHMARK('Align stretch in undefined axis', () => {
@@ -43,7 +42,6 @@ YGBENCHMARK('Align stretch in undefined axis', () => {
   }
 
   root.calculateLayout(undefined, undefined, Yoga.DIRECTION_LTR);
-  root.freeRecursive();
 });
 
 YGBENCHMARK('Nested flex', () => {
@@ -67,7 +65,6 @@ YGBENCHMARK('Nested flex', () => {
   }
 
   root.calculateLayout(undefined, undefined, Yoga.DIRECTION_LTR);
-  root.freeRecursive();
 });
 
 YGBENCHMARK('Huge nested layout', () => {
@@ -110,5 +107,4 @@ YGBENCHMARK('Huge nested layout', () => {
   }
 
   root.calculateLayout(undefined, undefined, Yoga.DIRECTION_LTR);
-  root.freeRecursive();
 });