Debian Codegraph @

.cargo/vendor/wasm-bindgen/guide/src/contributing/design/importing-js-struct.md

raw
1 # Importing a class from JS
2
3 Just like with functions after we've started exporting we'll also want to
4 import! Now that we've exported a `class` to JS we'll want to also be able to
5 import classes in Rust as well to invoke methods and such. Since JS classes are
6 in general just JS objects the bindings here will look pretty similar to the JS
7 object bindings describe above.
8
9 As usual though, let's dive into an example!
10
11 ```rust
12 #[wasm_bindgen(module = "./bar")]
13 extern "C" {
14 type Bar;
15
16 #[wasm_bindgen(constructor)]
17 fn new(arg: i32) -> Bar;
18
19 #[wasm_bindgen(js_namespace = Bar)]
20 fn another_function() -> i32;
21
22 #[wasm_bindgen(method)]
23 fn get(this: &Bar) -> i32;
24
25 #[wasm_bindgen(method)]
26 fn set(this: &Bar, val: i32);
27
28 #[wasm_bindgen(method, getter)]
29 fn property(this: &Bar) -> i32;
30
31 #[wasm_bindgen(method, setter)]
32 fn set_property(this: &Bar, val: i32);
33 }
34
35 fn run() {
36 let bar = Bar::new(Bar::another_function());
37 let x = bar.get();
38 bar.set(x + 3);
39
40 bar.set_property(bar.property() + 6);
41 }
42 ```
43
44 Unlike our previous imports, this one's a bit more chatty! Remember that one of
45 the goals of `wasm-bindgen` is to use native Rust syntax wherever possible, so
46 this is mostly intended to use the `#[wasm_bindgen]` attribute to interpret
47 what's written down in Rust. Now there's a few attribute annotations here, so
48 let's go through one-by-one:
49
50 * `#[wasm_bindgen(module = "./bar")]` - seen before with imports this is declare
51 where all the subsequent functionality is imported from. For example the `Bar`
52 type is going to be imported from the `./bar` module.
53 * `type Bar` - this is a declaration of JS class as a new type in Rust. This
54 means that a new type `Bar` is generated which is "opaque" but is represented
55 as internally containing a `JsValue`. We'll see more on this later.
56 * `#[wasm_bindgen(constructor)]` - this indicates that the binding's name isn't
57 actually used in JS but rather translates to `new Bar()`. The return value of
58 this function must be a bare type, like `Bar`.
59 * `#[wasm_bindgen(js_namespace = Bar)]` - this attribute indicates that the
60 function declaration is namespaced through the `Bar` class in JS.
61 * `#[wasm_bindgen(static_method_of = SomeJsClass)]` - this attribute is similar
62 to `js_namespace`, but instead of producing a free function, produces a static
63 method of `SomeJsClass`.
64 * `#[wasm_bindgen(method)]` - and finally, this attribute indicates that a
65 method call is going to happen. The first argument must be a JS struct, like
66 `Bar`, and the call in JS looks like `Bar.prototype.set.call(...)`.
67
68 With all that in mind, let's take a look at the JS generated.
69
70 ```js
71 import * as wasm from './foo_bg';
72
73 import { Bar } from './bar';
74
75 // other support functions omitted...
76
77 export function __wbg_s_Bar_new() {
78 return addHeapObject(new Bar());
79 }
80
81 const another_function_shim = Bar.another_function;
82 export function __wbg_s_Bar_another_function() {
83 return another_function_shim();
84 }
85
86 const get_shim = Bar.prototype.get;
87 export function __wbg_s_Bar_get(ptr) {
88 return shim.call(getObject(ptr));
89 }
90
91 const set_shim = Bar.prototype.set;
92 export function __wbg_s_Bar_set(ptr, arg0) {
93 set_shim.call(getObject(ptr), arg0)
94 }
95
96 const property_shim = Object.getOwnPropertyDescriptor(Bar.prototype, 'property').get;
97 export function __wbg_s_Bar_property(ptr) {
98 return property_shim.call(getObject(ptr));
99 }
100
101 const set_property_shim = Object.getOwnPropertyDescriptor(Bar.prototype, 'property').set;
102 export function __wbg_s_Bar_set_property(ptr, arg0) {
103 set_property_shim.call(getObject(ptr), arg0)
104 }
105 ```
106
107 Like when importing functions from JS we can see a bunch of shims are generated
108 for all the relevant functions. The `new` static function has the
109 `#[wasm_bindgen(constructor)]` attribute which means that instead of any
110 particular method it should actually invoke the `new` constructor instead (as
111 we see here). The static function `another_function`, however, is dispatched as
112 `Bar.another_function`.
113
114 The `get` and `set` functions are methods so they go through `Bar.prototype`,
115 and otherwise their first argument is implicitly the JS object itself which is
116 loaded through `getObject` like we saw earlier.
117
118 Some real meat starts to show up though on the Rust side of things, so let's
119 take a look:
120
121 ```rust
122 pub struct Bar {
123 obj: JsValue,
124 }
125
126 impl Bar {
127 fn new() -> Bar {
128 extern "C" {
129 fn __wbg_s_Bar_new() -> u32;
130 }
131 unsafe {
132 let ret = __wbg_s_Bar_new();
133 Bar { obj: JsValue::__from_idx(ret) }
134 }
135 }
136
137 fn another_function() -> i32 {
138 extern "C" {
139 fn __wbg_s_Bar_another_function() -> i32;
140 }
141 unsafe {
142 __wbg_s_Bar_another_function()
143 }
144 }
145
146 fn get(&self) -> i32 {
147 extern "C" {
148 fn __wbg_s_Bar_get(ptr: u32) -> i32;
149 }
150 unsafe {
151 let ptr = self.obj.__get_idx();
152 let ret = __wbg_s_Bar_get(ptr);
153 return ret
154 }
155 }
156
157 fn set(&self, val: i32) {
158 extern "C" {
159 fn __wbg_s_Bar_set(ptr: u32, val: i32);
160 }
161 unsafe {
162 let ptr = self.obj.__get_idx();
163 __wbg_s_Bar_set(ptr, val);
164 }
165 }
166
167 fn property(&self) -> i32 {
168 extern "C" {
169 fn __wbg_s_Bar_property(ptr: u32) -> i32;
170 }
171 unsafe {
172 let ptr = self.obj.__get_idx();
173 let ret = __wbg_s_Bar_property(ptr);
174 return ret
175 }
176 }
177
178 fn set_property(&self, val: i32) {
179 extern "C" {
180 fn __wbg_s_Bar_set_property(ptr: u32, val: i32);
181 }
182 unsafe {
183 let ptr = self.obj.__get_idx();
184 __wbg_s_Bar_set_property(ptr, val);
185 }
186 }
187 }
188
189 impl WasmBoundary for Bar {
190 // ...
191 }
192
193 impl ToRefWasmBoundary for Bar {
194 // ...
195 }
196 ```
197
198 In Rust we're seeing that a new type, `Bar`, is generated for this import of a
199 class. The type `Bar` internally contains a `JsValue` as an instance of `Bar`
200 is meant to represent a JS object stored in our module's stack/slab. This then
201 works mostly the same way that we saw JS objects work in the beginning.
202
203 When calling `Bar::new` we'll get an index back which is wrapped up in `Bar`
204 (which is itself just a `u32` in memory when stripped down). Each function then
205 passes the index as the first argument and otherwise forwards everything along
206 in Rust.