Extending descriptor struct types to have host fields

[eqrion]

The explainer describes a method for customizing the JS behavior of a descriptor struct using a 'designated value' where when the first field is an immutable externref, the JS-API would dynamically inspect it to see if it's a WebAssembly.DescriptorOptions value and if so it would customize the behavior of the descriptor.

This works, but it has some downsides:

1. Runtimes do not know statically if the first field will be the DO or not. This requires a dynamic check during allocation and separate behavior for both cases.
2. Codegen also cannot assume that this field has any special layout or meaning and so we're stuck with duplicating the contents of the DO into the rest of the rtt/map/shape. The DO is also effectively dead after allocation but we are forced to keep it around.
3. Misuse of this API results in a failures far away from the problem that caused it. If a user accidentally fails to use a DO, no error can happen when creating the descriptor, and instead the object will just act wrong later in weird ways. It'd be really nice if they could get an immediate error in this case.

I don't think these issues are necessarily hard blocks, but enough of a smell that I'd like to propose a tweak that would solve these problems.

What if we tweaked the type definition of descriptor struct types so that it could specify a prefix of the fields as being for the 'host'?

e.g.

(type $foo.rtt (describes $foo (struct (host-fields N) (field ...))))

or with some syntax sugar:

(type $foo.rtt (describes $foo (struct (host field ...) (field ...))))

Host fields act the same as regular fields, and can only exist on descriptors. The key difference is that when you allocate a descriptor, the N host fields are passed to a host hook which can perform validation of the host fields and possibly fail.

This would let hosts, like the JS-API, give special meaning to some of the fields on a descriptor struct without worrying about accidentally capturing normal fields. So we could define the convention that the first host field is always the prototype object, and later add additional host fields. We would not necessarily need the DO object anymore.

The host hook would let runtimes eagerly validate the fields and fail if e.g. the prototype is not an object. This (plus the static addition to the type) would enable us to put the host fields in different parts of the rtt/map/shape. Doing a struct.get of a the first host field would know that the prototype is always stored in a different slot than normal.

I think the best way to rationalize this addition is that descriptor structs are exactly the same as engine rtt/map/shape objects, which already have fields for things like prototypes. The very small addition we need to core wasm is just a way to statically describe a struct field as being one of the fields.

cc @lukewagner @tlively @jakobkummerow @rossberg

[tlively]

I agree with all the downsides you identified, and I'd add the downside that we need either DescriptorOptions or the possibility of accidental prototype capture as well. It's nice that this proposed change obviates DescriptorOptions.

I'm not convinced these downsides merit an addition to the spec, though:

1. Descriptor allocation should be uncommon.
2. There shouldn't be too many DOs and they are small (if we have them at all, see next point).
3. Accidental capture and misuse would typically be toolchain bugs, not end developer bugs, so I don't think we need as many guardrails to prevent them.

If we do decide that some solution is merited here, I like the host-field idea. It seems non-intrusive and easy to implement in the type system. I'm more worried about the precedent it would set with host hooks controlling behavior. Right now a Wasm embedder only interacts with Wasm modules via imports and exports, which are modular and virtualizable, and adding hooks would complicate that story.

But maybe we can get away without specifying host hooks: there's enough wiggle room in the specification of implementer limits on the number of allocated WasmGC objects to allow an implementer to fail to allocate at any time and for any reason. Perhaps we can specify in the JS API that allocation of descriptor type always fails if an invalid prototype is found in the prototype field. This idea could be adopted whether or not we adopt host-fields. The only downside I see is that we would have to report the error by trapping rather than by throwing a more informative exception. (and also it's kind of gross, but I will reiterate that I question whether we need to guard against misuse in the first place.)

[rossberg]

I agree with @tlively's arguments why the benefit seems small to justify a core addition. And I do think that this addition would raise various follow-up questions, like: are host fields accessible from Wasm, what are their subtyping rules, what are their type constraints, can they be recursive? The answers to these questions will bleed into different parts of the language semantics and further complicate something already complicated. And what do they mean for non-JS engines, do those now have to implement some extra mechanism in their representation that makes zero sense for them? Realistically, this still is a pure JSism leaking into Wasm.

[eqrion]

I'm not convinced these downsides merit an addition to the spec, though:

1. Descriptor allocation should be uncommon.

2. There shouldn't be too many DOs and they are small (if we have them at all, see next point).

3. Accidental capture and misuse would typically be toolchain bugs, not end developer bugs, so I don't think we need as many guardrails to prevent them.

I agree that these downsides are probably not hard blockers for the reasons you say. But they do indicate the design could be improved, and I don't see why we shouldn't consider changes to the core spec to express the actual intent we're going for (especially when this proposal already is adding a ton tricky things to the core spec type system). Having a magic field that is dynamically used or not depending on the type of value stored works, but we really just want this to be a proper field or parameter that programs opt into using.

