Debian Codegraph @

.cargo/vendor/wasm-bindgen/guide/src/reference/attributes/on-js-imports/final.md

raw
1 # `final`
2
3 The `final` attribute is the converse of the [`structural`
4 attribute](structural.html). It configures how `wasm-bindgen` will generate JS
5 imports to call the imported function. Notably a function imported by `final`
6 never changes after it was imported, whereas a function imported by default (or
7 with `structural`) is subject to runtime lookup rules such as walking the
8 prototype chain of an object. Note that `final` is not suitable for accessing
9 data descriptor properties of JS objects; to accomplish this, use the `structural`
10 attribute.
11
12 [component-model]: https://github.com/WebAssembly/component-model
13 [reference-types]: https://github.com/WebAssembly/reference-types
14
15 The `final` attribute is intended to be purely related to performance. It
16 ideally has no user-visible effect, and `structural` imports (the default)
17 should be able to transparently switch to `final` eventually.
18
19 The eventual performance aspect is that with the [component model
20 proposal][component-model] then `wasm-bindgen` will need to generate far fewer JS
21 function shims to import than it does today. For example, consider this import
22 today:
23
24 ```rust
25 #[wasm_bindgen]
26 extern "C" {
27 type Foo;
28 #[wasm_bindgen(method)]
29 fn bar(this: &Foo, argument: &str) -> JsValue;
30 }
31 ```
32
33 **Without the `final` attribute** the generated JS looks like this:
34
35 ```js
36 // without `final`
37 export function __wbg_bar_a81456386e6b526f(arg0, arg1, arg2) {
38 let varg1 = getStringFromWasm(arg1, arg2);
39 return addHeapObject(getObject(arg0).bar(varg1));
40 }
41 ```
42
43 We can see here that this JS function shim is required, but it's all relatively
44 self-contained. It does, however, execute the `bar` method in a duck-type-y
45 fashion in the sense that it never validates `getObject(arg0)` is of type `Foo`
46 to actually call the `Foo.prototype.bar` method.
47
48 If we instead, however, write this:
49
50 ```rust
51 #[wasm_bindgen]
52 extern "C" {
53 type Foo;
54 #[wasm_bindgen(method, final)] // note the change here
55 fn bar(this: &Foo, argument: &str) -> JsValue;
56 }
57 ```
58
59 it generates this JS glue (roughly):
60
61 ```js
62 const __wbg_bar_target = Foo.prototype.bar;
63
64 export function __wbg_bar_a81456386e6b526f(arg0, arg1, arg2) {
65 let varg1 = getStringFromWasm(arg1, arg2);
66 return addHeapObject(__wbg_bar_target.call(getObject(arg0), varg1));
67 }
68 ```
69
70 The difference here is pretty subtle, but we can see how the function being
71 called is hoisted out of the generated shim and is bound to always be
72 `Foo.prototype.bar`. This then uses the `Function.call` method to invoke that
73 function with `getObject(arg0)` as the receiver.
74
75 But wait, there's still a JS function shim here even with `final`! That's true,
76 and this is simply a fact of future WebAssembly proposals not being implemented
77 yet. The semantics, though, match the future [component model
78 proposal][component-model] because the method being called is determined exactly
79 once, and it's located on the prototype chain rather than being resolved at
80 runtime when the function is called.
81
82 ## Interaction with future proposals
83
84 If you're curious to see how our JS function shim will be eliminated entirely,
85 let's take a look at the generated bindings. We're starting off with this:
86
87 ```js
88 const __wbg_bar_target = Foo.prototype.bar;
89
90 export function __wbg_bar_a81456386e6b526f(arg0, arg1, arg2) {
91 let varg1 = getStringFromWasm(arg1, arg2);
92 return addHeapObject(__wbg_bar_target.call(getObject(arg0), varg1));
93 }
94 ```
95
96 ... and once the [reference types proposal][reference-types] is implemented then
97 we won't need some of these pesky functions. That'll transform our generated JS
98 shim to look like:
99
100 ```js
101 const __wbg_bar_target = Foo.prototype.bar;
102
103 export function __wbg_bar_a81456386e6b526f(arg0, arg1, arg2) {
104 let varg1 = getStringFromWasm(arg1, arg2);
105 return __wbg_bar_target.call(arg0, varg1);
106 }
107 ```
108
109 Getting better! Next up we need the component model proposal. Note that the
110 proposal is undergoing some changes right now so it's tough to link to reference
111 documentation, but it suffices to say that it'll empower us with at least two
112 different features.
113
114 First, component model promises to provide the concept of "argument conversions".
115 The `arg1` and `arg2` values here are actually a pointer and a length to a utf-8
116 encoded string, and with component model we'll be able to annotate that this
117 import should take those two arguments and convert them to a JS string (that is,
118 the *host* should do this, the WebAssembly engine). Using that feature we can
119 further trim this down to:
120
121 ```js
122 const __wbg_bar_target = Foo.prototype.bar;
123
124 export function __wbg_bar_a81456386e6b526f(arg0, varg1) {
125 return __wbg_bar_target.call(arg0, varg1);
126 }
127 ```
128
129 And finally, the second promise of the component model proposal is that we can
130 flag a function call to indicate the first argument is the `this` binding of the
131 function call. Today the `this` value of all called imported functions is
132 `undefined`, and this flag (configured with component model) will indicate the
133 first argument here is actually the `this`.
134
135 With that in mind we can further transform this to:
136
137 ```js
138 export const __wbg_bar_a81456386e6b526f = Foo.prototype.bar;
139 ```
140
141 and voila! We, with [reference types][reference-types] and [component
142 model][component-model], now have no JS function shim at all necessary to call
143 the imported function. Additionally future wasm proposals to the ES module
144 system may also mean that don't even need the `export const ...` here too.
145
146 It's also worth pointing out that with all these wasm proposals implemented the
147 default way to import the `bar` function (aka `structural`) would generate a JS
148 function shim that looks like:
149
150 ```js
151 export function __wbg_bar_a81456386e6b526f(varg1) {
152 return this.bar(varg1);
153 }
154 ```
155
156 where this import is still subject to runtime prototype chain lookups and such.