Skip to content

A lightweight WebAssembly runtime that is fast, secure, and standards-compliant

Clarify map docs and add `Type::unwrap_map` (#14839)

Randolf J.11e41bcbff45
diff --git a/crates/cli-flags/src/lib.rs b/crates/cli-flags/src/lib.rs
index 3e819466e2..4369644af8 100644
--- a/crates/cli-flags/src/lib.rs
+++ b/crates/cli-flags/src/lib.rs
@@ -500,7 +500,8 @@ wasmtime_option_group! {
/// GC support in the component model: this corresponds to the 🛸 emoji
/// in the component model specification.
pub component_model_gc: Option<bool>,
- /// Map support in the component model.
+ /// Map support in the component model: this corresponds to the 🗺️
+ /// emoji in the component model specification.
pub component_model_map: Option<bool>,
/// Component model support for `memory64`: this corresponds
/// to the 🐘 emoji in the component model specification.
diff --git a/crates/wasmtime/src/config.rs b/crates/wasmtime/src/config.rs
index 6005fb7542..bab1c970d8 100644
--- a/crates/wasmtime/src/config.rs
+++ b/crates/wasmtime/src/config.rs
@@ -1382,8 +1382,11 @@ impl Config {
/// Configures whether the component model map type is enabled or not.
///
- /// This is part of the component model specification and enables the
- /// `map<k, v>` type in WIT and the component binary format.
+ /// This corresponds to the 🗺️ emoji in the component model specification
+ /// and enables the `map<k, v>` type in WIT and the component binary
+ /// format.
+ ///
+ /// This is `false` by default.
#[cfg(feature = "component-model")]
pub fn wasm_component_model_map(&mut self, enable: bool) -> &mut Self {
self.wasm_features(WasmFeatures::CM_MAP, enable);
diff --git a/crates/wasmtime/src/runtime/component/func/typed.rs b/crates/wasmtime/src/runtime/component/func/typed.rs
index 5e5ed978e9..a09c503a29 100644
--- a/crates/wasmtime/src/runtime/component/func/typed.rs
+++ b/crates/wasmtime/src/runtime/component/func/typed.rs
@@ -432,6 +432,7 @@ pub unsafe trait ComponentNamedList: ComponentType {}
/// [`ResourceAny`]: crate::component::ResourceAny
/// [d-cm]: macro@crate::component::ComponentType
/// [f-m]: crate::component::flags
+/// [`Val::Map`]: crate::component::Val::Map
///
/// Rust standard library pointers such as `&T`, `Box<T>`, and `Arc<T>`
/// additionally represent whatever type `T` represents in the component model.
@@ -442,6 +443,9 @@ pub unsafe trait ComponentNamedList: ComponentType {}
/// those types are often generated by the
/// [`bindgen!`](crate::component::bindgen) macro from WIT definitions.
///
+/// Lifting a `map<K, V>` into a `HashMap<K, V>` keeps only the last value for
+/// each duplicate key. Use [`Val::Map`] to see every entry in order instead.
+///
/// Types that implement [`ComponentType`] are used for `Params` and `Return`
/// in [`TypedFunc`] and [`Func::typed`].
///
diff --git a/crates/wasmtime/src/runtime/component/types.rs b/crates/wasmtime/src/runtime/component/types.rs
index 9fe84a9015..c7a8f09650 100644
--- a/crates/wasmtime/src/runtime/component/types.rs
+++ b/crates/wasmtime/src/runtime/component/types.rs
@@ -801,6 +801,19 @@ impl Type {
}
}
+ /// Retrieve the inner [`Map`] of a [`Type::Map`].
+ ///
+ /// # Panics
+ ///
+ /// This will panic if `self` is not a [`Type::Map`].
+ pub fn unwrap_map(&self) -> &Map {
+ if let Type::Map(handle) = self {
+ &handle
+ } else {
+ panic!("attempted to unwrap a {} as a map", self.desc())
+ }
+ }
+
/// Retrieve the inner [`Record`] of a [`Type::Record`].
///
/// # Panics
diff --git a/crates/wasmtime/src/runtime/component/values.rs b/crates/wasmtime/src/runtime/component/values.rs
index 607b09bc55..f01295eb63 100644
--- a/crates/wasmtime/src/runtime/component/values.rs
+++ b/crates/wasmtime/src/runtime/component/values.rs
@@ -27,9 +27,9 @@ use wasmtime_environ::component::{
///
/// This type implements both the Rust `PartialEq` and `Eq` traits. This type
/// additionally contains values which are not necessarily easily equated,
-/// however, such as floats (`Float32` and `Float64`) and resources. Equality
-/// does require that two values have the same type, and then these cases are
-/// handled as:
+/// however, such as floats (`Float32` and `Float64`), resources, and maps.
+/// Equality does require that two values have the same type, and then these
+/// cases are handled as:
///
/// * Floats are tested if they are "semantically the same" meaning all NaN
/// values are equal to all other NaN values. Additionally zero values must be
@@ -45,6 +45,9 @@ use wasmtime_environ::component::{
/// if they contain the same value, but will never be considered equal when
/// compared as `Val::Resource`s).
///
+/// * Maps are compared entry-by-entry in order, so the same logical map with
+/// entries in a different order, or with duplicate keys, compares unequal.
+///
/// In general if a strict guarantee about equality is required here it's
/// recommended to "build your own" as this equality intended for fuzzing
/// Wasmtime may not be suitable for you.
@@ -90,7 +93,11 @@ pub enum Val {
String(String),
List(Vec<Val>),
/// A map type represented as a list of key-value pairs.
- /// Duplicate keys are allowed and follow "last value wins" semantics.
+ ///
+ /// Entries are kept exactly as they appear in the canonical ABI list, in
+ /// order and including duplicate keys. Per the component model, the last
+ /// entry for a key is the one that defines its value when the list is
+ /// interpreted as a map.
Map(Vec<(Val, Val)>),
Record(Vec<(String, Val)>),
Tuple(Vec<Val>),
diff --git a/tests/all/component_model/dynamic.rs b/tests/all/component_model/dynamic.rs
index dfa4275257..fde137f9b4 100644
--- a/tests/all/component_model/dynamic.rs
+++ b/tests/all/component_model/dynamic.rs
@@ -272,6 +272,26 @@ fn maps_complex_types() -> Result<()> {
Ok(())
}
+#[test]
+fn maps_type() -> Result<()> {
+ let engine = super::map_engine();
+ let mut store = Store::new(&engine, ());
+
+ let component = Component::new(&engine, make_echo_component("(map string (list u32))", 8))?;
+ let instance = Linker::new(&engine).instantiate(&mut store, &component)?;
+ let func = instance.get_func(&mut store, "echo").unwrap();
+ let func_ty = func.ty(&store);
+
+ let (name, param) = func_ty.params().next().unwrap();
+ assert_eq!(name, "a");
+ let map_ty = param.unwrap_map();
+ assert_eq!(map_ty.key(), types::Type::String);
+ assert_eq!(map_ty.value().unwrap_list().ty(), types::Type::U32);
+ assert_eq!(func_ty.results().next().unwrap().unwrap_map(), map_ty);
+
+ Ok(())
+}
+
#[test]
fn maps_equality() -> Result<()> {
let map1 = vec![