If we do decide that some solution is merited here, I like the host-field idea. It seems non-intrusive and easy to implement in the type system. I'm more worried about the precedent it would set with host hooks controlling behavior. Right now a Wasm embedder only interacts with Wasm modules via imports and exports, which are modular and virtualizable, and adding hooks would complicate that story.

I agree, this is the part I'd be most uncomfortable with. I think we could find a justification around it, but I actually had a different idea that avoids the host hook and may be more palatable.

If we had type imports, could we combine it with compile time builtins to allow modules to import a special base struct descriptor that has the fields we care about setting?

e.g.

(module
   (type $jsObject
      (import "wasm:js" "object")
      (sub extern)
   )
   (type $jsDescriptor
      (import "wasm:js" "descriptor")
      (sub
         (struct
            (describes structref (; abstract describes is needed so myDescriptor can be a subtype of this. only allowed on imported descriptors ;))
            (field $proto $jsObject)
         )
      )
   )
   (type $myDescriptor
      (sub $jsDescriptor
         (struct (describes ...) (field $proto $jsObject) (field ...)
      )
   )
)

Because these types are known at compile time, we could give them a special representation from normal structs and meaning. And we could precisely type the proto field to be JS object.

Type imports is a large addition, but it does have potential independent uses like typing JS objects and strings better. So I think it could easily pay for itself.

[tlively]

@rossberg, I'm assuming a host field would behave identically to a normal field as far as core Wasm is concerned. If so, this is a really simple addition of a single bit to the field syntax with no further ramifications in the type system. The only problem is that the bit cannot be assigned meaning without introducing host hooks, which we'd like to avoid.

@eqrion, I don't think there's any way to make declaring a subtype of an imported type safe, at least in the current design where type imports only have upper bounds. The actual type provided at instantiation time might already have extra fields not present in the import upper bounds, for example, so the compiler has no way of knowing what offsets new fields should be placed at.

Type imports could alternatively be used in place DOs to prevent accidental prototype capture, but I don't think the problem is serious enough to merit taking a dependence on type imports, either.

[rossberg]

@tlively:

If so, this is a really simple addition of a single bit to the field syntax with no further ramifications in the type system.

Hm, I would be surprised if we could get away without at least some restrictions on subtyping. For example, that a subtype cannot add a host field, or something along these lines. Also, can host fields be mutable? If so, what does that imply for JS implementations? Can they have a type other than externref? The problem that code could set a prototype field to something else than a JS object also isn't magically solved by the host field declaration, I believe. There are a number of unknowns, and it would seem hard to avoid ending up with ad-hoc design decisions that only match JavaScript.

[lukewagner]

This seems like a nice compromise and useful for other language runtimes (esp. dynamic languages) for language-specific metadata used to control how wasm-gc objects are projected into that language.

[eqrion]

@tlively

@eqrion, I don't think there's any way to make declaring a subtype of an imported type safe, at least in the current design where type imports only have upper bounds. The actual type provided at instantiation time might already have extra fields not present in the import upper bounds, for example, so the compiler has no way of knowing what offsets new fields should be placed at.

Ah, yeah you're right, that's an unfortunate limitation of type imports. I would hope though there is some way we could support a 'import a struct type that I can extend'. That seems like a fairly common concept in languages and would be a significant limitation if we could never support that.

@rossberg

Hm, I would be surprised if we could get away without at least some restrictions on subtyping. For example, that a subtype cannot add a host field, or something along these lines. Also, can host fields be mutable? If so, what does that imply for JS implementations? Can they have a type other than externref?

To be conservative you'd probably require that subtypes have exactly the same number of host fields.

As for the other questions, those are up to the host hook to validate. JS would require a single immutable externref (at least for now, until more configuration points are added). But Python could choose to have two mutable fields of whatever type if it wanted to.

The problem that code could set a prototype field to something else than a JS object also isn't magically solved by the host field declaration, I believe.

Having the field be immutable and having a host hook on initialization that can trap would let JS runtimes validate the prototype externref is an object.

There are a number of unknowns, and it would seem hard to avoid ending up with ad-hoc design decisions that only match JavaScript.

The JS specific design decisions here are really confined just to the host hook. There'd be very little in core wasm to this proposal except for the number of struct fields that are to be checked by the host, and the struct allocation hook that could trap.

[rossberg]

@lukewagner:

This seems like a nice compromise and useful for other language runtimes (esp. dynamic languages) for language-specific metadata used to control how wasm-gc objects are projected into that language.

Do we have any evidence for that? The amount of "seamless" integration that JS folks expect for an embedded language/VM is super unique, as far as I can tell. I wouldn't know anything comparable having happened elsewhere, so I fail imagining another host taking advantage of it. The fact alone that it only makes sense if both languages share a GC (or are very tightly integrated) makes it esoteric. I don't see how that could work for, say, a Python host and a run-of-the-mill Wasm embedding. You effectively need both implemented in a single runtime.

[eqrion]

The fact alone that it only makes sense if both languages share a GC (or are very tightly integrated) makes it esoteric. I don't see how that could work for, say, a Python host and a run-of-the-mill Wasm embedding. You effectively need both implemented in a single runtime

By far the biggest reason to use Wasm-GC is to share the host-GC so that cycles are collected. If we had a viable alternative solution to that issue, I don't think I would have supported the proposal. I was not really convinced of any code-size/performance arguments for using the host GC compared to languages being able to bring GCs optimized for their own languages invariants.

So I don't think it makes sense to call this use-case esoteric, this kind of shared-heap interop is the whole reason we added wasm-GC and added a ton of complexity to the language.

[rossberg]

@eqrion:

this kind of shared-heap interop is the whole reason we added wasm-GC and added a ton of complexity to the language.

That is not true. The primary reason for Wasm GC was more effective support for compiling high-level languages (while host heap integration was already enabled by externref). It was a game changer for a whole range of languages who were long waiting for this to happen and which we are now finally seeing targeting Wasm. And AFAICT, not all of them do particularly care about super-integrated JS interop for exported GC objects — especially when they are not only interested in the web.

[eqrion]

@rossberg Externref only allowed source languages to hold host references, it did not allow host objects to reference source language objects and have any cycles be collected. That's what I meant by having a shared-heap, which is what you referred to as 'esoteric'. It was the primary new capability added to the language that was not able to be emulated before (along with stack scanning) [1]. The performance/code size stuff is debatable and is just an optimization, not a new capability.

Not all VM's will use a shared heap, I'm sure some will just want to embed wasm as an isolated thing and will use wasm-GC because it already exists. But VM's with a shared heap are the critical and motivating use-case here. Yes, JS engines are the only ones with that right now, but that's primarily because they are on the bleeding edge.

[1] https://v8.dev/blog/wasm-gc-porting#cycle-collection

And AFAICT, not all of them do particularly care about super-integrated JS interop for exported GC objects — especially when they are not only interested in the web

I agree, this feature is not for everyone. However, it's a very natural extension once host code can hold references to wasm GC objects to want to read/write to them as some form of host objects. I think it's well in scope to find a minimal host extension to allow host's to express what they need here.

[rossberg]

The performance/code size stuff is debatable and is just an optimization, not a new capability.

While perhaps true in a purely technical sense, I think you are vastly underestimating practical and political factors, as well as the optimisation benefit. As the champion of the GC proposal, I can say with certainty that those were the driving factor, not JS interop.

Not all VM's will use a shared heap

We don't have any evidence that any will, besides web JS engines. And even less evidence that, should they get built one day, they will be interested in the same level of interop, and let alone that the proposed design matches their needs equally well. All of these are hypotheticals.

[tlively]

I'm happy to stipulate here that there will eventually be more embeddings that share their GC heaps with Wasm. If they want to efficiently support host/Wasm cycles, they will have to, as @eqrion has been saying. And we have heard from toolchains that in the Web embedding, these cycles will be important. I would be surprised if that property turns out to be specific to the Web.

But even then, I would like to have a clearer picture of how host fields would be useful for host languages other than JS.

[eqrion]

While perhaps true in a purely technical sense, I think you are vastly underestimating practical and political factors, as well as the optimisation benefit. As the champion of the GC proposal, I can say with certainty that those were the driving factor, not JS interop.

I'm not sure what you are referring to by practical and political factors. As the representative of a web engine, I can say that if it weren't for the host/guest cycle collection problem I wouldn't have supported the GC proposal. It makes a lot of difficult compromises that are only worth it if you really need to share the host's heap.

We don't have any evidence that any will, besides web JS engines. And even less evidence that, should they get built one day, they will be interested in the same level of interop, and let alone that the proposed design matches their needs equally well. All of these are hypotheticals.

Again, I'd flip this around and say that we only have Wasm-GC because of web JS engines needing a shared host/guest heap for guest managed languages to work well. So I don't think it's fair to then say that JS engines cannot motivate extensions to Wasm-GC because shared heaps are esoteric.

I think this debate would also be different if we were considering a very large addition to support associating host type information with wasm descriptors. But here we're talking about fairly trivial additions (from this idea and other ideas thrown around on this repo) that can be ignored by other hosts. Especially when this proposal is already introducing a complicated system of nest-able user defined type descriptors, that I'm not confident we fully understand all the implications of.