Define garbage collection rooting APIs

[fitzgen]

Rooting prevents GC objects from being collected while they are actively being used.

We have a few sometimes-conflicting goals with our GC rooting APIs:

1. Safety: It should never be possible to get a use-after-free bug because the user misused the rooting APIs, the collector "mistakenly" determined an object was unreachable and collected it, and then the user tried to access the object. This is our highest priority.

2. Moving GC: Our rooting APIs should moving collectors (such as generational and compacting collectors) where an object might get relocated after a collection and we need to update the GC root's pointer to the moved object. This means we either need cooperation and internal mutability from individual GC roots as well as the ability to enumerate all GC roots on the native Rust stack, or we need a level of indirection.

3. Performance: Our rooting APIs should generally be as low-overhead as possible. They definitely shouldn't require synchronization and locking to create, access, and drop GC roots.

4. Ergonomics: Our rooting APIs should be, if not a pleasure, then at least not a burden for users. Additionally, the API's types should be Sync and Send so that they work well with async Rust.

For example, goals (3) and (4) are in conflict when we think about how to support (2). Ideally, for ergonomics, a root would automatically unroot itself when dropped. But in the general case that requires holding a reference to the store's root set, and that root set needs to be held simultaneously by all GC roots, and they each need to mutate the set to unroot themselves. That implies Rc<RefCell<...>> or Arc<Mutex<...>>! The former makes the store and GC root types not Send and not Sync. The latter imposes synchronization and locking overhead. So we instead make GC roots indirect and require passing in a store context explicitly to unroot in the general case. This trades worse ergonomics for better performance and support for moving GC and async Rust.

Okay, with that out of the way, this module provides two flavors of rooting API. One for the common, scoped lifetime case, and another for the rare case where we really need a GC root with an arbitrary, non-LIFO/non-scoped lifetime:

1. RootScope and Rooted<T>: These are used for temporarily rooting GC objects for the duration of a scope. Upon exiting the scope, they are automatically unrooted. The internal implementation takes advantage of the LIFO property inherent in scopes, making creating and dropping Rooted<T>s and RootScopes super fast and roughly equivalent to bump allocation.

   This type is vaguely similar to V8's HandleScope.

   Note that Rooted<T> can't be statically tied to its context scope via a lifetime parameter, unfortunately, as that would allow the creation and use of only one Rooted<T> at a time, since the Rooted<T> would take a borrow of the whole context.

   This supports the common use case for rooting and provides good ergonomics.

2. ManuallyRooted<T>: This is the fully general rooting API used for holding onto non-LIFO GC roots with arbitrary lifetimes. However, users must manually unroot them. Failure to manually unroot a ManuallyRooted<T> before it is dropped will result in the GC object (and everything it transitively references) leaking for the duration of the Store's lifetime.

   This type is roughly similar to SpiderMonkey's PersistentRooted<T>, although they avoid the manual-unrooting with internal mutation and shared references. (Our constraints mean we can't do those things, as mentioned explained above.)

At the end of the day, both Rooted<T> and ManuallyRooted<T> are just tagged indices into the store's RootSet. This indirection allows working with Rust's borrowing discipline (we use &mut Store to represent mutable access to the GC heap) while still allowing rooted references to be moved around without tying up the whole store in borrows. Additionally, and crucially, this indirection allows us to update the actual GC pointers in the RootSet and support moving GCs (again, as mentioned above).

[fitzgen]

Part of #5032

[github-actions]

Subscribe to Label Action

cc @fitzgen, @peterhuene

This issue or pull request has been labeled: "cranelift", "fuzzing", "wasmtime:api", "wasmtime:c-api", "wasmtime:ref-types"

Thus the following users have been cc'd because of the following labels:

• fitzgen: fuzzing, wasmtime:ref-types
• peterhuene: wasmtime:api, wasmtime:c-api

To subscribe or unsubscribe from this label, edit the .github/subscribe-to-label.json configuration file.

Learn more.

[alexcrichton]

At a high level this all looks good to me. I think there's work we can do to build confidence in the internals, though. While I realize we can't remove all unsafe here I suspect we don't need quite so many just-a-typed-transmute functions. Those are really difficult to reason about the safety.

Additionally I think this is definitely an area where we're going to be leaning on miri pretty heavily. Can you ensure that there's tests that run in miri doing all the various bits and bobs with the API other than actually calling in to wasm?

[alexcrichton]

For a future PR, and with more GC types, I think it'd be reasonable to move these impls to the gc_ref.rs module to avoid the #[cfg] here

