Skip to content

Pre-Proposal: Wasm GC Support in the Canonical ABI #525

Open

Description

@fitzgen

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

New Canonical Definitions

  • (canon array.new_array dst src) : [(ref null src) i32 i32] -> [(ref dst)]:
    polyfill for the array.new_array instruction 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))
  • (canon array.new_memory dst src) : [i32 i32] -> [(ref dst)]:
    polyfill for the array.new_memory instruction 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))
  • (canon array.new_table dst src) : [i32 i32] -> [(ref dst)]:
    polyfill for the array.new_array instruction 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))

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 (ref array) is always a subtype of either (ref $latin1) or (ref $utf16); otherwise traps.

(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 D = discriminant_type(cases) and T' = gc_heap_storage_type(T).

Lifting enforces that the i32 discriminant field is in the range 0 <= i < len(cases) and that when the field is i then the struct is a subtype of $case-<i>; otherwise traps.

(list T) (ref $list) (same)
(rec (type $list (array T')))

Where T' = gc_heap_storage_type(T).

(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 variant.

(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 variant.

(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:

  1. A $base struct type, that is not final, with a single discriminant field of type discriminant_type(cases) that is not mut.
  2. For each case, a struct type that is final, is a subtype of the base (1) type, contains the discriminant field, and then contains a non-mut field which is the case'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 $O(1)$ dispatch on variant cases, instead of $O(n)$ 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

  1. Object. Haha -- get it?? Like GC objects. GET IT!? HAHA WHY AREN'T YOU LAUGHING?!?!?!?!? ↩

Activity

  1. fitzgen commented on Jun 3, 2025

    @fitzgen
    CollaboratorAuthor
  2. fitzgen commented on Jun 3, 2025

    @fitzgen
    CollaboratorAuthor

    Realization: we could actually remove the discriminants from sum types if we prescribe that the cases are all defined in the same rec group.

    I'll prototype this and update the OP once it is working in wasm-tools.

  3. added a commit that references this issue on Jun 3, 2025
  4. fitzgen commented on Jun 3, 2025

    @fitzgen
    CollaboratorAuthor

    I'll prototype this and update the OP once it is working in wasm-tools.

    Done and done

  5. lukewagner commented on Jun 4, 2025

    @lukewagner
    Member

    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:

    1. I'm probably misunderstanding the proposal, wasm-gc or both, but: for variant et 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 a struct type that is the first of its rec group and all the subsequent rec group members must be its cases; then the typeidx used in the core function type points to a rec group that points to the cases.

    2. While you're right about the reason that option can't represent none with ref.null in general, could we say that, when option<T> has a non-null-allowing T, ref.null represents none? This is ad hoc and irregular, but we are licensed to do that in the CABI when it's a significant win and option is very common and I expect this optimization would to 95% of options in practice.

    3. result<T> (no E) and result (no T) are also super common and I think perhaps worth optimizing. Could the former use null for error and the latter return a (boolean) i32 (making it no less efficient than enum, so that no one has the perverse incentive to use an enum for a result for perf reasons)?

  6. lukewagner commented on Jun 5, 2025

    @lukewagner
    Member

    Two more follow-up thoughts:

    1. For the latin1+utf16 string-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 an i32 when 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)).
    2. Regarding own, borrow, future and stream (as well as waitable sets and async subtasks): one issue I just realized is that various drop built-ins trap under various conditions (own and borrow trap if there are any extant async import calls to which they were lent; the writable end of a future traps 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 root externrefs 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-via FinalizationRegistry and 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).
  7. rossberg commented on Jun 6, 2025

    @rossberg
    Member

    A few drive-by comments:

    1. The even bigger reason that there are no canonical choices of type definitions to lower to are subtyping declarations, which the comment layer cannot guess.
    2. For the various small scalar types, a common target representation will be i31-ref (e.g., in any language with a uniform representation), so I think (i31 null? ref) should also be allowed as an alternative, for both value and/or storage type.
    3. For larger numeric types, various languages will probably need boxed representations to be able to process them, so perhaps it should be possible to map to those as well.
    4. I like @lukewagner's suggestion regarding variants.
    5. It is rather unfortunate that the CM calls arrays "lists"...

    @lukewagner:

    1. While you're right about the reason that option can't represent none with ref.null in general, could we say that, when option<T> has a non-null-allowing T, ref.null represents none? This is ad hoc and irregular, but we are licensed to do that in the CABI when it's a significant win and option is very common and I expect this optimization would to 95% of options in practice.

    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.

  8. lukewagner commented on Jun 6, 2025

    @lukewagner
    Member

    @rossberg

    While you're right about the reason that option can't represent none with ref.null in general, could we say that, when option has a non-null-allowing T, ref.null represents none? This is ad hoc and irregular, but we are licensed to do that in the CABI when it's a significant win and option is very common and I expect this optimization would to 95% of options in practice.

    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.

    Ah, interesting point. When I said "95%", I was talking about the percent of options appearing in WIT interfaces, but also thinking about how options are represented "at rest" in various languages is a good for regularity.

    Question: if a lowered function type lowers an option into a non-eq reference with an empty struct representing none, can the engine implement none with a single-per-type allocation (since the identity isn't observable via eq or mutation)? If so, then the null optimization wouldn't even be that big of a win.

  9. rossberg commented on Jun 6, 2025

    @rossberg
    Member

    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.

  10. gertvv commented on Jun 9, 2025

    @gertvv

    This is awesome! As an outsider, the wording on variant types is confusing:

    Component variant types are matched against a reference to a struct type with no fields.

    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?

  11. fitzgen commented on Jun 13, 2025

    @fitzgen
    CollaboratorAuthor

    This is awesome! As an outsider, the wording on variant types is confusing:

    Component variant types are matched against a reference to a struct type with no fields.

    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?

    Ah I just forgot to update the example. There shouldn't be any (field i32) there. Will update the OP shortly.

  12. fitzgen commented on Jun 13, 2025

    @fitzgen
    CollaboratorAuthor

    @lukewagner

    1. I'm probably misunderstanding the proposal, wasm-gc or both, but: for variant et 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 a struct type that is the first of its rec group and all the subsequent rec group members must be its cases; then the typeidx used in the core function type points to a rec group that points to the cases.

    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.

    2. While you're right about the reason that option can't represent none with ref.null in general, could we say that, when option<T> has a non-null-allowing T, ref.null represents none? This is ad hoc and irregular, but we are licensed to do that in the CABI when it's a significant win and option is very common and I expect this optimization would to 95% of options in practice.

    3. result<T> (no E) and result (no T) are also super common and I think perhaps worth optimizing. Could the former use null for error and the latter return a (boolean) i32 (making it no less efficient than enum, so that no one has the perverse incentive to use an enum for a result for perf reasons)?

    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.

    For the latin1+utf16 string-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 an i32 when 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)).

    Yeah, this makes sense and the OP reflects a misunderstanding on my part. Will update as soon as I fix my prototype.

    Regarding own, borrow, future and stream (as well as waitable sets and async subtasks): one issue I just realized is that various drop built-ins trap under various conditions (own and borrow trap if there are any extant async import calls to which they were lent; the writable end of a future traps 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 root externrefs 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-via FinalizationRegistry and 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).

    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 externref becomes 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 its with construct).

    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.

  13. fitzgen commented on Jun 13, 2025

    @fitzgen
    CollaboratorAuthor

    @rossberg

    • For the various small scalar types, a common target representation will be i31-ref (e.g., in any language with a uniform representation), so I think (i31 null? ref) should also be allowed as an alternative, for both value and/or storage type.

    • For larger numeric types, various languages will probably need boxed representations to be able to process them, so perhaps it should be possible to map to those as well.

    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 i31ref in 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. 14 remaining items

  15. justinfagnani commented on Apr 22, 2026

    @justinfagnani

    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.

  16. spotandjake commented on Apr 22, 2026

    @spotandjake

    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.

    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.

  17. justinfagnani commented on Apr 23, 2026

    @justinfagnani

    @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.

  18. kevmoo commented on Apr 23, 2026

    @kevmoo

    What @justinfagnani said! (Hi, @justinfagnani 👋 )

  19. simolus3 commented on Oct 18, 2026

    @simolus3

    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 a Uint8List, which is likely implemented with a backing (array i8) + offset + length. Being able to pass this without copying again would be nice.

  20. lukewagner commented on Oct 21, 2026

    @lukewagner
    Member

    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.

  21. justinfagnani commented on Oct 22, 2026

    @justinfagnani

    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.

  22. spotandjake commented on Oct 22, 2026

    @spotandjake

    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.

    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.

  23. simolus3 commented on Oct 22, 2026

    @simolus3

    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!

  24. fitzgen commented on Nov 4, 2026

    @fitzgen
    CollaboratorAuthor

    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 have tuple and record payloads (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 record or tuple (in particular, which rec group it is defined in, whether it is final or not, and whether its fields are mut or not). And the way that variant is spec'd here, we can pass variants back and forth, but if you then want to downcast them to a particular arm of the variant, 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 what rec group and mut fields the lowering chose, and there is currently no way to specify this from the canon lower, which is only based on the core-type function signature.

    To show the problem concretely, let me modify the variant example from the OP:

    ;; Component model types and function signature.
    
    (type $cat (record (field "lives" u8))
    (type $animal
      (variant
        (case $cat "cat" $cat)
        (case $dog "dog" u16))
    
    (type $sig (func (param "animal" $animal)))
    
    ;; A valid core lowering of that component type and function signature.
    
    ;; The supertype for all arms of the `variant`.
    (core type $animal' (sub (struct)))
    
    ;; The variant arm types.
    (core rec
      (type $cat' (sub $animal' (struct (field ???))))
      (type $dog' (sub $animal' (struct (field (mut i16))))))
    
    ;; The function signature.
    (core type $sig' (param (ref $animal')))
    
    ;; The lowered function.
    (core func $l (canon lower (func ...) gc (core-type $sig')))

    What should be in ??? here?

    If we were passing a $cat directly as a parameter, we could use any of the following:

    (type $cat' (sub (struct (field i8))))
    (type $cat'' (sub final (struct (field i8))))
    (type $cat''' (sub (struct (field (mut i8)))))
    (rec (type $whatever (struct))
         (type $cat'''' (sub (struct (field i8)))))

    But which one is actually chosen is fixed by the core signature given as (core-type ...) in the (canon lower ...), for example:

    (core type $sig' (func (param (ref $cat''')))
    (core func $l (canon lower (func ...) gc (core-type $sig')))

    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 $cat record is passed directly, the lowered version of $cat does not appear in the (core-type ...):

    (core type $sig' (param (ref $animal')))
    ;; ...
    (core func $l (canon lower (func ...) gc (core-type $sig')))

    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:

    1. 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 rec group, or needs a mut field when the canonical representation specifies a non-mut field 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...)

    2. Add a (variant-arm $animal $cat $cat') canonical option that must be specified for every variant arm 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.

  25. alexcrichton commented on Nov 4, 2026

    @alexcrichton
    Collaborator

    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 string and list<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 as i32 i32 in 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 languages list<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 of struct definition.

  26. fitzgen commented on Nov 18, 2026

    @fitzgen
    CollaboratorAuthor

    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 rec group shapes, whether or not a field was mut or not, whether a type is final or 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 for variants.

    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 tuple as 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 struct or array object, there is exactly one such type of struct/array that it lowers into.

    This also guarantees zero copying at the ABI boundary: because there can't be a mismatch where one component wants a struct that is in this rec group while the other wants one that is in that rec group, and because we can specify that the canonical lowered types are not mut, we can just pass objects across the ABI boundary without any copying.

    I've also made it so that variants can be exhaustively matched on in $O(1)$ time, rather than an $O(n)$ chain of br_on_casts/ref.tests, by adding a discriminator tag that lifting asserts is i only when this is the ith case of the variant, and which can therefore be br_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:

    • Update the wasm-tools parsing/validation support for CM+GC
    • Continue implementing a prototype in Wasmtime
    • Make a proper PR to this repo that can have multiple commits and git history and such, rather than just be a big issue comment thread, and can fit into the actual canonical ABI definition
  27. kevmoo commented on Nov 18, 2026

    @kevmoo

    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

  28. sjrd commented on Nov 19, 2026

    @sjrd

    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.

  29. sjrd commented on Nov 19, 2026

    @sjrd

    A related but distinct issue is that it's not possible to create a variable-size array of T where T is 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:

    1. Test if the language array is empty. If yes, return a new empty immutable array.
    2. Convert the first element if the language array into its ABI lowering $first.
    3. Now that you have one (ref $elem): Allocate a new mutable array filled with $first, using array.new
    4. Loop to convert all the other elements of the language array into lowered elements, and store them in that mutable array.
    5. Finally copy the whole thing into an immutable array.

    We would need something like WebAssembly/more-array-constructors#1 to deal with that.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions