Repository navigation
Description
Pre-Proposal: Wasm GC Support in the Canonical ABI
This issue proposes extensions to the Component Model's Canonical ABI for Wasm GC support and describes some of the motivation for particular choices. I am in the process of implementing these extensions in wasm-tools and wasmtime. My goals are to kick off discussion of how best to integrate GC and the canonical ABI, build consensus, and eventually get these extensions merged into the component model spec itself.
Emoji
Most important things first, I propose that we use the 🛸 emoji (an unidentified flying object1) to represent the Wasm GC extension to the component model in the Explainer.md.
New Canonical Options
-
gc: Switches the canonical ABI over to GC mode, from linear memory mode, when present.- Encoding:
0x08
- Encoding:
New Canonical Definitions
-
(canon array.new_array dst src) : [(ref null src) i32 i32] -> [(ref dst)]:
polyfill for thearray.new_arrayinstruction from the
more-array-constructors core Wasm proposal.Note: Needed in order to create immutable arrays of dynamic length and
content.- Encoding:
0x43 dst:<typeidx> src:<typeidx> => (canon array.new_array dst src (core func))
- Encoding:
-
(canon array.new_memory dst src) : [i32 i32] -> [(ref dst)]:
polyfill for thearray.new_memoryinstruction from the
more-array-constructors core Wasm proposal.Note: Needed in order to create immutable arrays of dynamic length and
content.- Encoding:
0x44 dst:<typeidx> src:<core:memoryidx> => (canon array.new_memory dst src (core func))
- Encoding:
-
(canon array.new_table dst src) : [i32 i32] -> [(ref dst)]:
polyfill for thearray.new_arrayinstruction from the
more-array-constructors core Wasm proposal.Note: Needed in order to create immutable arrays of dynamic length and
content.- Encoding:
0x45 dst:<typeidx> src:<core:tableidx> => (canon array.new_table dst src (core func))
- Encoding:
GC Type Lowerings
The lowerings are summarized in the following table, more details follow after.
| Component Type | Flat Value Type(s) | GC Heap Storage Type | Notes |
|---|---|---|---|
bool |
i32 |
i8 |
|
s8 |
i32 |
i8 |
|
u8 |
i32 |
i8 |
|
s16 |
i32 |
(same) | |
u16 |
i32 |
(same) | |
s32 |
i32 |
(same) | |
u32 |
i32 |
(same) | |
s64 |
i64 |
(same) | |
u64 |
i64 |
(same) | |
f32 |
f32 |
(same) | |
f64 |
f64 |
(same) | |
char |
i32 |
(same) | |
string when string-encoding=utf8 |
(ref $utf8) |
(same) |
(rec (type $utf8 (sub final (array i8)))) |
string` when `string-encoding=utf16 |
(ref $utf16) |
(same) |
(rec (type $utf16 (sub final (array i16)))) |
string` when `string-encoding=latin1+utf16 |
(ref array) |
(same) |
(rec (type $latin1 (sub final (array i8))))
(rec (type $utf16 (sub final (array i16))))Lifting enforces that the |
(variant ...(case T)) |
(ref $variant) |
(same) |
(rec (type $variant (sub (struct (field $discriminant D))))
...(type $case-<i> (sub final $variant (field $discriminant i32)
(field T'))))Where Lifting enforces that the |
(list T) |
(ref $list) |
(same) |
(rec (type $list (array T')))Where |
(record ...T) |
...T' where T' = flat_value_types(T) |
(ref $r) where (rec (type $r (sub final (struct ...(field T'))) and T' = gc_heap_storage_type(T) |
|
(tuple ...T) |
...T' where T' = flat_value_types(T) |
(ref $t) where (rec (type $t (sub final (struct ...(field T'))) and T' = gc_heap_storage_type(T) |
|
(flags ...) |
i32 |
(same) | Same as linear memory lifting and lowering. |
(enum ...) |
i32 |
(same) | Same as linear memory lifting and lowering. |
(option T) |
(see notes) | (see notes) |
Desugars into (variant (case "none" unit) (case "some" T))and is then lifted and lowered the same as any other |
(result T E) |
(see notes) | (see notes) |
Desugars into (variant (case "ok" T) (case "error" T))and is then lifted and lowered the same as any other |
(own ...) |
(ref extern) |
(same) | |
(borrow ...) |
(ref extern) |
(same) | |
(future ...) |
(ref extern) |
(same) | |
(stream ...) |
(ref extern) |
(same) | |
error-context |
(ref extern) |
(same) |
bool and {s,u}{8,16}
These types have different lowerings depending on whether we are lowering them to flat value types (arguments and results) or into a storage type on the GC heap (a field inside another component type). When lowered to a value type, these become i32 values. When lowered to a storage type, these become i8 (bool, {s,u}8) and i16 values ({s,u}16).
Example when lowering into flat values:
;; Component signature.
(type $sig (func (param "x" u8)
(param "y" s16)
(param "z" bool)))
;; Lowered core signature.
(core type $sig' (func (param i32 i32 i32)))Example when lowering into GC heap storage types:
;; Component type.
(type $tup (tuple bool s8 u16))
;; The associated core type lowering into storage types.
(core type $tup' (struct (field i8) (field i8) (field i16))){s,u}{32,64}, f{32,64}, and char
These component types are lowered to the same corresponding core type as in the linear memory version of the canonical ABI, regardless whether we are lowering into a flat value type or a GC heap storage type.
Example when lowering into flat values:
;; Component signature.
(type $sig (func (param "x" u32)
(param "y" s64)
(param "z" f32)))
;; Lowered core signature.
(core type $sig' (func (param i32 i64 f32)))Example when lowering into GC heap storage types:
;; Component type.
(type $tup (tuple u32 s64 f32))
;; The associated core type lowering.
(core type $tup' (struct (field i32) (field i64) (field f32)))string
string types are lowered to non-nullable references to core arrays of code points. The array element type used to represent code points depends on the string-encoding option given.
The lowering is the same when lowering to both flat value types and GC heap storage types.
When string-encoding=utf8
UTF-8 strings are lowered into non-nullable (ref $utf8) references, where $utf8 is a final array with no given supertype and i8 elements defined in its own rec group.
;; Component signature.
(type $sig (func (param "s" string)))
;; The lowered core signature when `string-encoding=utf8`.
(core rec (type $utf8 (sub final (array i8))))
(core type $sig' (func (param (ref $utf8))))When string-encoding=utf16
UTF-16 strings are lowered into non-nullable (ref $utf16) references, where $utf16 is a final array with no given supertype and i16 elements defined in its own rec group.
;; Component signature.
(type $sig (func (param "s" string)))
;; The lowered core signature when `string-encoding=utf16`.
(core rec (type $utf16 (sub final (array i16))))
(core type $sig' (func (param (ref $utf16))))When string-encoding=latin1+utf16
Compact latin1 or UTF-16 encoded strings are lowered to non-nullable (ref array) references that are always either an instance of $utf16 (a final array with no given supertype and i16 elements defined in its own rec group) or $latin1 (a final array with no given supertype and i8 elements defined in its own rec group).
Lifting these values checks that the given (ref array) is an instance of one of the two types and otherwise traps.
;; Component signature.
(type $sig (func (param "s" string)))
;; The lowered signature when `string-encoding=latin1+utf16`.
(core rec (type $latin1 (sub final (array i8))))
(core rec (type $utf16 (sub final (array i16))))
(core type $sig' (func (param (ref array))))record and tuple
When lowering into flat value types, these types behave like the linear memory canonical ABI, recursively flattening their field types as long as they fit within the maximum number of flat values.
When lowering into GC heap storage types, these types lower to a non-nullable (ref $s) reference to a final struct whose fields are the point-wise lowering of the component record or tuple fields into storage types, and which is defined in its own singleton rec group. All fields are non-mut.
;; Component types.
(type $point (tuple s32 s32))
(type $line (record (field "a" $point)
(field "b" $point)))
;; Component function signature and associated lowering into flat value types.
;;
;; Note that the `record` and `tuple` fields are flattened.
(type $sig (func (param "a" $line)))
(core type $sig' (func (param i32 i32 i32 i32)))
;; Component function signature and associated lowering into GC heap storage
;; types.
;;
;; Here, each `record` and `tuple` is its own `struct`, and the fields are not
;; flattened.
(type $list-of-lines (list $line))
(type $sig2 (func (param "lines" $list-of-lines))))
(core rec (type $point' (sub final (struct (field i32)
(field i32)))))
(core rec (type $line' (sub final (struct (field (ref $point')
(ref $point'))))))
(core rec (type $list-of-lines' (sub final (array $line'))))
(core type $sig2' (func (param (ref $list-of-lines'))))variant
Component variant types are lowered the same way whether into flat value types or GC heap storage types.
They are lowered into a rec group containing:
- A
$basestructtype, that is notfinal, with a single discriminant field of typediscriminant_type(cases)that is notmut. - For each case, a
structtype that isfinal, is a subtype of the base (1) type, contains the discriminant field, and then contains a non-mutfield which is thecase's payload type lowered into a GC heap storage type.
The lowered value is a non-nullable (ref $base) reference.
Lifting checks that the discriminant is in the range 0 <= i < len(cases) and that when the discriminant is i, the reference is an instance of the ith case's associated struct type; otherwise it raises a trap. This enables br_on_cast/ref.test subtype checks.
;; Component type and signature.
(type $animal
(variant
(case $cat "cat" u32)
(case $dog "dog" u16)
(case $rabbit "rabbit" u16)))
(type $sig (func (param "animal" $animal)))
;; The associated core lowering.
(core rec
(type $animal' (sub (struct (field $discriminant i8))))
(type $cat' (sub final $animal' (struct (field $discriminant i8)
(field i32))))
(type $dog' (sub $animal' (struct (field $discriminant i8)
(field (mut i16)))))
(type $rabbit' (sub $animal' (struct (field $discriminant i8)
(field i16)))))
(core type $sig' (param (ref $animal')))list<T>
The list<T> lowering is the same for both flat value types and GC heap storage types.
Component list<T> types are lowered to a non-nullable (ref $array) reference where $array is a final array with no declared supertype that is defined in its own rec group and with non-mut elements of T lowered to a GC heap storage type.
;; Component type and signature.
(type $bools (list bool))
(type $sig (func (param "x" $bools)))
;; The associated core lowering.
(core rec (type $bools' (sub final (array i8))))
(core type $sig' (func (param (ref $bools'))))flags and enum
Component flags and enum types are lowered in the same manner as in the linear memory version of the canonical ABI, regardless whether we are lowering into a value type or a GC heap storage type.
option<T>
option<T> is sugar for the following variant type:
(variant
(case "some" T)
(case "none"))options are desugared and then lowered under the same rules as any other variant type.
;; Component type and signature.
(type $tri-bool (option bool))
(type $sig (func (param "b" $tri-bool)))
;; Desugared `$tri-bool`.
(type $tri-bool (variant (case "some" bool)
(case "none")))
;; The associated core lowering.
(core rec
(type $tri-bool' (sub (struct (field $discriminant i8))))
(type $tri-bool-some' (sub final $tri-bool' (field $discriminant i8)
(field $payload i8)))
(type $tri-bool-none' (sub final $tri-bool' (field $discriminant i8))))result<T, E>
result<T, E> is sugar for the following variant type:
(variant
(case "ok" T)
(case "error" E))results are desugared and then lowered under the same rules as any other variant type.
;; Component type and signature.
(type $my-result (result u32 bool))
(type $sig (func (param "r" $my-result)))
;; Desugared `$my-result`.
(type $my-result (variant (case "ok" u32)
(case "error" bool)))
;; The associated core lowering.
(core rec
(type $my-result' (sub (struct (field $discriminant i8))))
(type $my-result-ok' (sub final $my-result' (field $discriminant i8)
(field $payload i32)))
(type $my-result-error' (sub final $my-result' (field $discriminant i8)
(field $payload i8))))own, borrow, future, stream, and error-context
These component types are lowered into references to non-nullable (ref extern) references.
Their lowering is identical for both flat value types and GC heap storage types.
;; Component types and signature.
(type $file (resource (rep i32)))
(type $future-bool (future bool))
(type $stream-u32 (stream u32))
(type $sig (func (param "a" (own $file))
(param "b" (borrow $file))
(param "c" $future-bool)
(param "d" $stream-u32)))
;; The associated core lowering.
(core type $sig' (func (param (ref extern)
(ref extern)
(ref extern)
(ref extern))))Footnotes
-
Object. Haha -- get it?? Like GC objects. GET IT!? HAHA WHY AREN'T YOU LAUGHING?!?!?!?!? ↩
Activity
fitzgen commentedon Jun 3, 2025
+cc @lukewagner @alexcrichton
fitzgen commentedon Jun 3, 2025
Realization: we could actually remove the discriminants from sum types if we prescribe that the cases are all defined in the same
recgroup.I'll prototype this and update the OP once it is working in
wasm-tools.Remove discriminants from sum types
wasmparser(CM+GC): Add support for lowering variants, options, and re…
wasmparser(CM+GC): Add support for lowering variants, options, and re…
fitzgen commentedon Jun 3, 2025
Done and done
lukewagner commentedon Jun 4, 2025
This is really exciting and I appreciate the clear writeup! Also, I love the approach of maximally-deriving the ABI from the core function type; that's an elegant solution to an otherwise gross problem. Overall, 👍 from me.
A few small questions/suggestions:
I'm probably misunderstanding the proposal, wasm-gc or both, but: for
variantet al, your examples all put the supertype in a separate rec group than the case subtypes but I would think that this doesn't expose the semantic link between "the variant type" and "the case types" that you need to let the core function type tell the whole story. E.g., iiuc, there's no "edge" in the type graph from$animal'to the rec group containing$dog'. (The edge exists in the other direction, ofc, but that's many-to-1, so you couldn't talk about "the rec group that contains subtypes of this supertype".) Instead, I would think that, since we're sortof hijacking rec groups in this scheme anyways, we'd say that variants have to refer to astructtype that is the first of its rec group and all the subsequent rec group members must be its cases; then thetypeidxused in the core function type points to a rec group that points to the cases.While you're right about the reason that
optioncan't representnonewithref.nullin general, could we say that, whenoption<T>has a non-null-allowingT,ref.nullrepresentsnone? This is ad hoc and irregular, but we are licensed to do that in the CABI when it's a significant win andoptionis very common and I expect this optimization would to 95% ofoptions in practice.result<T>(noE) andresult(noT) are also super common and I think perhaps worth optimizing. Could the former usenullforerrorand the latter return a (boolean)i32(making it no less efficient thanenum, so that no one has the perverse incentive to use anenumfor aresultfor perf reasons)?lukewagner commentedon Jun 5, 2025
Two more follow-up thoughts:
latin1+utf16string-encoding, there's the question of how to communicate the dynamic "is it Latin-1 or UTF-16?" boolean (which is packed with the length into ani32when using linear memory). One idea is that you could take a page from how variants work and have the static type be(ref null? array)and dynamically accept/produce either(ref (array i8))or(ref (array i16)).own,borrow,futureandstream(as well as waitable sets and async subtasks): one issue I just realized is that variousdropbuilt-ins trap under various conditions (ownandborrowtrap if there are any extant async import calls to which they were lent; the writable end of afuturetraps if dropped without having written a value; etc). As a general rule, we try to avoid ever allowing user code of a safe language to hit a raw wasm trap, so somehow we need to figure out how the language runtime (running as wasm using the CABI) is able to avoid hitting these traps. One option would be to extend the "drop if unreachable" semantics to be "drop if unreachable and the trapping conditions are met", but I'm thinking this will get tricky and subtle. Another option is to force the wasm guest to rootexternrefs during times when they would trap if they became unreachable, but this might end requiring the wasm guest to maintain a lot of parallel bookkeeping already maintained by the C-M, maybe adding non-trivial overhead. So I wonder if a nice third option is to leave these types the same as with linear memory (i32s that need to be dropped), but introduce new canon built-ins that provide postmortem-notification analogous-to and polyfilled-viaFinalizationRegistryand then allow the language runtime to use this primitive to Do The Right Thing itself. Such a built-in could also be used for other guest-internal purposes (such as associating a linear-memory buffer that needs to be freed with a wasm-GC object).rossberg commentedon Jun 6, 2025
A few drive-by comments:
@lukewagner:
FWIW, I don't think it is gonna be even close to 95%. Languages with parametric polymorphism typically don't or can't do such a specialisation, because it would require costly runtime type passing and dispatch. That probably includes languages like Java with its Optional type.
lukewagner commentedon Jun 6, 2025
@rossberg
Ah, interesting point. When I said "95%", I was talking about the percent of
options appearing in WIT interfaces, but also thinking about howoptions are represented "at rest" in various languages is a good for regularity.Question: if a lowered function type lowers an
optioninto a non-eqreference with an emptystructrepresentingnone, can the engine implementnonewith a single-per-type allocation (since the identity isn't observable viaeqor mutation)? If so, then thenulloptimization wouldn't even be that big of a win.rossberg commentedon Jun 6, 2025
I would represent None as an i31 ref with value zero (or any random value). It is just an instance of a variant type, where runtimes typically represent nullary constructors as different tagged ints. Which, now that I mention it, is something the variant encoding should also support.
Edit: Though null would equally work for option. What these languages generally can't do is unboxing Some.
gertvv commentedon Jun 9, 2025
This is awesome! As an outsider, the wording on variant types is confusing:
However the example defines a
(struct (field i32))which looks like a tagged union, but this is not explicitly stated. Is this the correct interpretation? And if so, can the lowering choose to use a smaller (packed) int instead, like the linear memory ABI does?fitzgen commentedon Jun 13, 2025
Ah I just forgot to update the example. There shouldn't be any
(field i32)there. Will update the OP shortly.fitzgen commentedon Jun 13, 2025
@lukewagner
Because the shape of the cases' rec group is fully defined, there doesn't need to be an explicit link: the engine/fused adapter compiler can simply (re)define the cases' rec group and then rely on type canonicalization.
This approach is slightly more flexible than keeping the base type in the same rec group as the cases, since it allows the base type to be defined in any rec group of the producer's choosing.
I'm fine with ultimately doing this kind of thing, but I am not going to do it for now, in my current prototyping, and therefore I am not going to update the OP with it either (which I will try to keep in sync with my prototyping).
As this extension settles and gets upstreamed into the spec, it should of course describe what we ultimately come to consensus on standardizing, and not what I just happen to have prototyped, but we can cross that bridge when we get to it.
Yeah, this makes sense and the OP reflects a misunderstanding on my part. Will update as soon as I fix my prototype.
Alternatively, we could continue to require explicit drop calls (as we do now for linear memory) rather than say that these things are implicitly dropped on finalization. If the
externrefbecomes unreachable without the future/stream having been explicitly dropped, then the future/stream is never dropped. Language-specific bindings generators can wrap this stuff up similar to what they would have to do now when translating to the linear memory variant of the ABI (e.g. Python would use itswithconstruct).Then, as a next step, we can introduce those canonical builtins for finalizers that allows them to Do The Right Thing.
This approach is smaller and more incremental and crucially doesn't require finalizer support in implementations initially at all.
fitzgen commentedon Jun 13, 2025
@rossberg
This gets at the philosophical question of how much duck typing we want to do. The proposal is doing some amount already with its matching of component types against many core types by their shape, but right now they always match against one shape modulo nullability, subtyping, and rec group. Allowing
i31refin various places is widening things such that we would match against multiple shapes. It seems to me like this could potentially be a slippery slope: How many shapes is enough? How do we decide whether a shape is worthy of matching against?I'm not saying I'm against adding support for
i31ref, but I do think we should consider what design principles we want to follow in this CM+GC extension.It is also possible my concerns are overblown, and this is the only additional shape we will actually want to match against.
14 remaining items
justinfagnani commentedon Apr 22, 2026
Is there anything that interested parties can do to help this effort along?
I'm making a new language for Wasm GC with planned component support built into the compiler, so this issue is at a very critical intersection of features for me.
spotandjake commentedon Apr 22, 2026
Not quite sure on your exact question (hopefully, with more info can help you out there). I just wanted to mention that nothing stops you from copying your gc information into linear memory and using the regular component model as it is right now, the only real dissadvantages to this approach, are you have to copy the data which means walking your gc structs or creating converters somehow and you don't get support for finalizers so there isn't really a way to communicate to another component your done with a resource without manually calling free.
justinfagnani commentedon Apr 23, 2026
@spotandjake yes, you can always copy data in and out of linear memory. This is what I do now.
Like @tanishiking points out, for GC-to-GC languages calls, this results in 3 copies per call: 1 in the calling component from GC types to linear memory, 1 in the host from caller linear memory to receiver linear memory, and 1 in the receiver component from linear memory into GC types. Then 3 copies again for return values. And it's not just the copies, you need to include the code to map to and from linear memory, and an allocator.
So this issue is critical for all Wasm GC languages that are used to write components.
kevmoo commentedon Apr 23, 2026
What @justinfagnani said! (Hi, @justinfagnani 👋 )
simolus3 commentedon Oct 18, 2026
Is there something we can do to help with this, e.g. by turning this into a PR?
I've built component model support for Dart using the approach of copying across the component boundary, but the lack of finalizers means I can't reference any object/resource owned by a linear memory component from a Dart object without leaking memory. This means I have to reimplement things like strings, regular expressions and number formatting over WASM arrays instead of e.g. bundling a Rust library providing this (and strings implemented in linear memory can e.g. use faster SIMD searches than an
(array i16)which only allows byte-level access). So even if we ignore copies at the CM boundary, not having finalizers makes implementing languages much harder than it needs to be.I think having canon definitions emulating a finalization registry (and perhaps weak references too) would be very helpful for GC-based languages. On the web, these languages already import JS weakrefs and finalization registries. Without these primitives in the component model, we also can't implement the full standard library of those languages.
With a finalization registry, GC-based components could allocate linear memory to implement their strings and lists objects and then free them when the object becomes unreferenced. By adopting linear memory for strings and lists, a GC component could use the current ABI without excessive copying.
Does have a PR defining these have any chance of landing currently? I would be happy to help spec builtins for weak references and finalization registries as a first step and open a PR for that.
Also one question on the original proposal: For lists, would it make sense to have an option to pass a subarray? For a component using linear memory, passing a slice across components is a mostly a matter of pointer arithmetic. For a JS guest, a
(list u8)should probably be represented as aUint8List, which is likely implemented with a backing(array i8)+ offset + length. Being able to pass this without copying again would be nice.lukewagner commentedon Oct 21, 2026
That seems like a pretty good idea for an incremental first addition to me!
So just to check my understanding: you're suggesting no changes to lifting/lowering (yet), but rather a few new ABI built-ins (that can use Core WebAssembly reference types b/c they're ABI built-ins) that Jco could polyfill with
FinalizationRegistery/WeakRef? If so, before a full PR, maybe a good first step would be to build a prototype implementation of these new ABI built-ins in Jco that you could validate with your Dart implementation? (cc @vados-cosmonic for thoughts.) Since this issue is already a bit long and is mostly focused on the lifting/lowering ABI questions, it's probably also a good idea to create a new issue dedicated to this idea to sketch out the shape of these new ABI built-ins before or during the prototyping.justinfagnani commentedon Oct 22, 2026
Shouldn't weakrefs and finalization registries be in Wasm GC proper, not the component API? This would be one more thing that a toolchain has to compile differently for core modules on JS vs components.
spotandjake commentedon Oct 22, 2026
I had a similar concern, if finalization registries and or weakrefs are added to the component model, it may duplicate effort or cause duplicate apis if similar wasm proposals are made as extensions to wasm gc.
simolus3 commentedon Oct 22, 2026
Finalizers require callbacks, which requires a decision on when these callbacks run. The component model has a perfect primitive for this in the form of waitables, it doesn't seem like this can be added to core WebAssembly.
I have opened #752 to discuss that specifically, I'd love to hear your thoughts there!
fitzgen commentedon Nov 4, 2026
I had a conversation with @alexcrichton yesterday about
variants and CM+GC and the conclusion we came to is that this pre-proposal doesn't work for variants that havetupleandrecordpayloads (and probably not any other compound type either).The current "duck typing" allows producers and consumers to choose which GC struct to use for a
recordortuple(in particular, whichrecgroup it is defined in, whether it isfinalor not, and whether its fields aremutor not). And the way thatvariantis spec'd here, we can passvariants back and forth, but if you then want to downcast them to a particular arm of thevariant, then what type do you test for in your downcast? It is obvious for scalars and the rules work in that case, but for compound types you don't know whatrecgroup andmutfields the lowering chose, and there is currently no way to specify this from thecanon lower, which is only based on the core-type function signature.To show the problem concretely, let me modify the
variantexample from the OP:What should be in
???here?If we were passing a
$catdirectly as a parameter, we could use any of the following:But which one is actually chosen is fixed by the core signature given as
(core-type ...)in the(canon lower ...), for example:That is, we have the explicit chain
canon lower->core-type->sig'->$cat'''in this case. Lowering can always statically know that$cat'''is what is wanted here, and doesn't have to do any dynamic lookups or tests or anything like that.But for a
variant's payload, how does lowering know which version to allocate in order to pass it to the receiver? Because, unlike for when when the$catrecord is passed directly, the lowered version of$catdoes not appear in the(core-type ...):We have
canon lower->core-type->$sig'->$animal', but no connection from$animal'to a unique, unambiguous choice between$cat'/$cat''/$cat'''/$cat''''. We could go searching through all the module's defined types for something whose shape is right, but there might be many such types and we can't know which is actually right. Also, that search is happening at runtime when it is the host that is doing this lowering.I see two options to resolve this issue:
Stop doing the "duck typing" and just spec unique, canonical GC representations of CM types. This is straightforward, but does imply copies if the component needs to convert the types to its own representations (e.g. needs the data to be defined by a type in a particular
recgroup, or needs amutfield when the canonical representation specifies a non-mutfield or vice versa, or the data must be defined by a type with a particular supertype because everything must have that supertype in this guest language, etc...)Add a
(variant-arm $animal $cat $cat')canonical option that must be specified for everyvariantarm whose payload is a compound type that appears in the lowering's function signature. This allows the components to specify everything they want so they can avoid copies, but is very verbose. And it feels kind of gross to me.I guess I am leaning towards (1) because it is the simplest thing to do, unlocking CM+GC functionality, and then, as a next incremental step, I believe that lazy value lowering should hopefully allow lowerings into component-chosen core GC types. But I am interested in hearing if folks have ideas I missed, and what other people's opinions are.
alexcrichton commentedon Nov 4, 2026
If dropping "duck typing", that in theory matches linear memory languages a bit more closely too. The canonical ABI representation of types, structs, etc, rarely matches the idiomatic representation in source languages. In my mind the main things to get right are things like
stringandlist<u8>since those are so common you really want to try to get those to match most languages, which is somewhat the case for linear memory languages (but not all).If going the route of canonical types though it might make sense to do something canonical-ABI-ish where flattening comes into play more regularly. For example
record point { x: u32, y: u32 }as an argument would be passed asi32 i32in wasm instead of a(ref $struct). That would allow, in the "fast" case, languages to choose their source of representation more freely and not pay the cost of translation. Like with linear memory languageslist<point>would probably still incur a heavy translation cost as that would need to be represented as(array (ref $struct)). Basically though it might make sense to be more linear-memory-like in the ABI if there's one canonical type to reclaim some of the flexibility of representation while maintaining performance. The main difference is that where the canonical ABI today specifies an in-memory layout the GC ABI would specify some sort ofstructdefinition.fitzgen commentedon Nov 18, 2026
After working on the Wasmtime prototype some more, talking with @alexcrichton about the prototype/design, and talking with @bashor and @jmrtsh from the Kotlin-Wasm team about the design and what would work for their toolchain in practice, I've concluded that the original pre-proposal was flawed. It took on a bunch of complexity to be compatible with different
recgroup shapes, whether or not a field wasmutor not, whether a type isfinalor not, etc..., however that complexity didn't even pay off in practice because it wasn't flexible enough to allow for every object to have a hash code and vtable field, which every Kotlin object must have (as well as be a subtype of Kotlin's any struct that defines those fields). I know that Grain's branch with Wasm GC support has the same impedance mismatch, and probably many other Wasm GC toolchains as well. So we were paying for flexibility that wasn't good enough. Also, the original pre-proposal just didn't work forvariants.Therefore, I've updated the OP to define a canonical GC lowering for each component model type (one lowering for flat values in params/results, and another for lowering into storage types on the GC heap).
This brings the GC ABI more inline with the linear memory ABI now: e.g. passing a
tupleas a parameter also flattens its fields into core Wasm parameters up to a max-parameters limit.This is also much simpler: when a component model type lowers into a GC
structorarrayobject, there is exactly one such type ofstruct/arraythat it lowers into.This also guarantees zero copying at the ABI boundary: because there can't be a mismatch where one component wants a
structthat is in thisrecgroup while the other wants one that is in thatrecgroup, and because we can specify that the canonical lowered types are notmut, we can just pass objects across the ABI boundary without any copying.I've also made it so that$O(1)$ time, rather than an $O(n)$ chain of
variants can be exhaustively matched on inbr_on_casts/ref.tests, by adding a discriminator tag that lifting asserts isionly when this is theithcaseof thevariant, and which can therefore bebr_tabled upon.The Kotlin-Wasm folks were confident that they can target this new style of GC ABI with the same approach that they were thinking about for the original version of the GC ABI. Their ideas involved lazily allocating wrapper/reflector objects when upcasting a CM object into a Kotlin object. I won't speak for them and their project, but I did want to note here that there was positive feedback on the new design from the toolchain side of things, not just from the engine side of things.
Roughly, my plan moving forward is to:
wasm-toolsparsing/validation support for CM+GCkevmoo commentedon Nov 18, 2026
This is great to hear, @fitzgen
There are a few of us in the Dart world that would love to collaborate here (CC @simolus3)
Would love to chat with @bashor etc at https://bytecodealliance.zulipchat.com/#narrow/channel/394175-SIG-Guest-Languages/topic/WasmGC.20guest.20language.20collaboration/with/633089671 (or somewhere else) on how we can align and validate
sjrd commentedon Nov 19, 2026
This change generally looks good from my point of view as well (Scala toolchain).
One thing is problematic: immutable ref arrays are currently impossible to construct in core Wasm, if they don't have a compile-time known fixed size. I mean you can create one but only with default values. There is no way to create a variable length array at run-time with dynamic content, not even by copying from an existing mutable array.
So either we must add that capability to core Wasm very soon, or we must use mutable arrays in the ABI.
Edit: oh, I see now that you also added some external polyfill to do just that. OK, I guess that works too.
Another issue (not blocking but not great) is that it will require 2 full copies in the general case: one loop to fill a new mutable array with
lowering(element)from the language array. Then another full copy into an immutable array.sjrd commentedon Nov 19, 2026
A related but distinct issue is that it's not possible to create a variable-size array of
TwhereTis non defaultable. Even a mutable one. So you're still stuck trying to create your(array (mut (ref $elem)))even before having to turn it into an immutable copy.I mean, you could perform the following dance, but it's atrocious:
$first.(ref $elem): Allocate a new mutable array filled with$first, usingarray.newWe would need something like WebAssembly/more-array-constructors#1 to deal with that.