Different approach to JS prototypes: more efficient, less visible

[jakobkummerow]

I'd like to propose a slightly different approach for specifying JS prototypes: to fully lean into a custom section specified and interpreted by the JS embedding.

Compared to the earlier sketch that went in this direction, this approach does not leave any traces in the core Wasm world. In particular, there are no "weird" externref fields in special positions or with special types or values or annotations that then magically get copied somewhere and seem useless otherwise. In a non-Web embedding where the custom section gets ignored, the rest of the Wasm module looks and behaves exactly as it would if we didn't introduce this mechanism at all.

Full disclosure up front: this approach is not compliant with the restrictions currently described by the embedder spec. However, since (1) those rules were written long before WasmGC came to be (and hence long before wanting to expose Wasm structs to JS in idiomatic/convenient ways was on anyone's radar), and (2) the proposed mechanism doesn't burden or constrain core Wasm or other embeddings in any way (notably including: it doesn't stand in the way of any conceivable future additions to core Wasm), I think it would be fair game to relax those rules a little bit, to allow embedders to reflect Wasm structs on their side of the fence if and how the module requests it (via the custom section).

Compared to the approach currently under discussion in PR#19, the key benefit is improved efficiency. Wasm modules would need to spend a lot fewer bytes on imports and exports. At the same time, engines would have maximum freedom to explore various eagerness/laziness tradeoffs they find interesting; they are not required (but certainly allowed) to process the entire custom section during instantiation of the module. (To clarify, I don't know yet what would be a good tradeoff there, so allowing freedom in this regard isn't a veiled way of saying that I'd expect any particular engine to make use of this freedom in any particular way. I just think it's good when implementers have options to try different strategies, and also to change their strategies when new needs emerge; for example, leaning towards eagerness might be simpler initially, but if a new generation of larger modules gains popularity, then lazy strategies might become more desirable than they were before.)
Personally (and I realize that this is somewhat subjective), I also find the alternative proposed here to be simpler overall: nothing is magically added to or removed from the imports or exports of the module, there is no special time window where unpopulated prototypes are observable, there is no question whether DescriptorOptions need to be stored forever or can be discarded after use, there are no intermediate wrapper modules being generated on the fly.

The key idea is to do everything declaratively.

In its simplest form, that would mean that the custom section describes a JS prototype for each Wasm type. However, we have reason to believe that it will be very useful (or even strictly required) to have more than one prototype per Wasm type, in particular due to type minimization by optimizers, type canonicalization, and module merging, all of which could result in multiple unrelated surface-language types being represented by the same Wasm type and needing different JS prototypes. So we need a different "key" to describe where each prototype belongs.
It turns out that in practice, toolchains store vtables and similar type identifiers (i.e. in the future that this proposal envisions: custom descriptors) in Wasm globals. So we can embrace that as our vehicle.

The section will contain a list of entries like the following (here presented in JSON-like syntax for readability, exact encoding TBD):

[{
  "global_index": 123,
  "parent_prototype": 89,
  "methods": [
    {
      "name": "foo",
      "func_index": 45,
    }, …
  ],
}, …]

(There may be a few more things to specify, this is just a first draft to illustrate the most important parts.)

The behavior triggered by such an entry is, roughly:
If $global123 is an immutable global,
whose type is (ref $x) for some type $x that describes some other type $y,
and whose initializer ends with a struct.new[_default] $x instruction,
then when $global123 is initialized, then along with this struct a JS-side prototype P is allocated and associated with the RTT contained in this descriptor struct.

Note 1: The "association" between the descriptor struct's RTT and P is invisible to Wasm. In implementations, we expect that P will be stored in some hidden/internal field in the descriptor or the RTT (or those two might be the same internal object anyway). P is not directly accessible from Wasm. The reason is twofold: there is no need to access it because the concept of "prototype" has no meaning to Wasm, and it would be in conflict with the goal that the section can be ignored without any observable changes in behavior for core Wasm.
Note 2: The allocation and configuration of P is unobservable. That gives engines the freedom to defer this work until some event makes the presence of P potentially-observable (such as: a Wasm object crossing over the "boundary" to JS, or an actual attempt to access a Wasm struct's prototype, or the first allocation of a Wasm struct that uses the descriptor struct stored in $global123 – in fact, the entire initialization of $global123 could be deferred until $global123 is accessed for the first time).
Note 3: This bit is what violates the current embedder restrictions: we allow the embedder to observe initialization of a global, and perform a "mirror" of this action in the embedder world.

This JS prototype P is populated with methods according to the "methods" list. The function indices in this list refer to the module's list of functions. These functions do not need to be exported with the usual exports mechanism (but they may be; they may also be imported). P also gets the specified parent prototype, if present, as its prototype; it is identified by another global index ($global89 in the example). We should probably require that any parent prototype must have a lower index (which corresponds to Wasm supertypes needing to have a lower type index), to rule out cycles by construction.
As far as JavaScript is concerned, when a Wasm struct of type $y (i.e. having descriptor $x) enters the JS realm, it will have P as its prototype. The identity of the struct's prototype is immutable, i.e. the struct's prototype cannot be replaced; this is in line with Wasm structs generally appearing as "sealed" in JS. P itself is mutable, however, so additional methods can be installed on it, or its prototype chain can be modified, e.g. to inject a custom prototype that wasn't available to the declarative mechanism. The preinstalled methods' property attributes are: not writable, not enumerable, not configurable. (This is the conservative choice, we could change it if there is a need.) When JavaScript calls one of the methods that have been declaratively installed on P, the corresponding Wasm function is called, and the "receiver" (aka "this") is passed as the first parameter. Along with any additional parameters, it is subject to the usual ToWebAssemblyValue rules, just like all other calls of (exported) Wasm functions.

A fun observation is that the contents of the proposed section are actually not JS-specific at all (if you read "parent_prototype" simply as "parent", but that string is just a descriptive label and wouldn't show up in the wire bytes anyway). All it really describes is "when Wasm structs with this descriptor flow out to the embedder, then their 'class' (whatever that means for the respective embedder) should have the following methods". I think a hypothetical Wasm embedder in other GC'ed, OO-friendly, dynamic or reflection-supporting languages (Python, Java, ...) could probably also make good use of this section. But that's not an explicit design goal here, just a welcome side effect. However, if there is interest, we could use this observation as motivation for specifying the section as "embedder section" in core Wasm rather than in one or more embedders.

WDYT?

[sjrd]

Overall, this looks appealing. I do see two problems that would be very annoying to work around, though.

First, the slightly less problematic: we cannot get hold of the prototype of a given "class" without creating an instance of the corresponding struct first. If the struct has non-defaultable fields, doing so could be very tricky. That is pretty annoying if we want to imperatively register additional methods not supported by the declarative section.

The second problem might not have a workaround at all: this proposal ties prototype association to the existence of a global for the custom RTT value. That only works if there is a finite, known-at-compile-time amount of such RTT values. However, there are use cases for creating an arbitrary number of RTT values at run-time. The use case I have is the Java array types, whose vtables must know their component type (reified as vtables themselves). String[] must have a different vtable value than Object[] and than String[][]. By construction, these must be created on-demand at run-time, so they cannot be stored in immutable globals (or mutable globals either, for that matter). Yet I would want them to be associated with a prototype (if only to give them a toString() method), just like other classes.

Because of the second point, I don't think restricting RTTs who can have a prototype to those than are stored in globals is a viable alternative. It could be an MVP, but it would at least need a path forward to add that support, IMO.

[jakobkummerow]

@sjrd: Thanks for the feedback, those are good points.

I don't have a full answer yet. Part of the solution could be that every descriptor struct always gets an empty prototype object, and the section only specifies how that should be populated beyond its emptiness (if at all). Then you could always install additional things imperatively if you need to. But to do that, you'd still need to get to the prototypes somehow...

[sjrd]

Ah yes but then you have no opportunity to specify a parent prototype.

[jakobkummerow]

One way to avoid the dependency on globals would be to use module-relative wire bytes offsets to annotate the struct.new instructions that should allocate a prototype along with the descriptor struct; then these instructions could occur in both global initializers and function bodies. I find that somewhat less elegant (because offsets feel more brittle / harder to work with than global indices), but it would be strictly more powerful. We can also support both, either right away, or as the post-MVP extension plan.

Can you shed a bit more light on the use case for manually/imperatively putting additional methods onto the prototypes that the declarative system allocated? A better understanding of the context/details would help me brainstorm possible solutions for that.

[sjrd]

Can you shed a bit more light on the use case for manually/imperatively putting additional methods onto the prototypes that the declarative system allocated? A better understanding of the context/details would help me brainstorm possible solutions for that.

This is for JS method shapes that are not supported by the declarative encoding. Off the top of my head there is at least the case of JS ...rest params. In Scala.js if I have

class Foo {
  @JSExport
  def bar(x: Int, ys: Int*): Int = ???
}

then this should export a method looking like the following on the prototype associated with Foo:

bar(x, ...ys) {
  return wasmExports.Foo_bar(this, x, ys)
}

(yes, this passes ys directly as a JS Array into the Wasm exported method; it can handle it)

I haven't really dug further to see if we have anything else (other than varargs) that is not supported by the proposed declarative encoding.

These things are rare, but they exist. I would not want to switch an entire hierarchy to be entirely imperative just because there is one such method. I would like to be able to use the declarative approach for everything that can be handled declaratively, and only patch up imperatively the few methods that need it.

[jakobkummerow]

One pretty generic/powerful escape hatch would be if one of the expressible options in the custom section was "when this prototype is allocated, call imported function $configure_proto with it", i.e. (func $configure_proto (param externref) (import "...")) would be a callback that's invoked to do whatever it wants with the freshly allocated prototype. In particular, such a callback-based design would work in combination with the other concern that statically-unknown numbers of descriptors might need to be allocated anywhere in the module, not just in global initializers. It would go somewhat against the goal of not leaving traces in the module that don't make sense outside a JS embedding; OTOH if it's needed rarely enough it's probably fine, and also most modules built for the web will probably import browser-specific stuff (which doesn't make sense outside a JS embedding) anyway. But perhaps it's too much magic, because it would mean that $configure_proto has (only) "invisible" callers.

So, perhaps a more palatable version of that idea would be an external function WebAssembly.configurePrototype(descriptor, callback), which takes a descriptor struct and a JS callback, fetches the descriptor's associated prototype, and passes it as a parameter to the callback. To use it, the Wasm module would still import a function (func $decorate_descriptor (param anyref)), but contrary to the earlier iteration it would explicitly call it with the just-allocated descriptor struct (without the custom section triggering this). That'd mean it doesn't work directly from a global initializer, but the start function could take care of it. (And, of course, the idea would be that only very few descriptors need imperative patching-up, so that there's not much of a performance concern about doing that eagerly.)

For ...rest parameters, that could perhaps also be one of the patterns you can declaratively request, so it wouldn't need imperative workarounds. I'm still hoping that the declarative mechanism can get by without actually materializing all these one-liner wrapper functions, and instead just configure the engine-internal glue (which needs to happen anyway to bridge between the JS and Wasm worlds) as needed. But I haven't started prototyping these bits yet so I don't know whether that hope will pan out.

Also, as a general thought: I think the task at hand is to strike a good balance between expressiveness and efficiency. We need to support enough cases to be useful, and leave viable workarounds (and/or open doors to future enhancements) for the others. We don't necessarily need to support everything. (By which I'm not arguing for or against any specific feature right now -- I'm still interested in collecting concerns, ideas, use cases and prototyping them; we can decide what needs to make it into the spec afterwards.)

[jakobkummerow]

Getting back to this, I think a function WebAssembly.configurePrototype(descriptor, callback) could be a good solution for addressing both problems that @sjrd raised upthread. Its behavior would be:

• first parameter must be a Wasm struct having some descriptor type, otherwise TypeError
• second parameter must be a function, otherwise TypeError
• when invoked, configurePrototype(D, C) will:
  • fetch D's associated prototype, if it has one (created by an entry in the custom section)
  • otherwise (if D does not have an associated prototype yet) create an empty JS object to use as prototype and associate it with D.
  • either way then call C, passing this prototype as the first argument. C can be a closure (or access global variables or whatever) to retrieve exported functions from the Wasm instance.

That addresses problem (1): to perform additional customization of an existing prototype, you don't need to allocate an exemplar object that uses the custom descriptor, you can simply pass the descriptor itself to an imported function, which in turn passes it to WA.configurePrototype. (Or WA.configurePrototype could potentially even be that imported function.)
And it addresses problem (2): to install a prototype on a custom descriptor that's not in a global (but instead allocated in some arbitrary Wasm function), you can also just pass it to an imported function that performs the required setup.

How does that sound?

Of course we can tweak the idea, if you like the core concept but not the details. For example, instead of this super-generic callback-driven tool, it could be an actual imperative equivalent of the custom section entry, such as WebAssembly.installPrototypeMethod(descriptor, method_name, kind, func), where kind is some encoding of method|getter|setter and func is whatever JS or Wasm function you want to install there, such as the (x, ...ys) example above. Would that be better or worse?

While having to call things manually and configure stuff imperatively is generally a pattern I'd like to avoid for performance reasons, I think the performance considerations mostly apply to (1) the majority use case and (2) things happening on the blocking path of application startup (i.e. Wasm instantiation). For somewhat-rare special cases, a manual/imperative escape hatch seems fine to me. More technically speaking, outside of global initializers we don't have the constraint that calling imports is not an option.

An alternative considered before was to have a second kind of entry in the custom section that uses wire byte offsets of struct.new[_default] instructions rather than global indices. It would address problem (2) but not (1). It might be slightly more efficient, it might also be somewhat more cumbersome to use. Would you prefer that?

[sjrd]

I'm not an engine implementor, but I would be surprise if they'd be happy to change the prototype of a descriptor after it has had a chance to be used in at least one instance.

Regardless, I think there remains a major blocker here: it's not possible to have run-time created descriptor with a prototype that extends another prototype. Since the only way to create it is to "create an empty JS object to use as prototype and associate it with D", which does not give the opportunity to specify a parent prototype. (and changing the prototype after is definitely a performance problem for engines)

[jakobkummerow]

Changing the prototype is indeed a no-go; creating it might be acceptable, but I agree that there's some nuance. We may have to couple this with saying "an empty prototype is always created for custom descriptors".

Prototype extensions are possible at any time using Object.setPrototypeOf, so I don't think there's a blocker there. We could make this more convenient with a WebAssembly.retrievePrototype(descriptor) function. Or just make that function be the function that everything else is built on.

[sjrd]

Prototype extensions are possible at any time using Object.setPrototypeOf, so I don't think there's a blocker there.

It's semantically possible, but using setPrototypeOf tends to create performance cliffs in JS engines. See the discussion starting here:
#2 (comment)
If you want your program to be performant, setPrototypeOf is on the short list of things you don't do. ;)

[jakobkummerow]

For setting up a new prototype, using setPrototypeOf is totally fine. The performance cliffs happen when already-initialized inline caches need to be reset, and similar situations of running hot code and then modifying relevant prototype chains. But for a fresh object that most of your code hasn't encountered yet, it doesn't really matter how you assign its prototype.