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 Type | Rust Type |
|---|---|
{s,u}{8,16,32,64} | {i,u}{8,16,32,64} |
f{32,64} | f{32,64} |
bool | bool |
char | char |
tuple<A, B> | (A, B) |
option<T> | Option<T> |
result | Result<(), ()> |
result<T> | Result<T, ()> |
result<_, E> | Result<(), E> |
result<T, E> | Result<T, E> |
string | String, &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)] |
flags | flags! |
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
Lowerassociated type must be aValRawsequence. It doesn’t have to literally be[ValRaw; N]but when laid out in memory it must be adjacentValRawvalues and have a multiple of the size ofValRawand the same alignment. -
The
lowerfunction must initialize the bits withinLowerthat are going to be read by the trampoline that’s used to enter core wasm. A trampoline is passed*mut Lowerand will read the canonical abi arguments in sequence, so all of the bits must be correctly initialized. -
The
sizeandalignfunctions must be correct for this value stored in the canonical ABI. TheCursor<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
SendandSyncfor 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.