wasmtime/runtime/component/linker.rs
1#[cfg(feature = "component-model-async")]
2use crate::component::concurrent::Accessor;
3use crate::component::func::HostFunc;
4use crate::component::instance::RuntimeImport;
5use crate::component::matching::{InstanceType, TypeChecker};
6use crate::component::types;
7use crate::component::{
8 Component, ComponentNamedList, Instance, InstancePre, Lift, Lower, ResourceType, Val,
9};
10use crate::prelude::*;
11use crate::{AsContextMut, Engine, Module, StoreContextMut};
12use alloc::sync::Arc;
13use core::marker;
14#[cfg(feature = "component-model-async")]
15use core::pin::Pin;
16use wasmtime_environ::component::NameMap;
17use wasmtime_environ::{Atom, PrimaryMap, StringPool};
18
19/// A type used to instantiate [`Component`]s.
20///
21/// This type is used to both link components together as well as supply host
22/// functionality to components. Values are defined in a [`Linker`] by their
23/// import name and then components are instantiated with a [`Linker`] using the
24/// names provided for name resolution of the component's imports.
25///
26/// # Names and Semver
27///
28/// Names defined in a [`Linker`] correspond to import names in the Component
29/// Model. Names in the Component Model are allowed to be semver-qualified, for
30/// example:
31///
32/// * `wasi:cli/stdout@0.2.0`
33/// * `wasi:http/types@0.2.0-rc-2023-10-25`
34/// * `my:custom/plugin@1.0.0-pre.2`
35///
36/// These version strings are taken into account when looking up names within a
37/// [`Linker`]. You're allowed to define any number of versions within a
38/// [`Linker`] still, for example you can define `a:b/c@0.2.0`, `a:b/c@0.2.1`,
39/// and `a:b/c@0.3.0` all at the same time.
40///
41/// Specifically though when names are looked up within a linker, for example
42/// during instantiation, semver-compatible names are automatically consulted.
43/// This means that if you define `a:b/c@0.2.1` in a [`Linker`] but a component
44/// imports `a:b/c@0.2.0` then that import will resolve to the `0.2.1` version.
45///
46/// This lookup behavior relies on hosts being well-behaved when using Semver,
47/// specifically that interfaces once defined are never changed. This reflects
48/// how Semver works at the Component Model layer, and it's assumed that if
49/// versions are present then hosts are respecting this.
50///
51/// Note that this behavior goes the other direction, too. If a component
52/// imports `a:b/c@0.2.1` and the host has provided `a:b/c@0.2.0` then that
53/// will also resolve correctly. This is because if an API was defined at 0.2.0
54/// and 0.2.1 then it must be the same API.
55///
56/// This behavior is intended to make it easier for hosts to upgrade WASI and
57/// for guests to upgrade WASI. So long as the actual "meat" of the
58/// functionality is defined then it should align correctly and components can
59/// be instantiated.
60pub struct Linker<T: 'static> {
61 engine: Engine,
62 strings: StringPool,
63 map: NameMap<Atom, Definition>,
64 path: Vec<Atom>,
65 allow_shadowing: bool,
66 _marker: marker::PhantomData<fn() -> T>,
67}
68
69impl<T: 'static> Clone for Linker<T> {
70 fn clone(&self) -> Linker<T> {
71 Linker {
72 engine: self.engine.clone(),
73 strings: self.strings.clone_panic_on_oom(),
74 map: self.map.clone_panic_on_oom(),
75 path: self.path.clone(),
76 allow_shadowing: self.allow_shadowing,
77 _marker: self._marker,
78 }
79 }
80}
81
82/// Structure representing an "instance" being defined within a linker.
83///
84/// Instances do not need to be actual [`Instance`]s and instead are defined by
85/// a "bag of named items", so each [`LinkerInstance`] can further define items
86/// internally.
87pub struct LinkerInstance<'a, T: 'static> {
88 engine: &'a Engine,
89 path: &'a mut Vec<Atom>,
90 path_len: usize,
91 strings: &'a mut StringPool,
92 map: &'a mut NameMap<Atom, Definition>,
93 allow_shadowing: bool,
94 _marker: marker::PhantomData<fn() -> T>,
95}
96
97#[derive(Debug)]
98pub(crate) enum Definition {
99 Instance(NameMap<Atom, Definition>),
100 Func(Arc<HostFunc>),
101 Module(Module),
102 Resource(ResourceType, Arc<crate::func::HostFunc>),
103}
104
105impl TryClone for Definition {
106 fn try_clone(&self) -> Result<Self, OutOfMemory> {
107 Ok(match self {
108 Self::Instance(i) => Self::Instance(i.try_clone()?),
109 Self::Func(f) => Self::Func(f.try_clone()?),
110 Self::Module(m) => Self::Module(m.clone()),
111 Self::Resource(r, f) => Self::Resource(*r, f.try_clone()?),
112 })
113 }
114}
115
116impl<T: 'static> Linker<T> {
117 /// Creates a new linker for the [`Engine`] specified with no items defined
118 /// within it.
119 pub fn new(engine: &Engine) -> Linker<T> {
120 Linker {
121 engine: engine.clone(),
122 strings: StringPool::default(),
123 map: NameMap::default(),
124 allow_shadowing: false,
125 path: Vec::new(),
126 _marker: marker::PhantomData,
127 }
128 }
129
130 /// Returns the [`Engine`] this is connected to.
131 pub fn engine(&self) -> &Engine {
132 &self.engine
133 }
134
135 /// Configures whether or not name-shadowing is allowed.
136 ///
137 /// By default name shadowing is not allowed and it's an error to redefine
138 /// the same name within a linker.
139 pub fn allow_shadowing(&mut self, allow: bool) -> &mut Self {
140 self.allow_shadowing = allow;
141 self
142 }
143
144 /// Returns the "root instance" of this linker, used to define names into
145 /// the root namespace.
146 pub fn root(&mut self) -> LinkerInstance<'_, T> {
147 LinkerInstance {
148 engine: &self.engine,
149 path: &mut self.path,
150 path_len: 0,
151 strings: &mut self.strings,
152 map: &mut self.map,
153 allow_shadowing: self.allow_shadowing,
154 _marker: self._marker,
155 }
156 }
157
158 /// Returns a builder for the named instance specified.
159 ///
160 /// # Errors
161 ///
162 /// Returns an error if `name` is already defined within the linker.
163 pub fn instance(&mut self, name: &str) -> Result<LinkerInstance<'_, T>> {
164 self.root().into_instance(name)
165 }
166
167 fn typecheck<'a>(&'a self, component: &'a Component) -> Result<TypeChecker<'a>> {
168 let mut cx = TypeChecker {
169 engine: &self.engine,
170 types: component.types(),
171 strings: &self.strings,
172 imported_resources: try_new::<Arc<_>>(TryPrimaryMap::new())?,
173 };
174
175 // Walk over the component's list of import names and use that to lookup
176 // the definition within this linker that it corresponds to. When found
177 // perform a typecheck against the component's expected type.
178 let env_component = component.env_component();
179 for (_idx, (name, ty)) in env_component.import_types.iter() {
180 let import = self.map.get(name, &self.strings);
181 cx.definition(&ty.ty, import).with_context(|| {
182 format!(
183 "component imports {desc} `{name}`, but \
184 a matching implementation was not found in the linker",
185 desc = ty.ty.desc()
186 )
187 })?;
188 }
189 Ok(cx)
190 }
191
192 /// Returns the [`types::Component`] corresponding to `component` with resource
193 /// types imported by it replaced using imports present in [`Self`].
194 ///
195 /// # Errors
196 ///
197 /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
198 /// memory allocation fails. See the `OutOfMemory` type's documentation for
199 /// details on Wasmtime's out-of-memory handling.
200 pub fn substituted_component_type(&self, component: &Component) -> Result<types::Component> {
201 let cx = self.typecheck(&component)?;
202 Ok(types::Component::from(
203 component.ty(),
204 &InstanceType {
205 types: cx.types,
206 resources: Some(&cx.imported_resources),
207 },
208 ))
209 }
210
211 /// Performs a "pre-instantiation" to resolve the imports of the
212 /// [`Component`] specified with the items defined within this linker.
213 ///
214 /// This method will perform as much work as possible short of actually
215 /// instantiating an instance. Internally this will use the names defined
216 /// within this linker to satisfy the imports of the [`Component`] provided.
217 /// Additionally this will perform type-checks against the component's
218 /// imports against all items defined within this linker.
219 ///
220 /// Note that unlike internally in components where subtyping at the
221 /// interface-types layer is supported this is not supported here. Items
222 /// defined in this linker must match the component's imports precisely.
223 ///
224 /// # Errors
225 ///
226 /// Returns an error if this linker doesn't define a name that the
227 /// `component` imports or if a name defined doesn't match the type of the
228 /// item imported by the `component` provided.
229 ///
230 /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
231 /// memory allocation fails. See the `OutOfMemory` type's documentation for
232 /// details on Wasmtime's out-of-memory handling.
233 pub fn instantiate_pre(&self, component: &Component) -> Result<InstancePre<T>> {
234 let cx = self.typecheck(&component)?;
235
236 // A successful typecheck resolves all of the imported resources used by
237 // this InstancePre. We keep a clone of this table in the InstancePre
238 // so that we can construct an InstanceType for typechecking.
239 let imported_resources = cx.imported_resources.clone();
240
241 // Now that all imports are known to be defined and satisfied by this
242 // linker a list of "flat" import items (aka no instances) is created
243 // using the import map within the component created at
244 // component-compile-time.
245 let env_component = component.env_component();
246 let mut imports = PrimaryMap::with_capacity(env_component.imports.len());
247 for (idx, (import, names)) in env_component.imports.iter() {
248 let (root, _) = &env_component.import_types[*import];
249
250 // This is the flattening process where we go from a definition
251 // optionally through a list of exported names to get to the final
252 // item.
253 let mut cur = self.map.get(root, &self.strings).unwrap();
254 for name in names {
255 cur = match cur {
256 Definition::Instance(map) => map.get(&name, &self.strings).unwrap(),
257 _ => unreachable!(),
258 };
259 }
260 let import = match cur {
261 Definition::Module(m) => RuntimeImport::Module(m.clone()),
262 Definition::Func(f) => RuntimeImport::Func(f.clone()),
263 Definition::Resource(t, dtor) => RuntimeImport::Resource {
264 ty: *t,
265 dtor: dtor.clone(),
266 dtor_funcref: component.resource_drop_func_ref(dtor),
267 },
268
269 // This is guaranteed by the compilation process that "leaf"
270 // runtime imports are never instances.
271 Definition::Instance(_) => unreachable!(),
272 };
273 let i = imports.push(import);
274 assert_eq!(i, idx);
275 }
276 Ok(unsafe {
277 InstancePre::new_unchecked(
278 component.clone(),
279 try_new::<Arc<_>>(imports)?,
280 imported_resources,
281 )
282 })
283 }
284
285 /// Instantiates the [`Component`] provided into the `store` specified.
286 ///
287 /// This function will use the items defined within this [`Linker`] to
288 /// satisfy the imports of the [`Component`] provided as necessary. For more
289 /// information about this see [`Linker::instantiate_pre`] as well.
290 ///
291 /// # Errors
292 ///
293 /// Returns an error if this [`Linker`] doesn't define an import that
294 /// `component` requires or if it is of the wrong type. Additionally this
295 /// can return an error if something goes wrong during instantiation such as
296 /// a runtime trap or a runtime limit being exceeded.
297 ///
298 /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
299 /// memory allocation fails. See the `OutOfMemory` type's documentation for
300 /// details on Wasmtime's out-of-memory handling.
301 pub fn instantiate(
302 &self,
303 mut store: impl AsContextMut<Data = T>,
304 component: &Component,
305 ) -> Result<Instance> {
306 let store = store.as_context_mut();
307 store.0.validate_sync_call()?;
308 self.instantiate_pre(component)?.instantiate(store)
309 }
310
311 /// Instantiates the [`Component`] provided into the `store` specified.
312 ///
313 /// This is exactly like [`Linker::instantiate`] except for [asynchronous
314 /// execution](crate#async).
315 ///
316 /// # Errors
317 ///
318 /// Returns an error if this [`Linker`] doesn't define an import that
319 /// `component` requires or if it is of the wrong type. Additionally this
320 /// can return an error if something goes wrong during instantiation such as
321 /// a runtime trap or a runtime limit being exceeded.
322 ///
323 /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
324 /// memory allocation fails. See the `OutOfMemory` type's documentation for
325 /// details on Wasmtime's out-of-memory handling.
326 #[cfg(feature = "async")]
327 pub async fn instantiate_async(
328 &self,
329 store: impl AsContextMut<Data = T>,
330 component: &Component,
331 ) -> Result<Instance>
332 where
333 T: Send,
334 {
335 self.instantiate_pre(component)?
336 .instantiate_async(store)
337 .await
338 }
339
340 /// Implement any imports of the given [`Component`] with a function which traps.
341 ///
342 /// By default a [`Linker`] will error when unknown imports are encountered when instantiating a [`Component`].
343 /// This changes this behavior from an instant error to a trap that will happen if the import is called.
344 ///
345 /// # Errors
346 ///
347 /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
348 /// memory allocation fails. See the `OutOfMemory` type's documentation for
349 /// details on Wasmtime's out-of-memory handling.
350 pub fn define_unknown_imports_as_traps(&mut self, component: &Component) -> Result<()> {
351 use wasmtime_environ::component::ComponentTypes;
352 use wasmtime_environ::component::TypeDef;
353 // Recursively stub out all imports of the component with a function that traps.
354 fn stub_item<T>(
355 linker: &mut LinkerInstance<T>,
356 item_name: &str,
357 item_def: &TypeDef,
358 parent_instance: Option<&str>,
359 types: &ComponentTypes,
360 ) -> Result<()> {
361 // Skip if the item isn't an instance and has already been defined in the linker.
362 if !matches!(item_def, TypeDef::ComponentInstance(_)) && linker.get(item_name).is_some()
363 {
364 return Ok(());
365 }
366
367 match item_def {
368 TypeDef::ComponentFunc(_) => {
369 let fully_qualified_name = match parent_instance {
370 Some(parent) => {
371 let mut s = TryString::new();
372 s.push_str(parent)?;
373 s.push('#')?;
374 s.push_str(item_name)?;
375 s
376 }
377 None => {
378 let mut s = TryString::new();
379 s.push_str(item_name)?;
380 s
381 }
382 };
383 linker.func_new(&item_name, move |_, _, _, _| {
384 bail!("unknown import: `{fully_qualified_name}` has not been defined")
385 })?;
386 }
387 TypeDef::ComponentInstance(i) => {
388 let instance = &types[*i];
389 let mut linker_instance = linker.instance(item_name)?;
390 for (export_name, export) in instance.exports.iter() {
391 stub_item(
392 &mut linker_instance,
393 export_name,
394 &export.ty,
395 Some(item_name),
396 types,
397 )?;
398 }
399 }
400 TypeDef::Resource(_) => {
401 let ty = crate::component::ResourceType::host::<()>();
402 linker.resource(item_name, ty, |_, _| Ok(()))?;
403 }
404 TypeDef::Component(_) | TypeDef::Module(_) => {
405 bail!("unable to define {} imports as traps", item_def.desc())
406 }
407 _ => {}
408 }
409 Ok(())
410 }
411
412 for (_, (import_name, import_type)) in &component.env_component().import_types {
413 stub_item(
414 &mut self.root(),
415 import_name,
416 &import_type.ty,
417 None,
418 component.types(),
419 )?;
420 }
421 Ok(())
422 }
423}
424
425impl<T: 'static> LinkerInstance<'_, T> {
426 fn as_mut(&mut self) -> LinkerInstance<'_, T> {
427 LinkerInstance {
428 engine: self.engine,
429 path: self.path,
430 path_len: self.path_len,
431 strings: self.strings,
432 map: self.map,
433 allow_shadowing: self.allow_shadowing,
434 _marker: self._marker,
435 }
436 }
437
438 /// Defines a new host-provided function into this [`LinkerInstance`].
439 ///
440 /// This method is used to give host functions to wasm components. The
441 /// `func` provided will be callable from linked components with the type
442 /// signature dictated by `Params` and `Return`. The `Params` is a tuple of
443 /// types that will come from wasm and `Return` is a value coming from the
444 /// host going back to wasm.
445 ///
446 /// Additionally the `func` takes a
447 /// [`StoreContextMut`](crate::StoreContextMut) as its first parameter.
448 ///
449 /// Note that `func` must be an `Fn` and must also be `Send + Sync +
450 /// 'static`. Shared state within a func is typically accessed with the `T`
451 /// type parameter from [`Store<T>`](crate::Store) which is accessible
452 /// through the leading [`StoreContextMut<'_, T>`](crate::StoreContextMut)
453 /// argument which can be provided to the `func` given here.
454 ///
455 /// # Blocking / Async Behavior
456 ///
457 /// The host function `func` provided here is a blocking function from the
458 /// perspective of WebAssembly. WebAssembly, and Rust, will be blocked until
459 /// `func` completes.
460 ///
461 /// To define a function which is async on the host, but blocking to the
462 /// guest, see the [`func_wrap_async`] method.
463 ///
464 /// [`func_wrap_async`]: LinkerInstance::func_wrap_async
465 ///
466 /// # Errors
467 ///
468 /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
469 /// memory allocation fails. See the `OutOfMemory` type's documentation for
470 /// details on Wasmtime's out-of-memory handling.
471 //
472 // TODO: needs more words and examples
473 pub fn func_wrap<F, Params, Return>(&mut self, name: &str, func: F) -> Result<()>
474 where
475 F: Fn(StoreContextMut<T>, Params) -> Result<Return> + Send + Sync + 'static,
476 Params: ComponentNamedList + Lift + 'static,
477 Return: ComponentNamedList + Lower + 'static,
478 {
479 self.insert(name, Definition::Func(HostFunc::func_wrap(func)?))?;
480 Ok(())
481 }
482
483 /// Defines a new host-provided async function into this [`LinkerInstance`].
484 ///
485 /// This function is similar to [`Self::func_wrap`] except it takes an async
486 /// host function instead of a blocking host function. The `F` function here
487 /// is intended to be:
488 ///
489 /// ```ignore
490 /// F: AsyncFn(StoreContextMut<'_, T>, Params) -> Result<Return>
491 /// ```
492 ///
493 /// however the returned future must be `Send` which is not possible to
494 /// bound at this time. This will be switched to an async closure once Rust
495 /// supports it.
496 ///
497 /// # Blocking / Async Behavior
498 ///
499 /// The function defined which WebAssembly calls will still appear as
500 /// blocking from the perspective of WebAssembly itself. The host, however,
501 /// can perform asynchronous operations without blocking the thread
502 /// performing a call.
503 ///
504 /// When defining host functions with this function, WebAssembly is invoked
505 /// on a separate stack within a Wasmtime-managed fiber (through the
506 /// `call_async`-style of invocation). This means that if the future
507 /// returned by `F` is not immediately ready then the fiber will be
508 /// suspended to block WebAssembly but not the host. When the future
509 /// becomes ready again the fiber will be resumed to continue execution
510 /// within WebAssembly.
511 ///
512 /// [`func_wrap_async`]: LinkerInstance::func_wrap_async
513 #[cfg(feature = "async")]
514 pub fn func_wrap_async<Params, Return, F>(&mut self, name: &str, f: F) -> Result<()>
515 where
516 F: Fn(
517 StoreContextMut<'_, T>,
518 Params,
519 ) -> Box<dyn Future<Output = Result<Return>> + Send + '_>
520 + Send
521 + Sync
522 + 'static,
523 Params: ComponentNamedList + Lift + 'static,
524 Return: ComponentNamedList + Lower + 'static,
525 {
526 self.insert(name, Definition::Func(HostFunc::func_wrap_async(f)?))?;
527 Ok(())
528 }
529
530 /// Defines a new host-provided async function into this [`LinkerInstance`].
531 ///
532 /// This function defines a host function available to call from
533 /// WebAssembly. WebAssembly may additionally make multiple invocations of
534 /// this function concurrently all at the same time. This function requires
535 /// the [`Config::wasm_component_model_async`] feature to be enabled.
536 ///
537 /// The function `f` provided will be invoked when called by WebAssembly.
538 /// WebAssembly components may then call `f` multiple times while previous
539 /// invocations of `f` are already running. Additionally while `f` is
540 /// running other host functions may be invoked.
541 ///
542 /// The `F` function here is intended to be:
543 ///
544 /// ```ignore
545 /// F: AsyncFn(&Accessor<T>, Params) -> Result<Return>
546 /// ```
547 ///
548 /// however the returned future must be `Send` which is not possible to
549 /// bound at this time. This will be switched to an async closure once Rust
550 /// supports it.
551 ///
552 /// The closure `f` is provided an [`Accessor`] which can be used to acquire
553 /// temporary, blocking, access to a [`StoreContextMut`] (through
554 /// [`Access`](crate::component::Access]). This models how a store is not
555 /// available to `f` across `await` points but it is temporarily available
556 /// while actively being polled.
557 ///
558 /// # Blocking / Async Behavior
559 ///
560 /// Unlike [`Self::func_wrap`] and [`Self::func_wrap_async`] this function
561 /// is asynchronous even from the perspective of guest WebAssembly. This
562 /// means that if `f` is not immediately resolved then the call from
563 /// WebAssembly will still return immediately (assuming it was lowered with
564 /// `async`). The closure `f` should not block the current thread and
565 /// should only perform blocking via `async` meaning that `f` won't block
566 /// either WebAssembly nor the host.
567 ///
568 /// Note that WebAssembly components can lower host functions both with and
569 /// without `async`. That means that even if a host function is defined in
570 /// the "concurrent" mode here a guest may still lower it synchronously. In
571 /// this situation Wasmtime will manage blocking the guest while the closure
572 /// `f` provided here completes. If a guest lowers this function with
573 /// `async`, though, then no blocking will happen.
574 ///
575 /// [`Config::wasm_component_model_async`]: crate::Config::wasm_component_model_async
576 /// [`func_wrap_async`]: LinkerInstance::func_wrap_async
577 #[cfg(feature = "component-model-async")]
578 pub fn func_wrap_concurrent<Params, Return, F>(&mut self, name: &str, f: F) -> Result<()>
579 where
580 T: 'static,
581 F: Fn(&Accessor<T>, Params) -> Pin<Box<dyn Future<Output = Result<Return>> + Send + '_>>
582 + Send
583 + Sync
584 + 'static,
585 Params: ComponentNamedList + Lift + 'static,
586 Return: ComponentNamedList + Lower + 'static,
587 {
588 if !self.engine.tunables().concurrency_support {
589 bail!("concurrent host functions require `Config::concurrency_support`");
590 }
591 self.insert(name, Definition::Func(HostFunc::func_wrap_concurrent(f)?))?;
592 Ok(())
593 }
594
595 /// Define a new host-provided function using dynamically typed values.
596 ///
597 /// The `name` provided is the name of the function to define and the
598 /// `func` provided is the host-defined closure to invoke when this
599 /// function is called.
600 ///
601 /// This function is the "dynamic" version of defining a host function as
602 /// compared to [`LinkerInstance::func_wrap`]. With
603 /// [`LinkerInstance::func_wrap`] a function's type is statically known but
604 /// with this method the `func` argument's type isn't known ahead of time.
605 /// That means that `func` can be by imported component so long as it's
606 /// imported as a matching name.
607 ///
608 /// Type information will be available at execution time, however. For
609 /// example when `func` is invoked the second argument, a `&[Val]` list,
610 /// contains [`Val`] entries that say what type they are. Additionally the
611 /// third argument, `&mut [Val]`, is the expected number of results. Note
612 /// that the expected types of the results cannot be learned during the
613 /// execution of `func`. Learning that would require runtime introspection
614 /// of a component.
615 ///
616 /// Return values, stored in the third argument of `&mut [Val]`, are
617 /// type-checked at runtime to ensure that they have the appropriate type.
618 /// A trap will be raised if they do not have the right type.
619 ///
620 /// # Examples
621 ///
622 /// ```
623 /// use wasmtime::{Store, Engine};
624 /// use wasmtime::component::{Component, Linker, Val};
625 ///
626 /// # fn main() -> wasmtime::Result<()> {
627 /// let engine = Engine::default();
628 /// let component = Component::new(
629 /// &engine,
630 /// r#"
631 /// (component
632 /// (import "thunk" (func $thunk))
633 /// (import "is-even" (func $is-even (param "x" u32) (result bool)))
634 ///
635 /// (core module $m
636 /// (import "" "thunk" (func $thunk))
637 /// (import "" "is-even" (func $is-even (param i32) (result i32)))
638 ///
639 /// (func (export "run")
640 /// call $thunk
641 ///
642 /// (call $is-even (i32.const 1))
643 /// if unreachable end
644 ///
645 /// (call $is-even (i32.const 2))
646 /// i32.eqz
647 /// if unreachable end
648 /// )
649 /// )
650 /// (core func $thunk (canon lower (func $thunk)))
651 /// (core func $is-even (canon lower (func $is-even)))
652 /// (core instance $i (instantiate $m
653 /// (with "" (instance
654 /// (export "thunk" (func $thunk))
655 /// (export "is-even" (func $is-even))
656 /// ))
657 /// ))
658 ///
659 /// (func (export "run") (canon lift (core func $i "run")))
660 /// )
661 /// "#,
662 /// )?;
663 ///
664 /// let mut linker = Linker::<()>::new(&engine);
665 ///
666 /// // Sample function that takes no arguments.
667 /// linker.root().func_new("thunk", |_store, _ty, params, results| {
668 /// assert!(params.is_empty());
669 /// assert!(results.is_empty());
670 /// println!("Look ma, host hands!");
671 /// Ok(())
672 /// })?;
673 ///
674 /// // This function takes one argument and returns one result.
675 /// linker.root().func_new("is-even", |_store, _ty, params, results| {
676 /// assert_eq!(params.len(), 1);
677 /// let param = match params[0] {
678 /// Val::U32(n) => n,
679 /// _ => panic!("unexpected type"),
680 /// };
681 ///
682 /// assert_eq!(results.len(), 1);
683 /// results[0] = Val::Bool(param % 2 == 0);
684 /// Ok(())
685 /// })?;
686 ///
687 /// let mut store = Store::new(&engine, ());
688 /// let instance = linker.instantiate(&mut store, &component)?;
689 /// let run = instance.get_typed_func::<(), ()>(&mut store, "run")?;
690 /// run.call(&mut store, ())?;
691 /// # Ok(())
692 /// # }
693 /// ```
694 ///
695 /// # Errors
696 ///
697 /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
698 /// memory allocation fails. See the `OutOfMemory` type's documentation for
699 /// details on Wasmtime's out-of-memory handling.
700 pub fn func_new(
701 &mut self,
702 name: &str,
703 func: impl Fn(StoreContextMut<'_, T>, types::ComponentFunc, &[Val], &mut [Val]) -> Result<()>
704 + Send
705 + Sync
706 + 'static,
707 ) -> Result<()> {
708 self.insert(name, Definition::Func(HostFunc::func_new(func)?))?;
709 Ok(())
710 }
711
712 /// Define a new host-provided async function using dynamic types.
713 ///
714 /// As [`Self::func_wrap_async`] is a dual of [`Self::func_wrap`], this
715 /// function is the dual of [`Self::func_new`].
716 ///
717 /// For documentation on blocking behavior see [`Self::func_wrap_async`].
718 #[cfg(feature = "async")]
719 pub fn func_new_async<F>(&mut self, name: &str, func: F) -> Result<()>
720 where
721 F: for<'a> Fn(
722 StoreContextMut<'a, T>,
723 types::ComponentFunc,
724 &'a [Val],
725 &'a mut [Val],
726 ) -> Box<dyn Future<Output = Result<()>> + Send + 'a>
727 + Send
728 + Sync
729 + 'static,
730 {
731 self.insert(name, Definition::Func(HostFunc::func_new_async(func)?))?;
732 Ok(())
733 }
734
735 /// Define a new host-provided async function using dynamic types.
736 ///
737 /// As [`Self::func_wrap_concurrent`] is a dual of [`Self::func_wrap`], this
738 /// function is the dual of [`Self::func_new`].
739 ///
740 /// For documentation on async/blocking behavior see
741 /// [`Self::func_wrap_concurrent`].
742 #[cfg(feature = "component-model-async")]
743 pub fn func_new_concurrent<F>(&mut self, name: &str, f: F) -> Result<()>
744 where
745 T: 'static,
746 F: for<'a> Fn(
747 &'a Accessor<T>,
748 types::ComponentFunc,
749 &'a [Val],
750 &'a mut [Val],
751 ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'a>>
752 + Send
753 + Sync
754 + 'static,
755 {
756 if !self.engine.tunables().concurrency_support {
757 bail!("concurrent host functions require `Config::concurrency_support`");
758 }
759 self.insert(name, Definition::Func(HostFunc::func_new_concurrent(f)?))?;
760 Ok(())
761 }
762
763 /// Defines a [`Module`] within this instance.
764 ///
765 /// This can be used to provide a core wasm [`Module`] as an import to a
766 /// component. The [`Module`] provided is saved within the linker for the
767 /// specified `name` in this instance.
768 ///
769 /// # Errors
770 ///
771 /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
772 /// memory allocation fails. See the `OutOfMemory` type's documentation for
773 /// details on Wasmtime's out-of-memory handling.
774 pub fn module(&mut self, name: &str, module: &Module) -> Result<()> {
775 self.insert(name, Definition::Module(module.clone()))?;
776 Ok(())
777 }
778
779 /// Defines a new resource of a given [`ResourceType`] in this linker.
780 ///
781 /// This function is used to specify resources defined in the host.
782 ///
783 /// The `name` argument is the name to define the resource within this
784 /// linker.
785 ///
786 /// The `dtor` provided is a destructor that will get invoked when an owned
787 /// version of this resource is destroyed from the guest. Note that this
788 /// destructor is not called when a host-owned resource is destroyed as it's
789 /// assumed the host knows how to handle destroying its own resources.
790 ///
791 /// The `dtor` closure is provided the store state as the first argument
792 /// along with the representation of the resource that was just destroyed.
793 ///
794 /// [`Resource<U>`]: crate::component::Resource
795 ///
796 /// # Errors
797 ///
798 /// The provided `dtor` closure returns an error if something goes wrong
799 /// when a guest calls the `dtor` to drop a `Resource<T>` such as
800 /// a runtime trap or a runtime limit being exceeded.
801 ///
802 /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
803 /// memory allocation fails. See the `OutOfMemory` type's documentation for
804 /// details on Wasmtime's out-of-memory handling.
805 pub fn resource(
806 &mut self,
807 name: &str,
808 ty: ResourceType,
809 dtor: impl Fn(StoreContextMut<'_, T>, u32) -> Result<()> + Send + Sync + 'static,
810 ) -> Result<()> {
811 let dtor = try_new::<Arc<_>>(crate::func::HostFunc::wrap(
812 &self.engine,
813 move |mut cx: crate::Caller<'_, T>, (param,): (u32,)| dtor(cx.as_context_mut(), param),
814 )?)?;
815 self.insert(name, Definition::Resource(ty, dtor))?;
816 Ok(())
817 }
818
819 /// Identical to [`Self::resource`], except that it takes an async destructor.
820 #[cfg(feature = "async")]
821 pub fn resource_async<F>(&mut self, name: &str, ty: ResourceType, dtor: F) -> Result<()>
822 where
823 T: Send,
824 F: Fn(StoreContextMut<'_, T>, u32) -> Box<dyn Future<Output = Result<()>> + Send + '_>
825 + Send
826 + Sync
827 + 'static,
828 {
829 let dtor = try_new::<Arc<_>>(crate::func::HostFunc::wrap_async(
830 &self.engine,
831 move |cx: crate::Caller<'_, T>, (param,): (u32,)| dtor(cx.into(), param),
832 )?)?;
833 self.insert(name, Definition::Resource(ty, dtor))?;
834 Ok(())
835 }
836
837 /// Identical to [`Self::resource`], except that it takes a concurrent destructor.
838 #[cfg(feature = "component-model-async")]
839 pub fn resource_concurrent<F>(&mut self, name: &str, ty: ResourceType, dtor: F) -> Result<()>
840 where
841 T: Send + 'static,
842 F: Fn(&Accessor<T>, u32) -> Pin<Box<dyn Future<Output = Result<()>> + Send + '_>>
843 + Send
844 + Sync
845 + 'static,
846 {
847 if !self.engine.tunables().concurrency_support {
848 bail!("concurrent host functions require `Config::concurrency_support`");
849 }
850 // TODO: This isn't really concurrent -- it requires exclusive access to
851 // the store for the duration of the call, preventing guest code from
852 // running until it completes. We should make it concurrent and clean
853 // up the implementation to avoid using e.g. `Accessor::new` and
854 // `tls::set` directly.
855 let dtor = Arc::new(dtor);
856 let dtor = Arc::new(crate::func::HostFunc::wrap_async(
857 &self.engine,
858 move |mut cx: crate::Caller<'_, T>, (param,): (u32,)| {
859 let dtor = dtor.clone();
860 Box::new(async move {
861 let mut store = cx.as_context_mut();
862 let accessor =
863 &Accessor::new(crate::store::StoreToken::new(store.as_context_mut()));
864 let mut future = std::pin::pin!(dtor(accessor, param));
865 std::future::poll_fn(|cx| {
866 crate::component::concurrent::tls::set(store.0, || future.as_mut().poll(cx))
867 })
868 .await
869 })
870 },
871 )?);
872 self.insert(name, Definition::Resource(ty, dtor))?;
873 Ok(())
874 }
875
876 /// Defines a nested instance within this instance.
877 ///
878 /// This can be used to describe arbitrarily nested levels of instances
879 /// within a linker to satisfy nested instance exports of components.
880 pub fn instance(&mut self, name: &str) -> Result<LinkerInstance<'_, T>> {
881 self.as_mut().into_instance(name)
882 }
883
884 /// Same as [`LinkerInstance::instance`] except with different lifetime
885 /// parameters.
886 pub fn into_instance(mut self, name: &str) -> Result<Self> {
887 let name = self.insert(name, Definition::Instance(NameMap::default()))?;
888 self.map = match self.map.raw_get_mut(&name) {
889 Some(Definition::Instance(map)) => map,
890 _ => unreachable!(),
891 };
892 self.path.truncate(self.path_len);
893 self.path.push(name);
894 self.path_len += 1;
895 Ok(self)
896 }
897
898 fn insert(&mut self, name: &str, item: Definition) -> Result<Atom> {
899 self.map
900 .insert(name, self.strings, self.allow_shadowing, item)
901 }
902
903 fn get(&self, name: &str) -> Option<&Definition> {
904 self.map.get(name, self.strings)
905 }
906}