wasmtime/linker.rs
1use crate::func::HostFunc;
2use crate::instance::InstancePre;
3use crate::store::StoreOpaque;
4use crate::{
5 AsContext, AsContextMut, Caller, Engine, Extern, ExternType, Func, FuncType, ImportType,
6 Instance, IntoFunc, Module, StoreContextMut, Val, ValRaw, ValType,
7};
8use anyhow::{bail, Context, Result};
9use log::warn;
10use std::collections::hash_map::{Entry, HashMap};
11#[cfg(feature = "async")]
12use std::future::Future;
13use std::marker;
14#[cfg(feature = "async")]
15use std::pin::Pin;
16use std::sync::Arc;
17
18/// Structure used to link wasm modules/instances together.
19///
20/// This structure is used to assist in instantiating a [`Module`]. A [`Linker`]
21/// is a way of performing name resolution to make instantiating a module easier
22/// than specifying positional imports to [`Instance::new`]. [`Linker`] is a
23/// name-based resolver where names are dynamically defined and then used to
24/// instantiate a [`Module`].
25///
26/// An important method is [`Linker::instantiate`] which takes a module to
27/// instantiate into the provided store. This method will automatically select
28/// all the right imports for the [`Module`] to be instantiated, and will
29/// otherwise return an error if an import isn't satisfied.
30///
31/// ## Name Resolution
32///
33/// As mentioned previously, `Linker` is a form of name resolver. It will be
34/// using the string-based names of imports on a module to attempt to select a
35/// matching item to hook up to it. This name resolution has two-levels of
36/// namespaces, a module level and a name level. Each item is defined within a
37/// module and then has its own name. This basically follows the wasm standard
38/// for modularization.
39///
40/// Names in a `Linker` cannot be defined twice, but allowing duplicates by
41/// shadowing the previous definition can be controlled with the
42/// [`Linker::allow_shadowing`] method.
43///
44/// ## Commands and Reactors
45///
46/// The [`Linker`] type provides conveniences for working with WASI Commands and
47/// Reactors through the [`Linker::module`] method. This will automatically
48/// handle instantiation and calling `_start` and such as appropriate
49/// depending on the inferred type of module.
50///
51/// ## Type parameter `T`
52///
53/// It's worth pointing out that the type parameter `T` on [`Linker<T>`] does
54/// not represent that `T` is stored within a [`Linker`]. Rather the `T` is used
55/// to ensure that linker-defined functions and stores instantiated into all use
56/// the same matching `T` as host state.
57///
58/// ## Multiple `Store`s
59///
60/// The [`Linker`] type is designed to be compatible, in some scenarios, with
61/// instantiation in multiple [`Store`]s. Specifically host-defined functions
62/// created in [`Linker`] with [`Linker::func_new`], [`Linker::func_wrap`], and
63/// their async versions are compatible to instantiate into any [`Store`]. This
64/// enables programs which want to instantiate lots of modules to create one
65/// [`Linker`] value at program start up and use that continuously for each
66/// [`Store`] created over the lifetime of the program.
67///
68/// Note that once [`Store`]-owned items, such as [`Global`], are defined witin
69/// a [`Linker`] then it is no longer compatible with any [`Store`]. At that
70/// point only the [`Store`] that owns the [`Global`] can be used to instantiate
71/// modules.
72///
73/// ## Multiple `Engine`s
74///
75/// The [`Linker`] type is not compatible with usage between multiple [`Engine`]
76/// values. An [`Engine`] is provided when a [`Linker`] is created and only
77/// stores and items which originate from that [`Engine`] can be used with this
78/// [`Linker`]. If more than one [`Engine`] is used with a [`Linker`] then that
79/// may cause a panic at runtime, similar to how if a [`Func`] is used with the
80/// wrong [`Store`] that can also panic at runtime.
81///
82/// [`Store`]: crate::Store
83/// [`Global`]: crate::Global
84pub struct Linker<T> {
85 engine: Engine,
86 string2idx: HashMap<Arc<str>, usize>,
87 strings: Vec<Arc<str>>,
88 map: HashMap<ImportKey, Definition>,
89 allow_shadowing: bool,
90 allow_unknown_exports: bool,
91 _marker: marker::PhantomData<fn() -> T>,
92}
93
94impl<T> Clone for Linker<T> {
95 fn clone(&self) -> Linker<T> {
96 Linker {
97 engine: self.engine.clone(),
98 string2idx: self.string2idx.clone(),
99 strings: self.strings.clone(),
100 map: self.map.clone(),
101 allow_shadowing: self.allow_shadowing,
102 allow_unknown_exports: self.allow_unknown_exports,
103 _marker: self._marker,
104 }
105 }
106}
107
108#[derive(Copy, Clone, Hash, PartialEq, Eq)]
109struct ImportKey {
110 name: usize,
111 module: usize,
112}
113
114#[derive(Clone)]
115pub(crate) enum Definition {
116 Extern(Extern, DefinitionType),
117 HostFunc(Arc<HostFunc>),
118}
119
120/// This is a sort of slimmed down `ExternType` which notably doesn't have a
121/// `FuncType`, which is an allocation, and additionally retains the current
122/// size of the table/memory.
123#[derive(Clone)]
124pub(crate) enum DefinitionType {
125 Func(wasmtime_runtime::VMSharedSignatureIndex),
126 Global(wasmtime_environ::Global),
127 // Note that tables and memories store not only the original type
128 // information but additionally the current size of the table/memory, as
129 // this is used during linking since the min size specified in the type may
130 // no longer be the current size of the table/memory.
131 Table(wasmtime_environ::Table, u32),
132 Memory(wasmtime_environ::Memory, u64),
133}
134
135macro_rules! generate_wrap_async_func {
136 ($num:tt $($args:ident)*) => (paste::paste!{
137 /// Asynchronous analog of [`Linker::func_wrap`].
138 ///
139 /// For more information also see
140 /// [`Func::wrapN_async`](crate::Func::wrap1_async).
141 #[allow(non_snake_case)]
142 #[cfg(feature = "async")]
143 #[cfg_attr(nightlydoc, doc(cfg(feature = "async")))]
144 pub fn [<func_wrap $num _async>]<$($args,)* R>(
145 &mut self,
146 module: &str,
147 name: &str,
148 func: impl for<'a> Fn(Caller<'a, T>, $($args),*) -> Box<dyn Future<Output = R> + Send + 'a> + Send + Sync + 'static,
149 ) -> Result<&mut Self>
150 where
151 $($args: crate::WasmTy,)*
152 R: crate::WasmRet,
153 {
154 assert!(
155 self.engine.config().async_support,
156 concat!(
157 "cannot use `func_wrap",
158 $num,
159 "_async` without enabling async support on the config",
160 ),
161 );
162 self.func_wrap(module, name, move |mut caller: Caller<'_, T>, $($args: $args),*| {
163 let async_cx = caller.store.as_context_mut().0.async_cx().expect("Attempt to start async function on dying fiber");
164 let mut future = Pin::from(func(caller, $($args),*));
165 match unsafe { async_cx.block_on(future.as_mut()) } {
166 Ok(ret) => ret.into_fallible(),
167 Err(e) => R::fallible_from_error(e),
168 }
169 })
170 }
171 })
172}
173
174impl<T> Linker<T> {
175 /// Creates a new [`Linker`].
176 ///
177 /// The linker will define functions within the context of the `engine`
178 /// provided and can only instantiate modules for a [`Store`][crate::Store]
179 /// that is also defined within the same [`Engine`]. Usage of stores with
180 /// different [`Engine`]s may cause a panic when used with this [`Linker`].
181 pub fn new(engine: &Engine) -> Linker<T> {
182 Linker {
183 engine: engine.clone(),
184 map: HashMap::new(),
185 string2idx: HashMap::new(),
186 strings: Vec::new(),
187 allow_shadowing: false,
188 allow_unknown_exports: false,
189 _marker: marker::PhantomData,
190 }
191 }
192
193 /// Returns the [`Engine`] this is connected to.
194 pub fn engine(&self) -> &Engine {
195 &self.engine
196 }
197
198 /// Configures whether this [`Linker`] will shadow previous duplicate
199 /// definitions of the same signature.
200 ///
201 /// By default a [`Linker`] will disallow duplicate definitions of the same
202 /// signature. This method, however, can be used to instead allow duplicates
203 /// and have the latest definition take precedence when linking modules.
204 ///
205 /// # Examples
206 ///
207 /// ```
208 /// # use wasmtime::*;
209 /// # fn main() -> anyhow::Result<()> {
210 /// # let engine = Engine::default();
211 /// let mut linker = Linker::<()>::new(&engine);
212 /// linker.func_wrap("", "", || {})?;
213 ///
214 /// // by default, duplicates are disallowed
215 /// assert!(linker.func_wrap("", "", || {}).is_err());
216 ///
217 /// // but shadowing can be configured to be allowed as well
218 /// linker.allow_shadowing(true);
219 /// linker.func_wrap("", "", || {})?;
220 /// # Ok(())
221 /// # }
222 /// ```
223 pub fn allow_shadowing(&mut self, allow: bool) -> &mut Self {
224 self.allow_shadowing = allow;
225 self
226 }
227
228 /// Configures whether this [`Linker`] will allow unknown exports from
229 /// command modules.
230 ///
231 /// By default a [`Linker`] will error when unknown exports are encountered
232 /// in a command module while using [`Linker::module`].
233 ///
234 /// This method can be used to allow unknown exports from command modules.
235 ///
236 /// # Examples
237 ///
238 /// ```
239 /// # use wasmtime::*;
240 /// # fn main() -> anyhow::Result<()> {
241 /// # let engine = Engine::default();
242 /// # let module = Module::new(&engine, "(module)")?;
243 /// # let mut store = Store::new(&engine, ());
244 /// let mut linker = Linker::new(&engine);
245 /// linker.allow_unknown_exports(true);
246 /// linker.module(&mut store, "mod", &module)?;
247 /// # Ok(())
248 /// # }
249 /// ```
250 pub fn allow_unknown_exports(&mut self, allow: bool) -> &mut Self {
251 self.allow_unknown_exports = allow;
252 self
253 }
254
255 /// Implement any imports of the given [`Module`] with a function which traps.
256 ///
257 /// By default a [`Linker`] will error when unknown imports are encountered
258 /// in a command module while using [`Linker::module`]. Use this function
259 /// when
260 ///
261 /// This method can be used to allow unknown imports from command modules.
262 ///
263 /// # Examples
264 ///
265 /// ```
266 /// # use wasmtime::*;
267 /// # fn main() -> anyhow::Result<()> {
268 /// # let engine = Engine::default();
269 /// # let module = Module::new(&engine, "(module (import \"unknown\" \"import\" (func)))")?;
270 /// # let mut store = Store::new(&engine, ());
271 /// let mut linker = Linker::new(&engine);
272 /// linker.define_unknown_imports_as_traps(&module)?;
273 /// linker.instantiate(&mut store, &module)?;
274 /// # Ok(())
275 /// # }
276 /// ```
277 #[cfg(compiler)]
278 #[cfg_attr(nightlydoc, doc(cfg(feature = "cranelift")))] // see build.rs
279 pub fn define_unknown_imports_as_traps(&mut self, module: &Module) -> anyhow::Result<()> {
280 for import in module.imports() {
281 if let Err(import_err) = self._get_by_import(&import) {
282 if let ExternType::Func(func_ty) = import_err.ty() {
283 self.func_new(import.module(), import.name(), func_ty, move |_, _, _| {
284 bail!(import_err.clone());
285 })?;
286 }
287 }
288 }
289 Ok(())
290 }
291
292 /// Implement any function imports of the [`Module`] with a function that
293 /// ignores its arguments and returns default values.
294 ///
295 /// Default values are either zero or null, depending on the value type.
296 ///
297 /// This method can be used to allow unknown imports from command modules.
298 ///
299 /// # Example
300 ///
301 /// ```
302 /// # use wasmtime::*;
303 /// # fn main() -> anyhow::Result<()> {
304 /// # let engine = Engine::default();
305 /// # let module = Module::new(&engine, "(module (import \"unknown\" \"import\" (func)))")?;
306 /// # let mut store = Store::new(&engine, ());
307 /// let mut linker = Linker::new(&engine);
308 /// linker.define_unknown_imports_as_default_values(&module)?;
309 /// linker.instantiate(&mut store, &module)?;
310 /// # Ok(())
311 /// # }
312 /// ```
313 #[cfg(compiler)]
314 #[cfg_attr(nightlydoc, doc(cfg(feature = "cranelift")))] // see build.rs
315 pub fn define_unknown_imports_as_default_values(
316 &mut self,
317 module: &Module,
318 ) -> anyhow::Result<()> {
319 for import in module.imports() {
320 if let Err(import_err) = self._get_by_import(&import) {
321 if let ExternType::Func(func_ty) = import_err.ty() {
322 let result_tys: Vec<_> = func_ty.results().collect();
323 self.func_new(
324 import.module(),
325 import.name(),
326 func_ty,
327 move |_caller, _args, results| {
328 for (result, ty) in results.iter_mut().zip(&result_tys) {
329 *result = match ty {
330 ValType::I32 => Val::I32(0),
331 ValType::I64 => Val::I64(0),
332 ValType::F32 => Val::F32(0.0_f32.to_bits()),
333 ValType::F64 => Val::F64(0.0_f64.to_bits()),
334 ValType::V128 => Val::V128(0),
335 ValType::FuncRef => Val::FuncRef(None),
336 ValType::ExternRef => Val::ExternRef(None),
337 };
338 }
339 Ok(())
340 },
341 )?;
342 }
343 }
344 }
345 Ok(())
346 }
347
348 /// Defines a new item in this [`Linker`].
349 ///
350 /// This method will add a new definition, by name, to this instance of
351 /// [`Linker`]. The `module` and `name` provided are what to name the
352 /// `item`.
353 ///
354 /// # Errors
355 ///
356 /// Returns an error if the `module` and `name` already identify an item
357 /// of the same type as the `item` provided and if shadowing is disallowed.
358 /// For more information see the documentation on [`Linker`].
359 ///
360 /// # Examples
361 ///
362 /// ```
363 /// # use wasmtime::*;
364 /// # fn main() -> anyhow::Result<()> {
365 /// # let engine = Engine::default();
366 /// # let mut store = Store::new(&engine, ());
367 /// let mut linker = Linker::new(&engine);
368 /// let ty = GlobalType::new(ValType::I32, Mutability::Const);
369 /// let global = Global::new(&mut store, ty, Val::I32(0x1234))?;
370 /// linker.define(&store, "host", "offset", global)?;
371 ///
372 /// let wat = r#"
373 /// (module
374 /// (import "host" "offset" (global i32))
375 /// (memory 1)
376 /// (data (global.get 0) "foo")
377 /// )
378 /// "#;
379 /// let module = Module::new(&engine, wat)?;
380 /// linker.instantiate(&mut store, &module)?;
381 /// # Ok(())
382 /// # }
383 /// ```
384 pub fn define(
385 &mut self,
386 store: impl AsContext<Data = T>,
387 module: &str,
388 name: &str,
389 item: impl Into<Extern>,
390 ) -> Result<&mut Self> {
391 let store = store.as_context();
392 let key = self.import_key(module, Some(name));
393 self.insert(key, Definition::new(store.0, item.into()))?;
394 Ok(self)
395 }
396
397 /// Same as [`Linker::define`], except only the name of the import is
398 /// provided, not a module name as well.
399 ///
400 /// This is only relevant when working with the module linking proposal
401 /// where one-level names are allowed (in addition to two-level names).
402 /// Otherwise this method need not be used.
403 pub fn define_name(
404 &mut self,
405 store: impl AsContext<Data = T>,
406 name: &str,
407 item: impl Into<Extern>,
408 ) -> Result<&mut Self> {
409 let store = store.as_context();
410 let key = self.import_key(name, None);
411 self.insert(key, Definition::new(store.0, item.into()))?;
412 Ok(self)
413 }
414
415 /// Creates a [`Func::new`]-style function named in this linker.
416 ///
417 /// For more information see [`Linker::func_wrap`].
418 #[cfg(compiler)]
419 #[cfg_attr(nightlydoc, doc(cfg(feature = "cranelift")))] // see build.rs
420 pub fn func_new(
421 &mut self,
422 module: &str,
423 name: &str,
424 ty: FuncType,
425 func: impl Fn(Caller<'_, T>, &[Val], &mut [Val]) -> Result<()> + Send + Sync + 'static,
426 ) -> Result<&mut Self> {
427 let func = HostFunc::new(&self.engine, ty, func);
428 let key = self.import_key(module, Some(name));
429 self.insert(key, Definition::HostFunc(Arc::new(func)))?;
430 Ok(self)
431 }
432
433 /// Creates a [`Func::new_unchecked`]-style function named in this linker.
434 ///
435 /// For more information see [`Linker::func_wrap`].
436 #[cfg(compiler)]
437 #[cfg_attr(nightlydoc, doc(cfg(feature = "cranelift")))] // see build.rs
438 pub unsafe fn func_new_unchecked(
439 &mut self,
440 module: &str,
441 name: &str,
442 ty: FuncType,
443 func: impl Fn(Caller<'_, T>, &mut [ValRaw]) -> Result<()> + Send + Sync + 'static,
444 ) -> Result<&mut Self> {
445 let func = HostFunc::new_unchecked(&self.engine, ty, func);
446 let key = self.import_key(module, Some(name));
447 self.insert(key, Definition::HostFunc(Arc::new(func)))?;
448 Ok(self)
449 }
450
451 /// Creates a [`Func::new_async`]-style function named in this linker.
452 ///
453 /// For more information see [`Linker::func_wrap`].
454 #[cfg(all(feature = "async", feature = "cranelift"))]
455 #[cfg_attr(nightlydoc, doc(cfg(all(feature = "async", feature = "cranelift"))))]
456 pub fn func_new_async<F>(
457 &mut self,
458 module: &str,
459 name: &str,
460 ty: FuncType,
461 func: F,
462 ) -> Result<&mut Self>
463 where
464 F: for<'a> Fn(
465 Caller<'a, T>,
466 &'a [Val],
467 &'a mut [Val],
468 ) -> Box<dyn Future<Output = Result<()>> + Send + 'a>
469 + Send
470 + Sync
471 + 'static,
472 {
473 assert!(
474 self.engine.config().async_support,
475 "cannot use `func_new_async` without enabling async support in the config"
476 );
477 self.func_new(module, name, ty, move |mut caller, params, results| {
478 let async_cx = caller
479 .store
480 .as_context_mut()
481 .0
482 .async_cx()
483 .expect("Attempt to spawn new function on dying fiber");
484 let mut future = Pin::from(func(caller, params, results));
485 match unsafe { async_cx.block_on(future.as_mut()) } {
486 Ok(Ok(())) => Ok(()),
487 Ok(Err(trap)) | Err(trap) => Err(trap),
488 }
489 })
490 }
491
492 /// Define a host function within this linker.
493 ///
494 /// For information about how the host function operates, see
495 /// [`Func::wrap`]. That includes information about translating Rust types
496 /// to WebAssembly native types.
497 ///
498 /// This method creates a host-provided function in this linker under the
499 /// provided name. This method is distinct in its capability to create a
500 /// [`Store`](crate::Store)-independent function. This means that the
501 /// function defined here can be used to instantiate instances in multiple
502 /// different stores, or in other words the function can be loaded into
503 /// different stores.
504 ///
505 /// Note that the capability mentioned here applies to all other
506 /// host-function-defining-methods on [`Linker`] as well. All of them can be
507 /// used to create instances of [`Func`] within multiple stores. In a
508 /// multithreaded program, for example, this means that the host functions
509 /// could be called concurrently if different stores are executing on
510 /// different threads.
511 ///
512 /// # Errors
513 ///
514 /// Returns an error if the `module` and `name` already identify an item
515 /// of the same type as the `item` provided and if shadowing is disallowed.
516 /// For more information see the documentation on [`Linker`].
517 ///
518 /// # Examples
519 ///
520 /// ```
521 /// # use wasmtime::*;
522 /// # fn main() -> anyhow::Result<()> {
523 /// # let engine = Engine::default();
524 /// let mut linker = Linker::new(&engine);
525 /// linker.func_wrap("host", "double", |x: i32| x * 2)?;
526 /// linker.func_wrap("host", "log_i32", |x: i32| println!("{}", x))?;
527 /// linker.func_wrap("host", "log_str", |caller: Caller<'_, ()>, ptr: i32, len: i32| {
528 /// // ...
529 /// })?;
530 ///
531 /// let wat = r#"
532 /// (module
533 /// (import "host" "double" (func (param i32) (result i32)))
534 /// (import "host" "log_i32" (func (param i32)))
535 /// (import "host" "log_str" (func (param i32 i32)))
536 /// )
537 /// "#;
538 /// let module = Module::new(&engine, wat)?;
539 ///
540 /// // instantiate in multiple different stores
541 /// for _ in 0..10 {
542 /// let mut store = Store::new(&engine, ());
543 /// linker.instantiate(&mut store, &module)?;
544 /// }
545 /// # Ok(())
546 /// # }
547 /// ```
548 pub fn func_wrap<Params, Args>(
549 &mut self,
550 module: &str,
551 name: &str,
552 func: impl IntoFunc<T, Params, Args>,
553 ) -> Result<&mut Self> {
554 let func = HostFunc::wrap(&self.engine, func);
555 let key = self.import_key(module, Some(name));
556 self.insert(key, Definition::HostFunc(Arc::new(func)))?;
557 Ok(self)
558 }
559
560 for_each_function_signature!(generate_wrap_async_func);
561
562 /// Convenience wrapper to define an entire [`Instance`] in this linker.
563 ///
564 /// This function is a convenience wrapper around [`Linker::define`] which
565 /// will define all exports on `instance` into this linker. The module name
566 /// for each export is `module_name`, and the name for each export is the
567 /// name in the instance itself.
568 ///
569 /// Note that when this API is used the [`Linker`] is no longer compatible
570 /// with multi-[`Store`][crate::Store] instantiation because the items
571 /// defined within this store will belong to the `store` provided, and only
572 /// the `store` provided.
573 ///
574 /// # Errors
575 ///
576 /// Returns an error if the any item is redefined twice in this linker (for
577 /// example the same `module_name` was already defined) and shadowing is
578 /// disallowed, or if `instance` comes from a different
579 /// [`Store`](crate::Store) than this [`Linker`] originally was created
580 /// with.
581 ///
582 /// # Panics
583 ///
584 /// Panics if `instance` does not belong to `store`.
585 ///
586 /// # Examples
587 ///
588 /// ```
589 /// # use wasmtime::*;
590 /// # fn main() -> anyhow::Result<()> {
591 /// # let engine = Engine::default();
592 /// # let mut store = Store::new(&engine, ());
593 /// let mut linker = Linker::new(&engine);
594 ///
595 /// // Instantiate a small instance...
596 /// let wat = r#"(module (func (export "run") ))"#;
597 /// let module = Module::new(&engine, wat)?;
598 /// let instance = linker.instantiate(&mut store, &module)?;
599 ///
600 /// // ... and inform the linker that the name of this instance is
601 /// // `instance1`. This defines the `instance1::run` name for our next
602 /// // module to use.
603 /// linker.instance(&mut store, "instance1", instance)?;
604 ///
605 /// let wat = r#"
606 /// (module
607 /// (import "instance1" "run" (func $instance1_run))
608 /// (func (export "run")
609 /// call $instance1_run
610 /// )
611 /// )
612 /// "#;
613 /// let module = Module::new(&engine, wat)?;
614 /// let instance = linker.instantiate(&mut store, &module)?;
615 /// # Ok(())
616 /// # }
617 /// ```
618 pub fn instance(
619 &mut self,
620 mut store: impl AsContextMut<Data = T>,
621 module_name: &str,
622 instance: Instance,
623 ) -> Result<&mut Self> {
624 let mut store = store.as_context_mut();
625 let exports = instance
626 .exports(&mut store)
627 .map(|e| {
628 (
629 self.import_key(module_name, Some(e.name())),
630 e.into_extern(),
631 )
632 })
633 .collect::<Vec<_>>();
634 for (key, export) in exports {
635 self.insert(key, Definition::new(store.0, export))?;
636 }
637 Ok(self)
638 }
639
640 /// Define automatic instantiations of a [`Module`] in this linker.
641 ///
642 /// This automatically handles [Commands and Reactors] instantiation and
643 /// initialization.
644 ///
645 /// Exported functions of a Command module may be called directly, however
646 /// instead of having a single instance which is reused for each call,
647 /// each call creates a new instance, which lives for the duration of the
648 /// call. The imports of the Command are resolved once, and reused for
649 /// each instantiation, so all dependencies need to be present at the time
650 /// when `Linker::module` is called.
651 ///
652 /// For Reactors, a single instance is created, and an initialization
653 /// function is called, and then its exports may be called.
654 ///
655 /// Ordinary modules which don't declare themselves to be either Commands
656 /// or Reactors are treated as Reactors without any initialization calls.
657 ///
658 /// [Commands and Reactors]: https://github.com/WebAssembly/WASI/blob/main/legacy/application-abi.md#current-unstable-abi
659 ///
660 /// # Errors
661 ///
662 /// Returns an error if the any item is redefined twice in this linker (for
663 /// example the same `module_name` was already defined) and shadowing is
664 /// disallowed, if `instance` comes from a different
665 /// [`Store`](crate::Store) than this [`Linker`] originally was created
666 /// with, or if a Reactor initialization function traps.
667 ///
668 /// # Panics
669 ///
670 /// Panics if any item used to instantiate the provided [`Module`] is not
671 /// owned by `store`, or if the `store` provided comes from a different
672 /// [`Engine`] than this [`Linker`].
673 ///
674 /// # Examples
675 ///
676 /// ```
677 /// # use wasmtime::*;
678 /// # fn main() -> anyhow::Result<()> {
679 /// # let engine = Engine::default();
680 /// # let mut store = Store::new(&engine, ());
681 /// let mut linker = Linker::new(&engine);
682 ///
683 /// // Instantiate a small instance and inform the linker that the name of
684 /// // this instance is `instance1`. This defines the `instance1::run` name
685 /// // for our next module to use.
686 /// let wat = r#"(module (func (export "run") ))"#;
687 /// let module = Module::new(&engine, wat)?;
688 /// linker.module(&mut store, "instance1", &module)?;
689 ///
690 /// let wat = r#"
691 /// (module
692 /// (import "instance1" "run" (func $instance1_run))
693 /// (func (export "run")
694 /// call $instance1_run
695 /// )
696 /// )
697 /// "#;
698 /// let module = Module::new(&engine, wat)?;
699 /// let instance = linker.instantiate(&mut store, &module)?;
700 /// # Ok(())
701 /// # }
702 /// ```
703 ///
704 /// For a Command, a new instance is created for each call.
705 ///
706 /// ```
707 /// # use wasmtime::*;
708 /// # fn main() -> anyhow::Result<()> {
709 /// # let engine = Engine::default();
710 /// # let mut store = Store::new(&engine, ());
711 /// let mut linker = Linker::new(&engine);
712 ///
713 /// // Create a Command that attempts to count the number of times it is run, but is
714 /// // foiled by each call getting a new instance.
715 /// let wat = r#"
716 /// (module
717 /// (global $counter (mut i32) (i32.const 0))
718 /// (func (export "_start")
719 /// (global.set $counter (i32.add (global.get $counter) (i32.const 1)))
720 /// )
721 /// (func (export "read_counter") (result i32)
722 /// (global.get $counter)
723 /// )
724 /// )
725 /// "#;
726 /// let module = Module::new(&engine, wat)?;
727 /// linker.module(&mut store, "commander", &module)?;
728 /// let run = linker.get_default(&mut store, "")?
729 /// .typed::<(), ()>(&store)?
730 /// .clone();
731 /// run.call(&mut store, ())?;
732 /// run.call(&mut store, ())?;
733 /// run.call(&mut store, ())?;
734 ///
735 /// let wat = r#"
736 /// (module
737 /// (import "commander" "_start" (func $commander_start))
738 /// (import "commander" "read_counter" (func $commander_read_counter (result i32)))
739 /// (func (export "run") (result i32)
740 /// call $commander_start
741 /// call $commander_start
742 /// call $commander_start
743 /// call $commander_read_counter
744 /// )
745 /// )
746 /// "#;
747 /// let module = Module::new(&engine, wat)?;
748 /// linker.module(&mut store, "", &module)?;
749 /// let run = linker.get(&mut store, "", "run").unwrap().into_func().unwrap();
750 /// let count = run.typed::<(), i32>(&store)?.call(&mut store, ())?;
751 /// assert_eq!(count, 0, "a Command should get a fresh instance on each invocation");
752 ///
753 /// # Ok(())
754 /// # }
755 /// ```
756 #[cfg(compiler)]
757 #[cfg_attr(nightlydoc, doc(cfg(feature = "cranelift")))] // see build.rs
758 pub fn module(
759 &mut self,
760 mut store: impl AsContextMut<Data = T>,
761 module_name: &str,
762 module: &Module,
763 ) -> Result<&mut Self>
764 where
765 T: 'static,
766 {
767 // NB: this is intended to function the same as `Linker::module_async`,
768 // they should be kept in sync.
769
770 // This assert isn't strictly necessary since it'll bottom out in the
771 // `HostFunc::to_func` method anyway. This is placed earlier for this
772 // function though to prevent the functions created here from delaying
773 // the panic until they're called.
774 assert!(
775 Engine::same(&self.engine, store.as_context().engine()),
776 "different engines for this linker and the store provided"
777 );
778 match ModuleKind::categorize(module)? {
779 ModuleKind::Command => {
780 self.command(
781 store,
782 module_name,
783 module,
784 |store, func_ty, export_name, instance_pre| {
785 Func::new(
786 store,
787 func_ty.clone(),
788 move |mut caller, params, results| {
789 // Create a new instance for this command execution.
790 let instance = instance_pre.instantiate(&mut caller)?;
791
792 // `unwrap()` everything here because we know the instance contains a
793 // function export with the given name and signature because we're
794 // iterating over the module it was instantiated from.
795 instance
796 .get_export(&mut caller, &export_name)
797 .unwrap()
798 .into_func()
799 .unwrap()
800 .call(&mut caller, params, results)?;
801
802 Ok(())
803 },
804 )
805 },
806 )
807 }
808 ModuleKind::Reactor => {
809 let instance = self.instantiate(&mut store, &module)?;
810
811 if let Some(export) = instance.get_export(&mut store, "_initialize") {
812 if let Extern::Func(func) = export {
813 func.typed::<(), ()>(&store)
814 .and_then(|f| f.call(&mut store, ()).map_err(Into::into))
815 .context("calling the Reactor initialization function")?;
816 }
817 }
818
819 self.instance(store, module_name, instance)
820 }
821 }
822 }
823
824 /// Define automatic instantiations of a [`Module`] in this linker.
825 ///
826 /// This is the same as [`Linker::module`], except for async `Store`s.
827 #[cfg(all(feature = "async", feature = "cranelift"))]
828 #[cfg_attr(nightlydoc, doc(cfg(all(feature = "async", feature = "cranelift"))))]
829 pub async fn module_async(
830 &mut self,
831 mut store: impl AsContextMut<Data = T>,
832 module_name: &str,
833 module: &Module,
834 ) -> Result<&mut Self>
835 where
836 T: Send + 'static,
837 {
838 // NB: this is intended to function the same as `Linker::module`, they
839 // should be kept in sync.
840 assert!(
841 Engine::same(&self.engine, store.as_context().engine()),
842 "different engines for this linker and the store provided"
843 );
844 match ModuleKind::categorize(module)? {
845 ModuleKind::Command => self.command(
846 store,
847 module_name,
848 module,
849 |store, func_ty, export_name, instance_pre| {
850 let upvars = Arc::new((instance_pre, export_name));
851 Func::new_async(
852 store,
853 func_ty.clone(),
854 move |mut caller, params, results| {
855 let upvars = upvars.clone();
856 Box::new(async move {
857 let (instance_pre, export_name) = &*upvars;
858 let instance = instance_pre.instantiate_async(&mut caller).await?;
859
860 instance
861 .get_export(&mut caller, &export_name)
862 .unwrap()
863 .into_func()
864 .unwrap()
865 .call_async(&mut caller, params, results)
866 .await?;
867 Ok(())
868 })
869 },
870 )
871 },
872 ),
873 ModuleKind::Reactor => {
874 let instance = self.instantiate_async(&mut store, &module).await?;
875
876 if let Some(export) = instance.get_export(&mut store, "_initialize") {
877 if let Extern::Func(func) = export {
878 let func = func
879 .typed::<(), ()>(&store)
880 .context("loading the Reactor initialization function")?;
881 func.call_async(&mut store, ())
882 .await
883 .context("calling the Reactor initialization function")?;
884 }
885 }
886
887 self.instance(store, module_name, instance)
888 }
889 }
890 }
891
892 fn command(
893 &mut self,
894 mut store: impl AsContextMut<Data = T>,
895 module_name: &str,
896 module: &Module,
897 mk_func: impl Fn(&mut StoreContextMut<T>, &FuncType, String, InstancePre<T>) -> Func,
898 ) -> Result<&mut Self>
899 where
900 T: 'static,
901 {
902 let mut store = store.as_context_mut();
903 for export in module.exports() {
904 if let Some(func_ty) = export.ty().func() {
905 let instance_pre = self.instantiate_pre(module)?;
906 let export_name = export.name().to_owned();
907 let func = mk_func(&mut store, func_ty, export_name, instance_pre);
908 let key = self.import_key(module_name, Some(export.name()));
909 self.insert(key, Definition::new(store.0, func.into()))?;
910 } else if export.name() == "memory" && export.ty().memory().is_some() {
911 // Allow an exported "memory" memory for now.
912 } else if export.name() == "__indirect_function_table" && export.ty().table().is_some()
913 {
914 // Allow an exported "__indirect_function_table" table for now.
915 } else if export.name() == "table" && export.ty().table().is_some() {
916 // Allow an exported "table" table for now.
917 } else if export.name() == "__data_end" && export.ty().global().is_some() {
918 // Allow an exported "__data_end" memory for compatibility with toolchains
919 // which use --export-dynamic, which unfortunately doesn't work the way
920 // we want it to.
921 warn!("command module exporting '__data_end' is deprecated");
922 } else if export.name() == "__heap_base" && export.ty().global().is_some() {
923 // Allow an exported "__data_end" memory for compatibility with toolchains
924 // which use --export-dynamic, which unfortunately doesn't work the way
925 // we want it to.
926 warn!("command module exporting '__heap_base' is deprecated");
927 } else if export.name() == "__dso_handle" && export.ty().global().is_some() {
928 // Allow an exported "__dso_handle" memory for compatibility with toolchains
929 // which use --export-dynamic, which unfortunately doesn't work the way
930 // we want it to.
931 warn!("command module exporting '__dso_handle' is deprecated")
932 } else if export.name() == "__rtti_base" && export.ty().global().is_some() {
933 // Allow an exported "__rtti_base" memory for compatibility with
934 // AssemblyScript.
935 warn!("command module exporting '__rtti_base' is deprecated; pass `--runtime half` to the AssemblyScript compiler");
936 } else if !self.allow_unknown_exports {
937 bail!("command export '{}' is not a function", export.name());
938 }
939 }
940
941 Ok(self)
942 }
943
944 /// Aliases one item's name as another.
945 ///
946 /// This method will alias an item with the specified `module` and `name`
947 /// under a new name of `as_module` and `as_name`.
948 ///
949 /// # Errors
950 ///
951 /// Returns an error if any shadowing violations happen while defining new
952 /// items, or if the original item wasn't defined.
953 pub fn alias(
954 &mut self,
955 module: &str,
956 name: &str,
957 as_module: &str,
958 as_name: &str,
959 ) -> Result<&mut Self> {
960 let src = self.import_key(module, Some(name));
961 let dst = self.import_key(as_module, Some(as_name));
962 match self.map.get(&src).cloned() {
963 Some(item) => self.insert(dst, item)?,
964 None => bail!("no item named `{}::{}` defined", module, name),
965 }
966 Ok(self)
967 }
968
969 /// Aliases one module's name as another.
970 ///
971 /// This method will alias all currently defined under `module` to also be
972 /// defined under the name `as_module` too.
973 ///
974 /// # Errors
975 ///
976 /// Returns an error if any shadowing violations happen while defining new
977 /// items.
978 pub fn alias_module(&mut self, module: &str, as_module: &str) -> Result<()> {
979 let module = self.intern_str(module);
980 let as_module = self.intern_str(as_module);
981 let items = self
982 .map
983 .iter()
984 .filter(|(key, _def)| key.module == module)
985 .map(|(key, def)| (key.name, def.clone()))
986 .collect::<Vec<_>>();
987 for (name, item) in items {
988 self.insert(
989 ImportKey {
990 module: as_module,
991 name,
992 },
993 item,
994 )?;
995 }
996 Ok(())
997 }
998
999 fn insert(&mut self, key: ImportKey, item: Definition) -> Result<()> {
1000 match self.map.entry(key) {
1001 Entry::Occupied(_) if !self.allow_shadowing => {
1002 let module = &self.strings[key.module];
1003 let desc = match self.strings.get(key.name) {
1004 Some(name) => format!("{}::{}", module, name),
1005 None => module.to_string(),
1006 };
1007 bail!("import of `{}` defined twice", desc)
1008 }
1009 Entry::Occupied(mut o) => {
1010 o.insert(item);
1011 }
1012 Entry::Vacant(v) => {
1013 v.insert(item);
1014 }
1015 }
1016 Ok(())
1017 }
1018
1019 fn import_key(&mut self, module: &str, name: Option<&str>) -> ImportKey {
1020 ImportKey {
1021 module: self.intern_str(module),
1022 name: name
1023 .map(|name| self.intern_str(name))
1024 .unwrap_or(usize::max_value()),
1025 }
1026 }
1027
1028 fn intern_str(&mut self, string: &str) -> usize {
1029 if let Some(idx) = self.string2idx.get(string) {
1030 return *idx;
1031 }
1032 let string: Arc<str> = string.into();
1033 let idx = self.strings.len();
1034 self.strings.push(string.clone());
1035 self.string2idx.insert(string, idx);
1036 idx
1037 }
1038
1039 /// Attempts to instantiate the `module` provided.
1040 ///
1041 /// This method will attempt to assemble a list of imports that correspond
1042 /// to the imports required by the [`Module`] provided. This list
1043 /// of imports is then passed to [`Instance::new`] to continue the
1044 /// instantiation process.
1045 ///
1046 /// Each import of `module` will be looked up in this [`Linker`] and must
1047 /// have previously been defined. If it was previously defined with an
1048 /// incorrect signature or if it was not previously defined then an error
1049 /// will be returned because the import can not be satisfied.
1050 ///
1051 /// Per the WebAssembly spec, instantiation includes running the module's
1052 /// start function, if it has one (not to be confused with the `_start`
1053 /// function, which is not run).
1054 ///
1055 /// # Errors
1056 ///
1057 /// This method can fail because an import may not be found, or because
1058 /// instantiation itself may fail. For information on instantiation
1059 /// failures see [`Instance::new`]. If an import is not found, the error
1060 /// may be downcast to an [`UnknownImportError`].
1061 ///
1062 ///
1063 /// # Panics
1064 ///
1065 /// Panics if any item used to instantiate `module` is not owned by
1066 /// `store`. Additionally this will panic if the [`Engine`] that the `store`
1067 /// belongs to is different than this [`Linker`].
1068 ///
1069 /// # Examples
1070 ///
1071 /// ```
1072 /// # use wasmtime::*;
1073 /// # fn main() -> anyhow::Result<()> {
1074 /// # let engine = Engine::default();
1075 /// # let mut store = Store::new(&engine, ());
1076 /// let mut linker = Linker::new(&engine);
1077 /// linker.func_wrap("host", "double", |x: i32| x * 2)?;
1078 ///
1079 /// let wat = r#"
1080 /// (module
1081 /// (import "host" "double" (func (param i32) (result i32)))
1082 /// )
1083 /// "#;
1084 /// let module = Module::new(&engine, wat)?;
1085 /// linker.instantiate(&mut store, &module)?;
1086 /// # Ok(())
1087 /// # }
1088 /// ```
1089 pub fn instantiate(
1090 &self,
1091 mut store: impl AsContextMut<Data = T>,
1092 module: &Module,
1093 ) -> Result<Instance> {
1094 self._instantiate_pre(module, Some(store.as_context_mut().0))?
1095 .instantiate(store)
1096 }
1097
1098 /// Attempts to instantiate the `module` provided. This is the same as
1099 /// [`Linker::instantiate`], except for async `Store`s.
1100 #[cfg(feature = "async")]
1101 #[cfg_attr(nightlydoc, doc(cfg(feature = "async")))]
1102 pub async fn instantiate_async(
1103 &self,
1104 mut store: impl AsContextMut<Data = T>,
1105 module: &Module,
1106 ) -> Result<Instance>
1107 where
1108 T: Send,
1109 {
1110 self._instantiate_pre(module, Some(store.as_context_mut().0))?
1111 .instantiate_async(store)
1112 .await
1113 }
1114
1115 /// Performs all checks necessary for instantiating `module` with this
1116 /// linker, except that instantiation doesn't actually finish.
1117 ///
1118 /// This method is used for front-loading type-checking information as well
1119 /// as collecting the imports to use to instantiate a module with. The
1120 /// returned [`InstancePre`] represents a ready-to-be-instantiated module,
1121 /// which can also be instantiated multiple times if desired.
1122 ///
1123 /// # Errors
1124 ///
1125 /// Returns an error which may be downcast to an [`UnknownImportError`] if
1126 /// the module has any unresolvable imports.
1127 ///
1128 /// # Examples
1129 ///
1130 /// ```
1131 /// # use wasmtime::*;
1132 /// # fn main() -> anyhow::Result<()> {
1133 /// # let engine = Engine::default();
1134 /// # let mut store = Store::new(&engine, ());
1135 /// let mut linker = Linker::new(&engine);
1136 /// linker.func_wrap("host", "double", |x: i32| x * 2)?;
1137 ///
1138 /// let wat = r#"
1139 /// (module
1140 /// (import "host" "double" (func (param i32) (result i32)))
1141 /// )
1142 /// "#;
1143 /// let module = Module::new(&engine, wat)?;
1144 /// let instance_pre = linker.instantiate_pre(&module)?;
1145 ///
1146 /// // Finish instantiation after the type-checking has all completed...
1147 /// let instance = instance_pre.instantiate(&mut store)?;
1148 ///
1149 /// // ... and we can even continue to keep instantiating if desired!
1150 /// instance_pre.instantiate(&mut store)?;
1151 /// instance_pre.instantiate(&mut store)?;
1152 ///
1153 /// // Note that functions defined in a linker with `func_wrap` and similar
1154 /// // constructors are not owned by any particular `Store`, so we can also
1155 /// // instantiate our `instance_pre` in other stores because no imports
1156 /// // belong to the original store.
1157 /// let mut new_store = Store::new(&engine, ());
1158 /// instance_pre.instantiate(&mut new_store)?;
1159 /// # Ok(())
1160 /// # }
1161 /// ```
1162 pub fn instantiate_pre(&self, module: &Module) -> Result<InstancePre<T>> {
1163 self._instantiate_pre(module, None)
1164 }
1165
1166 /// This is split out to optionally take a `store` so that when the
1167 /// `.instantiate` API is used we can get fresh up-to-date type information
1168 /// for memories and their current size, if necessary.
1169 ///
1170 /// Note that providing a `store` here is not required for correctness
1171 /// per-se. If one is not provided, such as the with the `instantiate_pre`
1172 /// API, then the type information used for memories and tables will reflect
1173 /// their size when inserted into the linker rather than their current size.
1174 /// This isn't expected to be much of a problem though since
1175 /// per-store-`Linker` types are likely using `.instantiate(..)` and
1176 /// per-`Engine` linkers don't have memories/tables in them.
1177 fn _instantiate_pre(
1178 &self,
1179 module: &Module,
1180 store: Option<&StoreOpaque>,
1181 ) -> Result<InstancePre<T>> {
1182 let mut imports = module
1183 .imports()
1184 .map(|import| self._get_by_import(&import))
1185 .collect::<Result<Vec<_>, _>>()?;
1186 if let Some(store) = store {
1187 for import in imports.iter_mut() {
1188 import.update_size(store);
1189 }
1190 }
1191 unsafe { InstancePre::new(module, imports) }
1192 }
1193
1194 /// Returns an iterator over all items defined in this `Linker`, in
1195 /// arbitrary order.
1196 ///
1197 /// The iterator returned will yield 3-tuples where the first two elements
1198 /// are the module name and item name for the external item, and the third
1199 /// item is the item itself that is defined.
1200 ///
1201 /// Note that multiple `Extern` items may be defined for the same
1202 /// module/name pair.
1203 ///
1204 /// # Panics
1205 ///
1206 /// This function will panic if the `store` provided does not come from the
1207 /// same [`Engine`] that this linker was created with.
1208 pub fn iter<'a: 'p, 'p>(
1209 &'a self,
1210 mut store: impl AsContextMut<Data = T> + 'p,
1211 ) -> impl Iterator<Item = (&str, &str, Extern)> + 'p {
1212 self.map.iter().map(move |(key, item)| {
1213 let store = store.as_context_mut();
1214 (
1215 &*self.strings[key.module],
1216 &*self.strings[key.name],
1217 // Should be safe since `T` is connecting the linker and store
1218 unsafe { item.to_extern(store.0) },
1219 )
1220 })
1221 }
1222
1223 /// Looks up a previously defined value in this [`Linker`], identified by
1224 /// the names provided.
1225 ///
1226 /// Returns `None` if this name was not previously defined in this
1227 /// [`Linker`].
1228 ///
1229 /// # Panics
1230 ///
1231 /// This function will panic if the `store` provided does not come from the
1232 /// same [`Engine`] that this linker was created with.
1233 pub fn get(
1234 &self,
1235 mut store: impl AsContextMut<Data = T>,
1236 module: &str,
1237 name: &str,
1238 ) -> Option<Extern> {
1239 let store = store.as_context_mut().0;
1240 // Should be safe since `T` is connecting the linker and store
1241 Some(unsafe { self._get(module, name)?.to_extern(store) })
1242 }
1243
1244 fn _get(&self, module: &str, name: &str) -> Option<&Definition> {
1245 let key = ImportKey {
1246 module: *self.string2idx.get(module)?,
1247 name: *self.string2idx.get(name)?,
1248 };
1249 self.map.get(&key)
1250 }
1251
1252 /// Looks up a value in this `Linker` which matches the `import` type
1253 /// provided.
1254 ///
1255 /// Returns `None` if no match was found.
1256 ///
1257 /// # Panics
1258 ///
1259 /// This function will panic if the `store` provided does not come from the
1260 /// same [`Engine`] that this linker was created with.
1261 pub fn get_by_import(
1262 &self,
1263 mut store: impl AsContextMut<Data = T>,
1264 import: &ImportType,
1265 ) -> Option<Extern> {
1266 let store = store.as_context_mut().0;
1267 // Should be safe since `T` is connecting the linker and store
1268 Some(unsafe { self._get_by_import(import).ok()?.to_extern(store) })
1269 }
1270
1271 fn _get_by_import(&self, import: &ImportType) -> Result<Definition, UnknownImportError> {
1272 match self._get(import.module(), import.name()) {
1273 Some(item) => Ok(item.clone()),
1274 None => Err(UnknownImportError::new(import)),
1275 }
1276 }
1277
1278 /// Returns the "default export" of a module.
1279 ///
1280 /// An export with an empty string is considered to be a "default export".
1281 /// "_start" is also recognized for compatibility.
1282 ///
1283 /// # Panics
1284 ///
1285 /// Panics if the default function found is not owned by `store`. This
1286 /// function will also panic if the `store` provided does not come from the
1287 /// same [`Engine`] that this linker was created with.
1288 pub fn get_default(
1289 &self,
1290 mut store: impl AsContextMut<Data = T>,
1291 module: &str,
1292 ) -> Result<Func> {
1293 if let Some(external) = self.get(&mut store, module, "") {
1294 if let Extern::Func(func) = external {
1295 return Ok(func.clone());
1296 }
1297 bail!("default export in '{}' is not a function", module);
1298 }
1299
1300 // For compatibility, also recognize "_start".
1301 if let Some(external) = self.get(&mut store, module, "_start") {
1302 if let Extern::Func(func) = external {
1303 return Ok(func.clone());
1304 }
1305 bail!("`_start` in '{}' is not a function", module);
1306 }
1307
1308 // Otherwise return a no-op function.
1309 Ok(Func::wrap(store, || {}))
1310 }
1311}
1312
1313impl<T> Default for Linker<T> {
1314 fn default() -> Linker<T> {
1315 Linker::new(&Engine::default())
1316 }
1317}
1318
1319impl Definition {
1320 fn new(store: &StoreOpaque, item: Extern) -> Definition {
1321 let ty = DefinitionType::from(store, &item);
1322 Definition::Extern(item, ty)
1323 }
1324
1325 pub(crate) fn ty(&self) -> DefinitionType {
1326 match self {
1327 Definition::Extern(_, ty) => ty.clone(),
1328 Definition::HostFunc(func) => DefinitionType::Func(func.sig_index()),
1329 }
1330 }
1331
1332 /// Note the unsafety here is due to calling `HostFunc::to_func`. The
1333 /// requirement here is that the `T` that was originally used to create the
1334 /// `HostFunc` matches the `T` on the store.
1335 pub(crate) unsafe fn to_extern(&self, store: &mut StoreOpaque) -> Extern {
1336 match self {
1337 Definition::Extern(e, _) => e.clone(),
1338 Definition::HostFunc(func) => func.to_func(store).into(),
1339 }
1340 }
1341
1342 /// Note the unsafety here is due to calling
1343 /// `HostFunc::to_func_store_rooted`.
1344 pub(crate) unsafe fn to_extern_store_rooted(&self, store: &mut StoreOpaque) -> Extern {
1345 match self {
1346 Definition::Extern(e, _) => e.clone(),
1347 Definition::HostFunc(func) => func.to_func_store_rooted(store).into(),
1348 }
1349 }
1350
1351 pub(crate) fn comes_from_same_store(&self, store: &StoreOpaque) -> bool {
1352 match self {
1353 Definition::Extern(e, _) => e.comes_from_same_store(store),
1354 Definition::HostFunc(_func) => true,
1355 }
1356 }
1357
1358 fn update_size(&mut self, store: &StoreOpaque) {
1359 match self {
1360 Definition::Extern(Extern::Memory(m), DefinitionType::Memory(_, size)) => {
1361 *size = m.internal_size(store);
1362 }
1363 Definition::Extern(Extern::SharedMemory(m), DefinitionType::Memory(_, size)) => {
1364 *size = m.size();
1365 }
1366 Definition::Extern(Extern::Table(m), DefinitionType::Table(_, size)) => {
1367 *size = m.internal_size(store);
1368 }
1369 _ => {}
1370 }
1371 }
1372}
1373
1374impl DefinitionType {
1375 pub(crate) fn from(store: &StoreOpaque, item: &Extern) -> DefinitionType {
1376 let data = store.store_data();
1377 match item {
1378 Extern::Func(f) => DefinitionType::Func(f.sig_index(data)),
1379 Extern::Table(t) => DefinitionType::Table(*t.wasmtime_ty(data), t.internal_size(store)),
1380 Extern::Global(t) => DefinitionType::Global(*t.wasmtime_ty(data)),
1381 Extern::Memory(t) => {
1382 DefinitionType::Memory(*t.wasmtime_ty(data), t.internal_size(store))
1383 }
1384 Extern::SharedMemory(t) => DefinitionType::Memory(*t.ty().wasmtime_memory(), t.size()),
1385 }
1386 }
1387
1388 pub(crate) fn desc(&self) -> &'static str {
1389 match self {
1390 DefinitionType::Func(_) => "function",
1391 DefinitionType::Table(..) => "table",
1392 DefinitionType::Memory(..) => "memory",
1393 DefinitionType::Global(_) => "global",
1394 }
1395 }
1396}
1397
1398/// Modules can be interpreted either as Commands or Reactors.
1399enum ModuleKind {
1400 /// The instance is a Command, meaning an instance is created for each
1401 /// exported function and lives for the duration of the function call.
1402 Command,
1403
1404 /// The instance is a Reactor, meaning one instance is created which
1405 /// may live across multiple calls.
1406 Reactor,
1407}
1408
1409impl ModuleKind {
1410 /// Determine whether the given module is a Command or a Reactor.
1411 fn categorize(module: &Module) -> Result<ModuleKind> {
1412 let command_start = module.get_export("_start");
1413 let reactor_start = module.get_export("_initialize");
1414 match (command_start, reactor_start) {
1415 (Some(command_start), None) => {
1416 if let Some(_) = command_start.func() {
1417 Ok(ModuleKind::Command)
1418 } else {
1419 bail!("`_start` must be a function")
1420 }
1421 }
1422 (None, Some(reactor_start)) => {
1423 if let Some(_) = reactor_start.func() {
1424 Ok(ModuleKind::Reactor)
1425 } else {
1426 bail!("`_initialize` must be a function")
1427 }
1428 }
1429 (None, None) => {
1430 // Module declares neither of the recognized functions, so treat
1431 // it as a reactor with no initialization function.
1432 Ok(ModuleKind::Reactor)
1433 }
1434 (Some(_), Some(_)) => {
1435 // Module declares itself to be both a Command and a Reactor.
1436 bail!("Program cannot be both a Command and a Reactor")
1437 }
1438 }
1439 }
1440}
1441
1442/// Error for an unresolvable import.
1443///
1444/// Returned - wrapped in an [`anyhow::Error`] - by [`Linker::instantiate`] and
1445/// related methods for modules with unresolvable imports.
1446#[derive(Clone, Debug)]
1447pub struct UnknownImportError {
1448 module: String,
1449 name: String,
1450 ty: ExternType,
1451}
1452
1453impl UnknownImportError {
1454 fn new(import: &ImportType) -> Self {
1455 Self {
1456 module: import.module().to_string(),
1457 name: import.name().to_string(),
1458 ty: import.ty(),
1459 }
1460 }
1461
1462 /// Returns the module name that the unknown import was expected to come from.
1463 pub fn module(&self) -> &str {
1464 &self.module
1465 }
1466
1467 /// Returns the field name of the module that the unknown import was expected to come from.
1468 pub fn name(&self) -> &str {
1469 &self.name
1470 }
1471
1472 /// Returns the type of the unknown import.
1473 pub fn ty(&self) -> ExternType {
1474 self.ty.clone()
1475 }
1476}
1477
1478impl std::fmt::Display for UnknownImportError {
1479 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1480 write!(
1481 f,
1482 "unknown import: `{}::{}` has not been defined",
1483 self.module, self.name,
1484 )
1485 }
1486}
1487
1488impl std::error::Error for UnknownImportError {}