Trait ComponentType

Source
pub unsafe trait ComponentType: Send + Sync { }
Available on crate features runtime and component-model only.
Expand description

A trait representing types which can be passed to and read from components with the canonical ABI.

This trait is implemented for Rust types which can be communicated to components. The Func::typed and TypedFunc Rust items are the main consumers of this trait.

Supported Rust types include:

Component Model TypeRust Type
{s,u}{8,16,32,64}{i,u}{8,16,32,64}
f{32,64}f{32,64}
boolbool
charchar
tuple<A, B>(A, B)
option<T>Option<T>
resultResult<(), ()>
result<T>Result<T, ()>
result<_, E>Result<(), E>
result<T, E>Result<T, E>
stringString, &str, or WasmStr
list<T>Vec<T>, &[T], or WasmList
own<T>, borrow<T>Resource<T> or ResourceAny
record#[derive(ComponentType)]
variant#[derive(ComponentType)]
enum#[derive(ComponentType)]
flagsflags!

Rust standard library pointers such as &T, Box<T>, and Arc<T> additionally represent whatever type T represents in the component model. Note that types such as record, variant, enum, and flags are generated by the embedder at compile time. These macros derive implementation of this trait for custom types to map to custom types in the component model. Note that for record, variant, enum, and flags those types are often generated by the bindgen! macro from WIT definitions.

Types that implement ComponentType are used for Params and Return in TypedFunc and Func::typed.

The contents of this trait are hidden as it’s intended to be an implementation detail of Wasmtime. The contents of this trait are not covered by Wasmtime’s stability guarantees.

§Safety

Note that this is an unsafe trait as TypedFunc’s safety heavily relies on the correctness of the implementations of this trait. Some ways in which this trait must be correct to be safe are:

  • The Lower associated type must be a ValRaw sequence. It doesn’t have to literally be [ValRaw; N] but when laid out in memory it must be adjacent ValRaw values and have a multiple of the size of ValRaw and the same alignment.

  • The lower function must initialize the bits within Lower that are going to be read by the trampoline that’s used to enter core wasm. A trampoline is passed *mut Lower and will read the canonical abi arguments in sequence, so all of the bits must be correctly initialized.

  • The size and align functions must be correct for this value stored in the canonical ABI. The Cursor<T> iteration of these bytes rely on this for correctness as they otherwise eschew bounds-checking.

There are likely some other correctness issues which aren’t documented as well, this isn’t currently an exhaustive list. It suffices to say, though, that correctness bugs in this trait implementation are highly likely to lead to security bugs, which again leads to the unsafe in the trait.

Note that this trait specifically is not sealed because bindgen!-generated types must be able to implement this trait using a #[derive] macro. For users it’s recommended to not implement this trait manually given the non-exhaustive list of safety requirements that must be upheld. This trait is implemented at your own risk if you do so.

§Send and Sync

While on the topic of safety it’s worth discussing the Send and Sync bounds here as well. These bounds might naively seem like they shouldn’t be required for all component types as they’re host-level types not guest-level types persisted anywhere. Various subtleties lead to these bounds, however:

  • Fibers require that all stack-local variables are Send and Sync for fibers themselves to be send/sync. Unfortunately we have no help from the compiler on this one so it’s up to Wasmtime’s discipline to maintain this. One instance of this is that return values are placed on the stack as they’re lowered into guest memory. This lowering operation can involve malloc and context switches, so return values must be Send/Sync.

  • In the implementation of component model async it’s not uncommon for types to be “buffered” in the store temporarily. For example parameters might reside in a store temporarily while wasm has backpressure turned on.

Overall it’s generally easiest to require Send and Sync for all component types. There additionally aren’t known use case for non-Send or non-Sync types at this time.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types§

Source§

impl ComponentType for bool

Source§

impl ComponentType for char

Source§

impl ComponentType for f32

Source§

impl ComponentType for f64

Source§

impl ComponentType for i8

Source§

impl ComponentType for i16

Source§

impl ComponentType for i32

Source§

impl ComponentType for i64

Source§

impl ComponentType for str

Source§

impl ComponentType for u8

Source§

impl ComponentType for u16

Source§

impl ComponentType for u32

Source§

impl ComponentType for u64

Source§

impl ComponentType for ()

Source§

impl ComponentType for String

Source§

impl<A1> ComponentType for (A1,)
where A1: ComponentType,

Source§

impl<A1, A2> ComponentType for (A1, A2)

Source§

impl<A1, A2, A3> ComponentType for (A1, A2, A3)

