by @bwasti
tl;dr - Using WeakRefs, you can pretty easily implement automatic memory management for objects exposed from WebAssembly with JavaScript's garbage collector.
(Keep in mind "automatic memory management" does not mean "garbage collection". This post omits any specific implementation choices. Jump to the code here.)
It's well known that JavaScript has garbage collection by default. WebAssembly doesn't have such a mechanism, as it operates at a much lower level. You only get a big slab of memory. Luckily you can resize it.
So how the heck do you do anything? Well, you can place things inside this slab of memory where ever you'd like. It's all yours. However, deciding where to place things isn't always obvious.
Fortunately, people have written utilities to make this placement problem a bit easier.
The most common of these are malloc
and free
. Often, they're written in C and
that's easily compiled to WebAssembly.
But then another problem arises: when do you actually call free
?
In many languages this is done for you automatically (such as with scoping rules).
That's well and good if you're mostly working within the compiled language
and only passing small bits to JavaScript.
On the other hand, if you're dealing with big objects and want to pass around pointers, the moment you pass them to JavaScript, you lose all the niceties the compiled language had to offer. You might even end up with memory leaks.
This can of course be dealt with, but that's a hassle.
Ideally we'd just register our pointers and some function to free
them with JavaScript's
garbage collection mechanism.
This does exist to some degree with a
FinalizationRegistry,
but my minimal testing has not shown it to work very reliably.
There are no guarantees that finalization callbacks are actually called
and I've found my code stuck waiting forever.
It's important to also note that there's a proposal for WebAssembly involving typed heaps and other new semantics that would also enable garbage collection. This is unfortunately only in phase 2, which means it hasn't been implemented anywhere let alone shipped to most browsers.
A viable solution that I've found is to spin on weak references (brrr) and free
underlying
pointers when the weak refs go null.
(WeakRefs are supported in every major browser.)
Below is an example in C++, but the concept should hold for any managed memory language.
Here's the C++ class we'll expose:
class MyClass {
public:
MyClass(int hide) : hidden(hide) { }
int my_method() { return hidden * 2; }
private:
int hidden;
};
The steps are as follows:
In C++:
extern "C" {
EXPORT MyClass* _MyClass__constructor(int h) { return new MyClass(h); }
EXPORT void _MyClass__destructor(MyClass* m) { delete m; }
EXPORT int _MyClass__my_method(MyClass* m) { return m->my_method(); }
}
and in JavaScript:
const { instance } = await WebAssembly.instantiateStreaming(fetch("./demo.wasm"));
const {
_MyClass__constructor,
_MyClass__destructor,
_MyClass__my_method
} = instance.exports;
const managed = {};
async function memory_management_loop() {
while (true) {
const keys = Object.keys(managed);
for (let key of keys) {
const [weakref, deleter] = managed[key];
if (!weakref.deref()) { // this object was garbage collected
deleter(); // call the user provided deleter
delete managed[key];
}
}
// cleanup every 100ms, or replace with window.requestIdleCallback()
await new Promise(resolve => setTimeout(resolve, 100));
}
}
manage
functionfunction manage(ptr, weakref, deleter) {
managed[ptr] = [weakref, deleter];
}
manage
on the objectclass MyClass {
constructor(h) {
const data = _MyClass__constructor(h);
// make sure the third argument does not reference `this`
manage(data, new WeakRef(this), () => {
_MyClass__destructor(data); // data is just a pointer :)
});
this.data = data;
}
my_method() {
return _MyClass__my_method(this.data);
}
};
Now you can use your objects as fully garbage collected JavaScript objects.
for (let i = 0; i < 50; ++i) {
const m = new MyClass(5 + i);
console.log(m.my_method());
}
All 50 created MyClass
objects go out of scope and will be cleaned up soon after the above code executes.
If you'd like to see the whole code used (pure clang
!),
please see this repo: https://github.com/bwasti/web_assembly_experiments/tree/main/memory_management
You'll want to run make
and then python3 -m http.server
or equivalent to open demo.html
.
For one, this isn't exactly "production ready." But, it'll let you hack around one of the more annoying deficiencies WebAssembly/JavaScript interaction has today.
Second, nothing here actually implements garbage collection for WebAssembly. We're just using the garbage collection mechanism in JavaScript as a way to call WebAssembly destructors at the appropriate (or, at least, valid) time.
A more involved example would use something like C++'s shared pointers to implement ref-counting based cleanup inside the compiled code. One could also go a step further and actually run a background process to periodically cleanup memory (called from JavaScript of course).
If we wanted to further integrate with JavaScript's garbage collection, WebAssembly would need a way to hold strong references on JS objects. This requires another layer of wrapping. Luckily, exposing JavaScript calls to WebAssembly is a straight-forward process:
function tell_js_to_decref(ptr) {
delete held_refs[ptr];
}
const { instance } = await WebAssembly.instantiateStreaming(fetch("./demo.wasm"), {
env: {
decref: ptr => tell_js_to_decref(ptr)
}
});
And now we've got tell_js_to_decref()
in WebAssembly as decref
.
If you'd like, you can follow me on Twitter here: @bwasti