Embind: add explicit resource management support (#23818)

Adds experimental support for the [explicit resource management
proposal](https://github.com/tc39/proposal-explicit-resource-management)
to Embind classes. It's currently only natively supported in latest
Chrome (unflagged) and Node.js (flagged), but users can already enjoy it
via TypeScript and Babel transpilation.

It's designed specifically for RAII objects that need to be freed when
they go out of scope, which is a perfect fit for Embind (much better
than FinalizationRegistry that we used as a loose fallback for forgotten
deletes so far).

Before:

```js
var foo = new Module.MyClass();
foo.doSomething();
// somewhere later:
foo.delete();
```

With this support:

```js
using foo = new Module.MyClass();
foo.doSomething();
```

Author: RReverser

site/source/docs/porting/connecting_cpp_and_javascript/embind.rst

@@ -243,11 +243,27 @@ a C++ object is no longer needed and can be deleted:
 Automatic memory management
 ---------------------------
 
-JavaScript only gained support for `finalizers`_ in ECMAScript 2021, or ECMA-262
-Edition 12. The new API is called `FinalizationRegistry`_ and it still does not
-offer any guarantees that the provided finalization callback will be called.
-Embind uses this for cleanup if available, but only for smart pointers,
-and only as a last resort.
+Embind integrates with the `Explicit Resource Management`_ proposal.
+
+It allows to automatically delete short-lived C++ objects at the end of the
+scope when they're declared with a `using` keyword:
+
+.. code:: javascript
+
+    using x = new Module.MyClass;
+    x.method();
+
+At the moment of writing, this proposal is natively supported in
+Chromium-based browsers as well as Babel and TypeScript via transpilation.
+
+Embind also supports `finalizers`_, which were added in ECMAScript 2021 under a
+`FinalizationRegistry`_ API. Unlike the `using` keyword, finalizers are not
+guaranteed to be called, and even if they are, there are no guarantees about
+their timing or order of execution, which makes them unsuitable for general
+RAII-style resource management.
+
+Embind uses it for cleanup if available, but only for smart pointers, and only
+as a last resort.
 
 .. warning:: It is strongly recommended that JavaScript code explicitly deletes
     any C++ object handles it has received.
@@ -1245,3 +1261,4 @@ real-world applications has proved to be more than acceptable.
 .. _Making sine, square, sawtooth and triangle waves: http://stuartmemo.com/making-sine-square-sawtooth-and-triangle-waves/
 .. _embind_tsgen.cpp: https://github.com/emscripten-core/emscripten/blob/main/test/other/embind_tsgen.cpp
 .. _embind_tsgen.d.ts: https://github.com/emscripten-core/emscripten/blob/main/test/other/embind_tsgen.d.ts
+.. _Explicit Resource Management: https://tc39.es/proposal-explicit-resource-management/

src/closure-externs/closure-externs.js

@@ -261,3 +261,9 @@ var moduleRtn;
  */
 Navigator.prototype.webkitGetUserMedia = function(
     constraints, successCallback, errorCallback) {};
+
+/**
+ * A symbol from the explicit resource management proposal that isn't yet part of Closure.
+ * @type {symbol}
+ */
+Symbol.dispose;

src/lib/libembind.js

@@ -1558,7 +1558,9 @@ var LibraryEmbind = {
     '$delayFunction',
   ],
   $init_ClassHandle: () => {
-    Object.assign(ClassHandle.prototype, {
+    let proto = ClassHandle.prototype;
+
+    Object.assign(proto, {
       "isAliasOf"(other) {
         if (!(this instanceof ClassHandle)) {
           return false;
@@ -1644,6 +1646,12 @@ var LibraryEmbind = {
         return this;
       },
     });
+
+    // Support `using ...` from https://github.com/tc39/proposal-explicit-resource-management.
+    const symbolDispose = Symbol.dispose;
+    if (symbolDispose) {
+      proto[symbolDispose] = proto["delete"];
+    }
   },
 
   $ClassHandle__docs: '/** @constructor */',

test/test_other.py

@@ -3379,6 +3379,37 @@ def test_embind_long_long(self, args):
     self.do_runf('embind/test_embind_long_long.cpp', '1000000000000n\n-1000000000000n',
                  emcc_args=['-lembind', '-sWASM_BIGINT'] + args)
 
+  @requires_node_canary
+  def test_embind_resource_management(self):
+    self.node_args.append('--js-explicit-resource-management')
+
+    create_file('main.cpp', r'''
+      #include <emscripten.h>
+      #include <emscripten/bind.h>
+
+      using namespace emscripten;
+
+      class MyClass {};
+      EMSCRIPTEN_BINDINGS(my_module) {
+          class_<MyClass>("MyClass")
+          .constructor();
+      }
+
+      int main() {
+        EM_ASM({
+          let instanceRef;
+          {
+            using instance = new Module.MyClass();
+            assert(!instance.isDeleted());
+            // "Leak" a reference to the instance just to check that it's deleted.
+            instanceRef = instance;
+          }
+          assert(instanceRef.isDeleted());
+        });
+      }
+    ''')
+    self.do_runf('main.cpp', emcc_args=['-lembind'])
+
   @requires_jspi
   @parameterized({
     '': [['-sJSPI_EXPORTS=async*']],