Source§

impl<A1, A2, A3, A4> ComponentType for (A1, A2, A3, A4)

Source§

impl<A1, A2, A3, A4, A5> ComponentType for (A1, A2, A3, A4, A5)

Source§

impl<A1, A2, A3, A4, A5, A6> ComponentType for (A1, A2, A3, A4, A5, A6)

Source§

impl<A1, A2, A3, A4, A5, A6, A7> ComponentType for (A1, A2, A3, A4, A5, A6, A7)

Source§

impl<A1, A2, A3, A4, A5, A6, A7, A8> ComponentType for (A1, A2, A3, A4, A5, A6, A7, A8)

Source§

impl<A1, A2, A3, A4, A5, A6, A7, A8, A9> ComponentType for (A1, A2, A3, A4, A5, A6, A7, A8, A9)

Source§

impl<A1, A2, A3, A4, A5, A6, A7, A8, A9, A10> ComponentType for (A1, A2, A3, A4, A5, A6, A7, A8, A9, A10)

Source§

impl<A1, A2, A3, A4, A5, A6, A7, A8, A9, A10, A11> ComponentType for (A1, A2, A3, A4, A5, A6, A7, A8, A9, A10, A11)

Source§

impl<A1, A2, A3, A4, A5, A6, A7, A8, A9, A10, A11, A12> ComponentType for (A1, A2, A3, A4, A5, A6, A7, A8, A9, A10, A11, A12)

Source§

impl<A1, A2, A3, A4, A5, A6, A7, A8, A9, A10, A11, A12, A13> ComponentType for (A1, A2, A3, A4, A5, A6, A7, A8, A9, A10, A11, A12, A13)

Source§

impl<A1, A2, A3, A4, A5, A6, A7, A8, A9, A10, A11, A12, A13, A14> ComponentType for (A1, A2, A3, A4, A5, A6, A7, A8, A9, A10, A11, A12, A13, A14)

Source§

impl<A1, A2, A3, A4, A5, A6, A7, A8, A9, A10, A11, A12, A13, A14, A15> ComponentType for (A1, A2, A3, A4, A5, A6, A7, A8, A9, A10, A11, A12, A13, A14, A15)

Source§

impl<A1, A2, A3, A4, A5, A6, A7, A8, A9, A10, A11, A12, A13, A14, A15, A16> ComponentType for (A1, A2, A3, A4, A5, A6, A7, A8, A9, A10, A11, A12, A13, A14, A15, A16)

Source§

impl<A1, A2, A3, A4, A5, A6, A7, A8, A9, A10, A11, A12, A13, A14, A15, A16, A17> ComponentType for (A1, A2, A3, A4, A5, A6, A7, A8, A9, A10, A11, A12, A13, A14, A15, A16, A17)

Source§

impl<T> ComponentType for Option<T>
where T: ComponentType,

Source§

impl<T> ComponentType for [T]
where T: ComponentType,

Source§

impl<T, E> ComponentType for Result<T, E>

Source§

impl<T: ComponentType + ?Sized> ComponentType for &T

Source§

impl<T: ComponentType + ?Sized> ComponentType for Box<T>

Source§

impl<T: ComponentType + ?Sized> ComponentType for Arc<T>

Source§

impl<T: ComponentType> ComponentType for Vec<T>

Implementors§

Source§

impl ComponentType for wasmtime::component::bindgen_examples::_3_interface_imports::example::interface_imports::logging::Level

Available on docsrs only.
Source§

impl ComponentType for wasmtime::component::bindgen_examples::_4_imported_resources::example::imported_resources::logging::Level

Available on docsrs only.
Source§

impl ComponentType for wasmtime::component::bindgen_examples::_6_exported_resources::exports::example::exported_resources::logging::Level

Available on docsrs only.
Source§

impl ComponentType for wasmtime::component::bindgen_examples::_7_async::example::imported_resources::logging::Level

Available on docsrs only.
Source§

impl ComponentType for ErrorContext

Available on crate feature component-model-async only.
Source§

impl ComponentType for ResourceAny

Source§

impl ComponentType for WasmStr

Source§

impl<T: 'static> ComponentType for Resource<T>

Source§

impl<T: Send + Sync> ComponentType for HostFuture<T>

Available on crate feature component-model-async only.
Source§

impl<T: Send + Sync> ComponentType for HostStream<T>

Available on crate feature component-model-async only.
Source§

impl<T: ComponentType> ComponentType for WasmList<T>