[fitzgen]

That's a good idea.

[fitzgen]

@alexcrichton I think I've addressed everything in your review.

Going to start rebasing on main, but I think you can take another look now.

[alexcrichton]

Handling the fallout for this in the wasmtime-cpp repository I think that the requirement to take a wasmtime_context_t as an argument for value operations invalidates the preexisting copy constructor and copy assignment operator. Not an issue per se, but it appears that removing those also invalidates this pattern where arguments can't be constructed as {6, 27} any more. I'll admit I'm not C++ expert and the wall of error messages I'm looking at don't exactly explain why it's related to the copy constructor/assignment.

Anyway that's a long way of asking, do you think we're going to indefinitely want to have a context argument on these functios into the future, even with the idea of an indexed heap?

[fitzgen]

Anyway that's a long way of asking, do you think we're going to indefinitely want to have a context argument on these functios into the future, even with the idea of an indexed heap?

Yes, unfortunately, I do. At least in Rust. I could see a C/C++ specific approach to alleviating this, however...

Indexed GC heaps are orthogonal to the rooting approach here.

In order to support moving GCs, we need to either:

1. Be able to precisely identify raw (whether pointer or index) GC roots and mutate them after an object moves.

2. Or support pinning GC references temporarily such that they do not move while rooted. This allows us to avoid the need to update GC roots after an object moves.

Option (2) is a pretty big constraint on GC implementations. We would have to really bend over backwards to support that in our planned copying collector.

So focusing on option (1), there are basically two approaches available to us for implementing rooting APIs:

1. Indirection. Store the raw GC references in some sort of table (aka our GcRoots) and have the user's root type index into that table (aka our Rooted<T>/ManuallyRooted<T>). This is nice, and works well with Rust and its move semantics, because we don't need to track down where all the Rooted<T>s and ManuallyRooted<T>s are in memory and we don't need to pin them or do any sort of updates on move so that we can update their internal GC reference after an object moves. Instead, the GC refs are all in the table and we can just do a pass over the table to update the GC refs, and all the Rooted<T>s index into the table and get the moved GC ref the next time they do some operation on their referent. The downside is that all constructing and dropping GC roots in this scheme requires access to the table, in the general case, as you've found.

2. Intrusive lists/some other intrusive data structure. This is the approach that SpiderMonkey takes, for example. All the user's roots hold raw GC references and are additionally members of an intrusive list that is associated with their GC heap. This allows the GC to walk the intrusive list and update all rooted GC references after moving objects. But this means that you need to pin the GC root type or have move constructors that keep the intrusive list valid as the GC root is moved in memory. This works well with C++ but very much not so well with Rust, which is why we went with the first option.

So, if we wanted to make the C/C++ API a little more ergonomic, we could support the intrusive list option. Ideally not in the Rust embedder API, but maybe with some doc(hidden) stuff that is feature gated for when we are building the C API crate. FWIW, this is also fairly unsafe not just in terms of the invariants around maintianing the intrusive list, but in that right now with the table/indirect approach we only ever use indices and we bounds check their accesses into the table so "use after free"-style bugs are still memory safe, which limits how bad things can go wrong. That is not the case with the intrusive list approach.

[alexcrichton]

Ok nah that all sounds good, no need to go the intrusive list route just yet, I think it's ok if things are slightly less ergonomic in the C++ bindings API unless a C++ wizard more adept than I can figure out a better solution

[rockwotj]

Not an issue per se, but it appears that removing those also invalidates this pattern where arguments can't be constructed as {6, 27} any more

https://github.com/bytecodealliance/wasmtime-cpp/blob/da579e78f799aca0a472875b7e348f74b3a04145/include/wasmtime.hh#L2457C32-L2458

The function you're calling takes a std::vector and you're passing in an initializer_list, which copies things out of the vector: https://godbolt.org/z/h844YKxYq

You'll need to use a move iterator to force moving out of the container. One of the annoying bits about C++ iterators. You could use ranges/views to make this more seemless.

As for dropping the copy constructor/assignment I think that's fine, but it can be useful to have an explicit copy function that takes a context.

[alexcrichton]

Makes sense! In bytecodealliance/wasmtime-cpp#48 I ended up adding overloaded versions for std::initializer_list and std::vector with a "base" version that takes an iterator. That being said I don't know how to best generically take an iterator in C++

[rockwotj]

Added a suggestion here: https://github.com/bytecodealliance/wasmtime-cpp/pull/48/files#r1525490495