Trait ComponentType

pub unsafe trait ComponentType: Send + Sync { }
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§

§

impl ComponentType for bool

§

impl ComponentType for char

§

impl ComponentType for f32

§

impl ComponentType for f64

§

impl ComponentType for i8

§

impl ComponentType for i16

§

impl ComponentType for i32

§

impl ComponentType for i64

§

impl ComponentType for str

§

impl ComponentType for u8

§

impl ComponentType for u16

§

impl ComponentType for u32

§

impl ComponentType for u64

§

impl ComponentType for ()

§

impl ComponentType for String

§

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

§

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

§

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

§

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

§

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

§

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

§

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

§

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

§

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

§

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

§

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)

§

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)

§

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)

§

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)

§

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)

§

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)

§

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)

§

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

§

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

§

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

§

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

§

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

§

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

§

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

Implementors§

§

impl ComponentType for ErrorContext

§

impl ComponentType for ResourceAny

§

impl ComponentType for WasmStr

§

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

§

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

§

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

§

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