Skip to content

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

c-api: implement wasm_tagtype_t for exception tag types (#10252) (#12763)

Vasily Chekalkin546f6dbc6abf
diff --git a/crates/c-api/include/wasmtime.h b/crates/c-api/include/wasmtime.h
index 814da24344..3d403790dd 100644
--- a/crates/c-api/include/wasmtime.h
+++ b/crates/c-api/include/wasmtime.h
@@ -201,6 +201,7 @@
#include <wasmtime/sharedmemory.h>
#include <wasmtime/store.h>
#include <wasmtime/table.h>
+#include <wasmtime/tag.h>
#include <wasmtime/trap.h>
#include <wasmtime/val.h>
#include <wasmtime/async.h>
diff --git a/crates/c-api/include/wasmtime/tag.h b/crates/c-api/include/wasmtime/tag.h
new file mode 100644
index 0000000000..d614052e4e
--- /dev/null
+++ b/crates/c-api/include/wasmtime/tag.h
@@ -0,0 +1,94 @@
+/**
+ * \file wasmtime/tag.h
+ *
+ * \brief Wasmtime APIs for WebAssembly exception tag types.
+ *
+ * This header defines the C API for `wasmtime_tagtype_t`, the type descriptor
+ * for WebAssembly exception tags (wasm exception-handling proposal). Because
+ * `wasm.h` is vendored from the upstream wasm-c-api repository and does not
+ * yet include tag-type support, the declarations live here instead.
+ */
+
+#ifndef WASMTIME_TAG_H
+#define WASMTIME_TAG_H
+
+#include <stddef.h>
+#include <wasm.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * \brief Opaque type representing a WebAssembly exception tag type.
+ *
+ * A tag type is described by a function type whose parameters are the exception
+ * payload types and whose results are the tag's result types (currently always
+ * empty, but reserved for the stack-switching proposal).
+ */
+typedef struct wasmtime_tagtype_t wasmtime_tagtype_t;
+
+/**
+ * \brief Value returned by #wasm_externtype_kind for exception tags.
+ *
+ * This constant extends the `WASM_EXTERN_*` range from `wasm.h` (0–3) with
+ * tag support. It is distinct from #WASMTIME_EXTERN_SHAREDMEMORY (which is
+ * a discriminant for the runtime #wasmtime_extern_t union in
+ * `wasmtime/extern.h`).
+ */
+#define WASMTIME_EXTERNTYPE_TAG 4
+
+/**
+ * \brief Creates a new tag type from the given function type.
+ *
+ * The function type describes the exception payload: its parameters are the
+ * tag's exception payload types and its results are the tag's result types.
+ * `engine` is used to resolve `functype` if it has not yet been interned.
+ *
+ * Returns an owned #wasmtime_tagtype_t that must be freed with
+ * #wasmtime_tagtype_delete.
+ */
+WASM_API_EXTERN wasmtime_tagtype_t *
+wasmtime_tagtype_new(wasm_engine_t *engine, const wasm_functype_t *functype);
+
+/// \brief Deletes a #wasmtime_tagtype_t.
+WASM_API_EXTERN void wasmtime_tagtype_delete(wasmtime_tagtype_t *);
+
+/// \brief Returns a copy of the given #wasmtime_tagtype_t (caller owns the
+/// result).
+WASM_API_EXTERN wasmtime_tagtype_t *
+wasmtime_tagtype_copy(const wasmtime_tagtype_t *);
+
+/**
+ * \brief Returns the function type describing this tag's exception payload.
+ *
+ * The caller owns the returned #wasm_functype_t and must free it with
+ * #wasm_functype_delete.
+ */
+WASM_API_EXTERN wasm_functype_t *
+wasmtime_tagtype_functype(const wasmtime_tagtype_t *);
+
+/// \brief Converts a #wasmtime_tagtype_t to a #wasm_externtype_t (borrowed).
+WASM_API_EXTERN wasm_externtype_t *
+wasmtime_tagtype_as_externtype(wasmtime_tagtype_t *);
+
+/// \brief Converts a const #wasmtime_tagtype_t to a const #wasm_externtype_t
+/// (borrowed).
+WASM_API_EXTERN const wasm_externtype_t *
+wasmtime_tagtype_as_externtype_const(const wasmtime_tagtype_t *);
+
+/// \brief Converts a #wasm_externtype_t to a #wasmtime_tagtype_t, or NULL if
+/// not a tag.
+WASM_API_EXTERN wasmtime_tagtype_t *
+wasmtime_externtype_as_tagtype(wasm_externtype_t *);
+
+/// \brief Converts a const #wasm_externtype_t to a const #wasmtime_tagtype_t,
+/// or NULL if not a tag.
+WASM_API_EXTERN const wasmtime_tagtype_t *
+wasmtime_externtype_as_tagtype_const(const wasm_externtype_t *);
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // WASMTIME_TAG_H
diff --git a/crates/c-api/include/wasmtime/types.hh b/crates/c-api/include/wasmtime/types.hh
index 3694740cce..d44633f72c 100644
--- a/crates/c-api/include/wasmtime/types.hh
+++ b/crates/c-api/include/wasmtime/types.hh
@@ -8,6 +8,7 @@
#include <wasmtime/types/import.hh>
#include <wasmtime/types/memory.hh>
#include <wasmtime/types/table.hh>
+#include <wasmtime/types/tag.hh>
#include <wasmtime/types/val.hh>
#endif // WASMTIME_TYPES_HH
diff --git a/crates/c-api/include/wasmtime/types/extern.hh b/crates/c-api/include/wasmtime/types/extern.hh
index 88412a0e42..c6b55d603e 100644
--- a/crates/c-api/include/wasmtime/types/extern.hh
+++ b/crates/c-api/include/wasmtime/types/extern.hh
@@ -7,12 +7,14 @@
#include <variant>
#include <wasm.h>
+#include <wasmtime/tag.h>
#include <wasmtime/types/export.hh>
#include <wasmtime/types/func.hh>
#include <wasmtime/types/global.hh>
#include <wasmtime/types/import.hh>
#include <wasmtime/types/memory.hh>
#include <wasmtime/types/table.hh>
+#include <wasmtime/types/tag.hh>
namespace wasmtime {
@@ -31,7 +33,7 @@ public:
/// otherwise this is used to determine what the actual type of the outer item
/// is.
typedef std::variant<FuncType::Ref, GlobalType::Ref, TableType::Ref,
- MemoryType::Ref>
+ MemoryType::Ref, TagType::Ref>
Ref;
/// Extract the type of the item imported by the provided type.
@@ -59,6 +61,8 @@ private:
return wasm_externtype_as_tabletype_const(ptr);
case WASM_EXTERN_MEMORY:
return wasm_externtype_as_memorytype_const(ptr);
+ case WASMTIME_EXTERNTYPE_TAG:
+ return wasmtime_externtype_as_tagtype_const(ptr);
}
std::abort();
}
diff --git a/crates/c-api/include/wasmtime/types/func.hh b/crates/c-api/include/wasmtime/types/func.hh
index a3bc2a6868..0971fe9579 100644
--- a/crates/c-api/include/wasmtime/types/func.hh
+++ b/crates/c-api/include/wasmtime/types/func.hh
@@ -15,6 +15,7 @@ namespace wasmtime {
class FuncType {
friend class Func;
friend class Linker;
+ friend class TagType;
struct deleter {
void operator()(wasm_functype_t *p) const { wasm_functype_delete(p); }
diff --git a/crates/c-api/include/wasmtime/types/tag.hh b/crates/c-api/include/wasmtime/types/tag.hh
new file mode 100644
index 0000000000..9cf239906b
--- /dev/null
+++ b/crates/c-api/include/wasmtime/types/tag.hh
@@ -0,0 +1,86 @@
+/**
+ * \file wasmtime/types/tag.hh
+ */
+
+#ifndef WASMTIME_TYPES_TAG_HH
+#define WASMTIME_TYPES_TAG_HH
+
+#include <memory>
+#include <wasmtime/engine.hh>
+#include <wasmtime/tag.h>
+#include <wasmtime/types/func.hh>
+
+namespace wasmtime {
+
+/**
+ * \brief Type information for a WebAssembly exception tag.
+ *
+ * A tag type is described by a function type whose parameters are the exception
+ * payload types (and whose results are empty under the current proposal).
+ */
+class TagType {
+ struct deleter {
+ void operator()(wasmtime_tagtype_t *p) const { wasmtime_tagtype_delete(p); }
+ };
+
+ std::unique_ptr<wasmtime_tagtype_t, deleter> ptr;
+
+public:
+ /// Non-owning reference to a `TagType`, must not be used after the original
+ /// owner is deleted.
+ class Ref {
+ friend class TagType;
+ const wasmtime_tagtype_t *ptr;
+
+ public:
+ /// Creates a reference from the raw underlying C API representation.
+ Ref(const wasmtime_tagtype_t *ptr) : ptr(ptr) {}
+ /// Creates a reference to the provided `TagType`.
+ Ref(const TagType &ty) : Ref(ty.ptr.get()) {}
+
+ /// Returns the function type describing the exception payload of this tag.
+ ///
+ /// The caller owns the returned `FuncType`.
+ FuncType functype() const {
+ return FuncType(wasmtime_tagtype_functype(ptr));
+ }
+ };
+
+private:
+ Ref ref;
+ TagType(wasmtime_tagtype_t *ptr) : ptr(ptr), ref(ptr) {}
+
+public:
+ /// Creates a new tag type from the given function type and engine.
+ TagType(Engine &engine, FuncType &functype)
+ : ptr(wasmtime_tagtype_new(engine.capi(), functype.ptr.get())),
+ ref(ptr.get()) {}
+
+ /// Copies a reference into a uniquely owned tag type.
+ TagType(Ref other) : TagType(wasmtime_tagtype_copy(other.ptr)) {}
+ /// Copies another tag type into this one.
+ TagType(const TagType &other)
+ : TagType(wasmtime_tagtype_copy(other.ptr.get())) {}
+ /// Copies another tag type into this one.
+ TagType &operator=(const TagType &other) {
+ ptr.reset(wasmtime_tagtype_copy(other.ptr.get()));
+ ref = ptr.get();
+ return *this;
+ }
+ ~TagType() = default;
+ /// Moves the tag type resources from another type to this one.
+ TagType(TagType &&other) = default;
+ /// Moves the tag type resources from another type to this one.
+ TagType &operator=(TagType &&other) = default;
+
+ /// \brief Returns the underlying `Ref`, a non-owning reference pointing to
+ /// this instance.
+ Ref *operator->() { return &ref; }
+ /// \brief Returns the underlying `Ref`, a non-owning reference pointing to
+ /// this instance.
+ Ref *operator*() { return &ref; }
+};
+
+}; // namespace wasmtime
+
+#endif // WASMTIME_TYPES_TAG_HH
diff --git a/crates/c-api/include/wasmtime/types/val.hh b/crates/c-api/include/wasmtime/types/val.hh
index 2b063e176b..7dc524784b 100644
--- a/crates/c-api/include/wasmtime/types/val.hh
+++ b/crates/c-api/include/wasmtime/types/val.hh
@@ -68,7 +68,6 @@ class ValType {
friend class TableType;
friend class GlobalType;
friend class FuncType;
-
struct deleter {
void operator()(wasm_valtype_t *p) const { wasm_valtype_delete(p); }
};
diff --git a/crates/c-api/src/types.rs b/crates/c-api/src/types.rs
index e1aa3a704a..99e08400fe 100644
--- a/crates/c-api/src/types.rs
+++ b/crates/c-api/src/types.rs
@@ -22,6 +22,7 @@ mod global;
mod import;
mod memory;
mod table;
+mod tag;
mod val;
pub use self::export::*;
pub use self::r#extern::*;
@@ -30,4 +31,5 @@ pub use self::global::*;
pub use self::import::*;
pub use self::memory::*;
pub use self::table::*;
+pub use self::tag::*;
pub use self::val::*;
diff --git a/crates/c-api/src/types/extern.rs b/crates/c-api/src/types/extern.rs
index 075b1b7105..ea755bd835 100644
--- a/crates/c-api/src/types/extern.rs
+++ b/crates/c-api/src/types/extern.rs
@@ -1,4 +1,4 @@
-use crate::{CFuncType, CGlobalType, CMemoryType, CTableType};
+use crate::{CFuncType, CGlobalType, CMemoryType, CTableType, CTagType};
use crate::{wasm_functype_t, wasm_globaltype_t, wasm_memorytype_t, wasm_tabletype_t};
use wasmtime::ExternType;
@@ -16,6 +16,7 @@ pub(crate) enum CExternType {
Global(CGlobalType),
Memory(CMemoryType),
Table(CTableType),
+ Tag(CTagType),
}
impl CExternType {
@@ -25,7 +26,7 @@ impl CExternType {
ExternType::Global(f) => CExternType::Global(CGlobalType::new(f)),
ExternType::Memory(f) => CExternType::Memory(CMemoryType::new(f)),
ExternType::Table(f) => CExternType::Table(CTableType::new(f)),
- ExternType::Tag(_) => todo!(), // FIXME: #10252 C embedder API for exceptions and control tags.
+ ExternType::Tag(t) => CExternType::Tag(CTagType::new(t)),
}
}
}
@@ -36,6 +37,9 @@ pub const WASM_EXTERN_FUNC: wasm_externkind_t = 0;
pub const WASM_EXTERN_GLOBAL: wasm_externkind_t = 1;
pub const WASM_EXTERN_TABLE: wasm_externkind_t = 2;
pub const WASM_EXTERN_MEMORY: wasm_externkind_t = 3;
+/// Value returned by `wasm_externtype_kind` for exception tags.
+/// This extends the `wasm_externkind_t` range (0-3 in wasm.h) with tag support.
+pub const WASMTIME_EXTERNTYPE_TAG: wasm_externkind_t = 4;
impl wasm_externtype_t {
pub(crate) fn from_extern_type(ty: ExternType) -> wasm_externtype_t {
@@ -56,6 +60,7 @@ pub extern "C" fn wasm_externtype_kind(et: &wasm_externtype_t) -> wasm_externkin
CExternType::Table(_) => WASM_EXTERN_TABLE,
CExternType::Global(_) => WASM_EXTERN_GLOBAL,
CExternType::Memory(_) => WASM_EXTERN_MEMORY,
+ CExternType::Tag(_) => WASMTIME_EXTERNTYPE_TAG,
}
}
diff --git a/crates/c-api/src/types/tag.rs b/crates/c-api/src/types/tag.rs
new file mode 100644
index 0000000000..9c915e3fd5
--- /dev/null
+++ b/crates/c-api/src/types/tag.rs
@@ -0,0 +1,94 @@
+use crate::{CExternType, wasm_engine_t, wasm_externtype_t, wasm_functype_t};
+use wasmtime::TagType;
+
+#[repr(transparent)]
+#[derive(Clone)]
+pub struct wasmtime_tagtype_t {
+ ext: wasm_externtype_t,
+}
+
+wasmtime_c_api_macros::declare_ty!(wasmtime_tagtype_t);
+
+#[derive(Clone)]
+pub(crate) struct CTagType {
+ ty: TagType,
+}
+
+impl CTagType {
+ pub(crate) fn new(ty: TagType) -> CTagType {
+ CTagType { ty }
+ }
+}
+
+impl wasmtime_tagtype_t {
+ pub(crate) fn try_from(e: &wasm_externtype_t) -> Option<&wasmtime_tagtype_t> {
+ match &e.which {
+ CExternType::Tag(_) => Some(unsafe { &*(e as *const _ as *const _) }),
+ _ => None,
+ }
+ }
+
+ fn cty(&self) -> &CTagType {
+ match &self.ext.which {
+ CExternType::Tag(t) => t,
+ _ => unsafe { std::hint::unreachable_unchecked() },
+ }
+ }
+}
+
+/// Creates a new tag type from a function type describing the exception payload.
+///
+/// The tag type takes ownership of the exception payload shape from `functype`
+/// (which may have both params and results for forward compatibility with the
+/// stack-switching proposal). Returns an owned `wasmtime_tagtype_t` that must
+/// be freed with `wasmtime_tagtype_delete`.
+#[unsafe(no_mangle)]
+pub extern "C" fn wasmtime_tagtype_new(
+ engine: &wasm_engine_t,
+ functype: &wasm_functype_t,
+) -> Box<wasmtime_tagtype_t> {
+ let func_ty = functype.ty().ty(&engine.engine);
+ let tag_ty = TagType::new(func_ty);
+ Box::new(wasmtime_tagtype_t {
+ ext: wasm_externtype_t::from_cextern_type(CExternType::Tag(CTagType::new(tag_ty))),
+ })
+}
+
+/// Returns the function type describing the exception payload of this tag type.
+///
+/// The caller owns the returned `wasm_functype_t` and must free it with
+/// `wasm_functype_delete`.
+#[unsafe(no_mangle)]
+pub extern "C" fn wasmtime_tagtype_functype(tt: &wasmtime_tagtype_t) -> Box<wasm_functype_t> {
+ Box::new(wasm_functype_t::new(tt.cty().ty.ty().clone()))
+}
+
+/// Converts a `wasmtime_tagtype_t` to a `wasm_externtype_t` (borrowed).
+#[unsafe(no_mangle)]
+pub extern "C" fn wasmtime_tagtype_as_externtype(ty: &wasmtime_tagtype_t) -> &wasm_externtype_t {
+ &ty.ext
+}
+
+/// Converts a const `wasmtime_tagtype_t` to a const `wasm_externtype_t` (borrowed).
+#[unsafe(no_mangle)]
+pub extern "C" fn wasmtime_tagtype_as_externtype_const(
+ ty: &wasmtime_tagtype_t,
+) -> &wasm_externtype_t {
+ &ty.ext
+}
+
+/// Converts a `wasm_externtype_t` to a `wasmtime_tagtype_t`, or NULL if not a tag.
+#[unsafe(no_mangle)]
+pub extern "C" fn wasmtime_externtype_as_tagtype(
+ et: &wasm_externtype_t,
+) -> Option<&wasmtime_tagtype_t> {
+ wasmtime_externtype_as_tagtype_const(et)
+}
+
+/// Converts a const `wasm_externtype_t` to a const `wasmtime_tagtype_t`, or NULL if not a tag.
+#[unsafe(no_mangle)]
+pub extern "C" fn wasmtime_externtype_as_tagtype_const(
+ et: &wasm_externtype_t,
+) -> Option<&wasmtime_tagtype_t> {
+ wasmtime_tagtype_t::try_from(et)
+}
diff --git a/crates/c-api/tests/CMakeLists.txt b/crates/c-api/tests/CMakeLists.txt
index b77c1e68bf..f18adad6d2 100644
--- a/crates/c-api/tests/CMakeLists.txt
+++ b/crates/c-api/tests/CMakeLists.txt
@@ -30,6 +30,7 @@ add_capi_test(tests FILES
import_type.cc
export_type.cc
extern_type.cc
+ tag_type.cc
func.cc
component/instantiate.cc
component/define_module.cc
diff --git a/crates/c-api/tests/tag_type.cc b/crates/c-api/tests/tag_type.cc
new file mode 100644
index 0000000000..7470c36dcf
--- /dev/null
+++ b/crates/c-api/tests/tag_type.cc
@@ -0,0 +1,97 @@
+#include <wasmtime/tag.h>
+#include <wasmtime/types/tag.hh>
+
+#include <gtest/gtest.h>
+#include <wasmtime.hh>
+
+using namespace wasmtime;
+
+// Basic TagType construction and param inspection via functype.
+TEST(TagType, Simple) {
+ Config config;
+ config.wasm_exceptions(true);
+ Engine engine(std::move(config));
+
+ // Tag with no payload: empty functype.
+ FuncType empty_ft({}, {});
+ TagType empty(engine, empty_ft);
+ auto empty_func = empty->functype();
+ EXPECT_EQ(empty_func->params().size(), 0u);
+
+ // Tag with i32 and i64 payload types.
+ FuncType ft({ValKind::I32, ValKind::I64}, {});
+ TagType t(engine, ft);
+ auto func = t->functype();
+ auto params = func->params();
+ EXPECT_EQ(params.size(), 2u);
+ auto it = params.begin();
+ EXPECT_EQ(it->kind(), ValKind::I32);
+ ++it;
+ EXPECT_EQ(it->kind(), ValKind::I64);
+
+ // Copy.
+ auto t2 = t;
+ EXPECT_EQ(t2->functype()->params().size(), 2u);
+}
+
+// Verify that a module exporting an exception tag can have its exports
+// enumerated without panicking (regression test for wasmtime issue #10252).
+// Previously, CExternType::new() hit todo!() for ExternType::Tag.
+TEST(TagType, ModuleExportEnumeration) {
+ Config config;
+ config.wasm_exceptions(true);
+ Engine engine(std::move(config));
+
+ // Compile a module that exports a tag. The tag has an i32 payload.
+ Module module = Module::compile(engine, "(module"
+ " (tag $t (param i32))"
+ " (export \"t\" (tag $t))"
+ ")")
+ .unwrap();
+
+ auto exports = module.exports();
+ ASSERT_EQ(exports.size(), 1);
+
+ auto e = *exports.begin();
+ EXPECT_EQ(e.name(), "t");
+
+ auto extern_ty = ExternType::from_export(e);
+ ASSERT_TRUE(std::holds_alternative<TagType::Ref>(extern_ty));
+
+ auto tag_ref = std::get<TagType::Ref>(extern_ty);
+ auto func = tag_ref.functype();
+ auto params = func->params();
+ ASSERT_EQ(params.size(), 1u);
+ EXPECT_EQ(params.begin()->kind(), ValKind::I32);
+}
+
+// Verify that wasm_externtype_kind returns WASMTIME_EXTERNTYPE_TAG for tag
+// exports and that the C-level cast functions work correctly.
+TEST(TagType, ExternTypeKindAndCast) {
+ Config config;
+ config.wasm_exceptions(true);
+ Engine engine(std::move(config));
+
+ Module module = Module::compile(engine, "(module"
+ " (tag $t)"
+ " (export \"t\" (tag $t))"
+ ")")
+ .unwrap();
+
+ auto exports = module.exports();
+ ASSERT_EQ(exports.size(), 1);
+
+ auto e = *exports.begin();
+
+ // Access the raw C export type to verify kind and cast functions.
+ const wasm_exporttype_t *raw_et =
+ *reinterpret_cast<const wasm_exporttype_t *const *>(&e);
+ const wasm_externtype_t *ext = wasm_exporttype_type(raw_et);
+
+ EXPECT_EQ(wasm_externtype_kind(ext), WASMTIME_EXTERNTYPE_TAG);
+ EXPECT_NE(wasmtime_externtype_as_tagtype_const(ext), nullptr);
+ EXPECT_EQ(wasm_externtype_as_functype_const(ext), nullptr);
+ EXPECT_EQ(wasm_externtype_as_globaltype_const(ext), nullptr);
+ EXPECT_EQ(wasm_externtype_as_memorytype_const(ext), nullptr);
+ EXPECT_EQ(wasm_externtype_as_tabletype_const(ext), nullptr);
+}