-
Notifications
You must be signed in to change notification settings - Fork 1.3k
/
linker.rs
404 lines (375 loc) · 15 KB
/
linker.rs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
use crate::component::func::HostFunc;
use crate::component::instance::RuntimeImport;
use crate::component::matching::TypeChecker;
use crate::component::{Component, ComponentNamedList, Instance, InstancePre, Lift, Lower, Val};
use crate::{AsContextMut, Engine, Module, StoreContextMut};
use anyhow::{anyhow, bail, Context, Result};
use std::collections::hash_map::{Entry, HashMap};
use std::future::Future;
use std::marker;
use std::pin::Pin;
use std::sync::Arc;
use wasmtime_environ::component::TypeDef;
use wasmtime_environ::PrimaryMap;
/// A type used to instantiate [`Component`]s.
///
/// This type is used to both link components together as well as supply host
/// functionality to components. Values are defined in a [`Linker`] by their
/// import name and then components are instantiated with a [`Linker`] using the
/// names provided for name resolution of the component's imports.
pub struct Linker<T> {
engine: Engine,
strings: Strings,
map: NameMap,
allow_shadowing: bool,
_marker: marker::PhantomData<fn() -> T>,
}
#[derive(Default)]
pub struct Strings {
string2idx: HashMap<Arc<str>, usize>,
strings: Vec<Arc<str>>,
}
/// Structure representing an "instance" being defined within a linker.
///
/// Instances do not need to be actual [`Instance`]s and instead are defined by
/// a "bag of named items", so each [`LinkerInstance`] can further define items
/// internally.
pub struct LinkerInstance<'a, T> {
engine: Engine,
strings: &'a mut Strings,
map: &'a mut NameMap,
allow_shadowing: bool,
_marker: marker::PhantomData<fn() -> T>,
}
pub type NameMap = HashMap<usize, Definition>;
#[derive(Clone)]
pub enum Definition {
Instance(NameMap),
Func(Arc<HostFunc>),
Module(Module),
}
impl<T> Linker<T> {
/// Creates a new linker for the [`Engine`] specified with no items defined
/// within it.
pub fn new(engine: &Engine) -> Linker<T> {
Linker {
engine: engine.clone(),
strings: Strings::default(),
map: NameMap::default(),
allow_shadowing: false,
_marker: marker::PhantomData,
}
}
/// Returns the [`Engine`] this is connected to.
pub fn engine(&self) -> &Engine {
&self.engine
}
/// Configures whether or not name-shadowing is allowed.
///
/// By default name shadowing is not allowed and it's an error to redefine
/// the same name within a linker.
pub fn allow_shadowing(&mut self, allow: bool) -> &mut Self {
self.allow_shadowing = allow;
self
}
/// Returns the "root instance" of this linker, used to define names into
/// the root namespace.
pub fn root(&mut self) -> LinkerInstance<'_, T> {
LinkerInstance {
engine: self.engine.clone(),
strings: &mut self.strings,
map: &mut self.map,
allow_shadowing: self.allow_shadowing,
_marker: self._marker,
}
}
/// Returns a builder for the named instance specified.
///
/// # Errors
///
/// Returns an error if `name` is already defined within the linker.
pub fn instance(&mut self, name: &str) -> Result<LinkerInstance<'_, T>> {
self.root().into_instance(name)
}
/// Performs a "pre-instantiation" to resolve the imports of the
/// [`Component`] specified with the items defined within this linker.
///
/// This method will perform as much work as possible short of actually
/// instantiating an instance. Internally this will use the names defined
/// within this linker to satisfy the imports of the [`Component`] provided.
/// Additionally this will perform type-checks against the component's
/// imports against all items defined within this linker.
///
/// Note that unlike internally in components where subtyping at the
/// interface-types layer is supported this is not supported here. Items
/// defined in this linker must match the component's imports precisely.
///
/// # Errors
///
/// Returns an error if this linker doesn't define a name that the
/// `component` imports or if a name defined doesn't match the type of the
/// item imported by the `component` provided.
pub fn instantiate_pre(&self, component: &Component) -> Result<InstancePre<T>> {
let cx = TypeChecker {
types: component.types(),
strings: &self.strings,
};
// Walk over the component's list of import names and use that to lookup
// the definition within this linker that it corresponds to. When found
// perform a typecheck against the component's expected type.
let env_component = component.env_component();
for (_idx, (name, ty)) in env_component.import_types.iter() {
let import = self
.strings
.lookup(name)
.and_then(|name| self.map.get(&name));
cx.definition(ty, import)
.with_context(|| format!("import `{name}` has the wrong type"))?;
}
// Now that all imports are known to be defined and satisfied by this
// linker a list of "flat" import items (aka no instances) is created
// using the import map within the component created at
// component-compile-time.
let mut imports = PrimaryMap::with_capacity(env_component.imports.len());
for (idx, (import, names)) in env_component.imports.iter() {
let (root, _) = &env_component.import_types[*import];
let root = self.strings.lookup(root).unwrap();
// This is the flattening process where we go from a definition
// optionally through a list of exported names to get to the final
// item.
let mut cur = &self.map[&root];
for name in names {
let name = self.strings.lookup(name).unwrap();
cur = match cur {
Definition::Instance(map) => &map[&name],
_ => unreachable!(),
};
}
let import = match cur {
Definition::Module(m) => RuntimeImport::Module(m.clone()),
Definition::Func(f) => RuntimeImport::Func(f.clone()),
// This is guaranteed by the compilation process that "leaf"
// runtime imports are never instances.
Definition::Instance(_) => unreachable!(),
};
let i = imports.push(import);
assert_eq!(i, idx);
}
Ok(unsafe { InstancePre::new_unchecked(component.clone(), imports) })
}
/// Instantiates the [`Component`] provided into the `store` specified.
///
/// This function will use the items defined within this [`Linker`] to
/// satisfy the imports of the [`Component`] provided as necessary. For more
/// information about this see [`Linker::instantiate_pre`] as well.
///
/// # Errors
///
/// Returns an error if this [`Linker`] doesn't define an import that
/// `component` requires or if it is of the wrong type. Additionally this
/// can return an error if something goes wrong during instantiation such as
/// a runtime trap or a runtime limit being exceeded.
pub fn instantiate(
&self,
store: impl AsContextMut<Data = T>,
component: &Component,
) -> Result<Instance> {
assert!(
!store.as_context().async_support(),
"must use async instantiation when async support is enabled"
);
self.instantiate_pre(component)?.instantiate(store)
}
/// Instantiates the [`Component`] provided into the `store` specified.
///
/// This is exactly like [`Linker::instantiate`] except for async stores.
///
/// # Errors
///
/// Returns an error if this [`Linker`] doesn't define an import that
/// `component` requires or if it is of the wrong type. Additionally this
/// can return an error if something goes wrong during instantiation such as
/// a runtime trap or a runtime limit being exceeded.
#[cfg(feature = "async")]
#[cfg_attr(nightlydoc, doc(cfg(feature = "async")))]
pub async fn instantiate_async(
&self,
store: impl AsContextMut<Data = T>,
component: &Component,
) -> Result<Instance>
where
T: Send,
{
assert!(
store.as_context().async_support(),
"must use sync instantiation when async support is disabled"
);
self.instantiate_pre(component)?
.instantiate_async(store)
.await
}
}
impl<T> LinkerInstance<'_, T> {
fn as_mut(&mut self) -> LinkerInstance<'_, T> {
LinkerInstance {
engine: self.engine.clone(),
strings: self.strings,
map: self.map,
allow_shadowing: self.allow_shadowing,
_marker: self._marker,
}
}
/// Defines a new host-provided function into this [`Linker`].
///
/// This method is used to give host functions to wasm components. The
/// `func` provided will be callable from linked components with the type
/// signature dictated by `Params` and `Return`. The `Params` is a tuple of
/// types that will come from wasm and `Return` is a value coming from the
/// host going back to wasm.
///
/// Additionally the `func` takes a
/// [`StoreContextMut`](crate::StoreContextMut) as its first parameter.
///
/// Note that `func` must be an `Fn` and must also be `Send + Sync +
/// 'static`. Shared state within a func is typically accessed with the `T`
/// type parameter from [`Store<T>`](crate::Store) which is accessible
/// through the leading [`StoreContextMut<'_, T>`](crate::StoreContextMut)
/// argument which can be provided to the `func` given here.
//
// TODO: needs more words and examples
pub fn func_wrap<F, Params, Return>(&mut self, name: &str, func: F) -> Result<()>
where
F: Fn(StoreContextMut<T>, Params) -> Result<Return> + Send + Sync + 'static,
Params: ComponentNamedList + Lift + 'static,
Return: ComponentNamedList + Lower + 'static,
{
let name = self.strings.intern(name);
self.insert(name, Definition::Func(HostFunc::from_closure(func)))
}
/// Defines a new host-provided async function into this [`Linker`].
///
/// This is exactly like [`Self::func_wrap`] except it takes an async
/// host function.
#[cfg(feature = "async")]
#[cfg_attr(nightlydoc, doc(cfg(feature = "async")))]
pub fn func_wrap_async<Params, Return, F>(&mut self, name: &str, f: F) -> Result<()>
where
F: for<'a> Fn(
StoreContextMut<'a, T>,
Params,
) -> Box<dyn Future<Output = Result<Return>> + Send + 'a>
+ Send
+ Sync
+ 'static,
Params: ComponentNamedList + Lift + 'static,
Return: ComponentNamedList + Lower + 'static,
{
assert!(
self.engine.config().async_support,
"cannot use `func_wrap_async` without enabling async support in the config"
);
let ff = move |mut store: StoreContextMut<'_, T>, params: Params| -> Result<Return> {
let async_cx = store.as_context_mut().0.async_cx().expect("async cx");
let mut future = Pin::from(f(store.as_context_mut(), params));
unsafe { async_cx.block_on(future.as_mut()) }?
};
self.func_wrap(name, ff)
}
/// Define a new host-provided function using dynamic types.
///
/// `name` must refer to a function type import in `component`. If and when
/// that import is invoked by the component, the specified `func` will be
/// called, which must return a `Val` which is an instance of the result
/// type of the import.
pub fn func_new<
F: Fn(StoreContextMut<'_, T>, &[Val], &mut [Val]) -> Result<()> + Send + Sync + 'static,
>(
&mut self,
component: &Component,
name: &str,
func: F,
) -> Result<()> {
for (import_name, ty) in component.env_component().import_types.values() {
if name == import_name {
if let TypeDef::ComponentFunc(index) = ty {
let name = self.strings.intern(name);
return self.insert(
name,
Definition::Func(HostFunc::new_dynamic(func, *index, component.types())),
);
} else {
bail!("import `{name}` has the wrong type (expected a function)");
}
}
}
Err(anyhow!("import `{name}` not found"))
}
// TODO: define func_new_async
/// Defines a [`Module`] within this instance.
///
/// This can be used to provide a core wasm [`Module`] as an import to a
/// component. The [`Module`] provided is saved within the linker for the
/// specified `name` in this instance.
pub fn module(&mut self, name: &str, module: &Module) -> Result<()> {
let name = self.strings.intern(name);
self.insert(name, Definition::Module(module.clone()))
}
/// Defines a nested instance within this instance.
///
/// This can be used to describe arbitrarily nested levels of instances
/// within a linker to satisfy nested instance exports of components.
pub fn instance(&mut self, name: &str) -> Result<LinkerInstance<'_, T>> {
self.as_mut().into_instance(name)
}
/// Same as [`LinkerInstance::instance`] except with different lifetime
/// parameters.
pub fn into_instance(mut self, name: &str) -> Result<Self> {
let name = self.strings.intern(name);
let item = Definition::Instance(NameMap::default());
let slot = match self.map.entry(name) {
Entry::Occupied(_) if !self.allow_shadowing => {
bail!("import of `{}` defined twice", self.strings.strings[name])
}
Entry::Occupied(o) => {
let slot = o.into_mut();
*slot = item;
slot
}
Entry::Vacant(v) => v.insert(item),
};
self.map = match slot {
Definition::Instance(map) => map,
_ => unreachable!(),
};
Ok(self)
}
fn insert(&mut self, key: usize, item: Definition) -> Result<()> {
match self.map.entry(key) {
Entry::Occupied(_) if !self.allow_shadowing => {
bail!("import of `{}` defined twice", self.strings.strings[key])
}
Entry::Occupied(mut e) => {
e.insert(item);
}
Entry::Vacant(v) => {
v.insert(item);
}
}
Ok(())
}
}
impl Strings {
fn intern(&mut self, string: &str) -> usize {
if let Some(idx) = self.string2idx.get(string) {
return *idx;
}
let string: Arc<str> = string.into();
let idx = self.strings.len();
self.strings.push(string.clone());
self.string2idx.insert(string, idx);
idx
}
pub fn lookup(&self, string: &str) -> Option<usize> {
self.string2idx.get(string).cloned()
}
}