chore: cleanup

Signed-off-by: Henry <mail@henrygressmann.de>

Author: explodingcamera

crates/c-api/README.md

@@ -15,6 +15,26 @@ This builds `libtinywasm.so` (or `.dylib` on macOS) and `libtinywasm.a` in
 `pkg-config` file, run `make -C crates/c-api install`. Run `make -C crates/c-api example` to
 build and run the C example.
 
+## Symbol prefix
+
+By default, the library exports the names in `wasm.h`. To avoid symbol
+collisions with another WebAssembly C API implementation, build with a prefix:
+
+```sh
+make -C crates/c-api TINYWASM_C_API_PREFIX=my_
+```
+
+Define the same prefix before including `tinywasm.h` in C or C++:
+
+```c
+#define TINYWASM_C_API_PREFIX my_
+#include "tinywasm.h"
+```
+
+When building with Cargo directly, enable `custom-prefix` and set the
+`TINYWASM_C_API_PREFIX` environment variable. Include `tinywasm.h` before
+`wasm.h` so the symbol aliases take effect.
+
 ## Notes
 
 - Follow the ownership annotations in `wasm.h` and use the matching delete
@@ -28,5 +48,5 @@ build and run the C example.
   the module boundary.
 
 `wasm.h` is vendored from WebAssembly/wasm-c-api commit
-`9d6b93764ac96cdd9db51081c363e09d2d488b4d` under
+`9d6b93764ac96cdd9db51081c363e09d2d488b4d`, under
 [`include/LICENSE-wasm-c-api`](include/LICENSE-wasm-c-api).

crates/c-api/examples/add.c

@@ -1,3 +1,4 @@
+#include <assert.h>
 #include <stdio.h>
 #include "tinywasm.h"
 
@@ -30,8 +31,10 @@ int main(void) {
   assert(instance && !trap);
   wasm_extern_vec_t exports;
   wasm_instance_exports(instance, &exports);
+  /* The export vector owns its handles. wasm_extern_as_func borrows one. */
   wasm_val_t arguments[] = { WASM_I32_VAL(20), WASM_I32_VAL(22) };
   wasm_val_t result[1];
+  /* Stack-backed vectors need no vector delete. The call writes the result slot. */
   wasm_val_vec_t args = WASM_ARRAY_VEC(arguments);
   wasm_val_vec_t results = WASM_ARRAY_VEC(result);
   trap = wasm_func_call(wasm_extern_as_func(exports.data[0]), &args, &results);

crates/c-api/src/externals.rs

@@ -48,7 +48,6 @@ export! { pub unsafe extern "C" fn wasm_table_new(store: *mut wasm_store_t, ty:
     }).map_or_else(failure, |object| boxed(wasm_ref_t(object)))
 }}
 
-/// Runs a checked store operation on an opaque object.
 fn with_object<T: Default>(
     object: &Object,
     action: impl FnOnce(&Rc<StoreState>, &mut Access<'_>) -> tinywasm::Result<T>,

crates/c-api/src/function.rs

@@ -39,6 +39,9 @@ impl<T> ThreadConfined<T> {
 }
 
 impl CallbackData {
+    /// # Safety
+    /// The C callback and its environment must remain valid for this call, and
+    /// `args` and `results` must point to valid callback vectors.
     unsafe fn call(&self, args: *const wasm_val_vec_t, results: *mut wasm_val_vec_t) -> *mut wasm_trap_t {
         unsafe {
             match self.function {
@@ -123,7 +126,10 @@ export! { pub unsafe extern "C" fn wasm_func_result_arity(value: *const wasm_fun
 
 export! { pub unsafe extern "C" fn wasm_func_call(value: *const wasm_func_t, args: *const wasm_val_vec_t, results: *mut wasm_val_vec_t) -> *mut wasm_trap_t {
     let object = unsafe { (*value).0.clone() };
-    let state = object.state().expect("function store must be alive");
+    let state = match object.state() {
+        Ok(state) => state,
+        Err(error) => return failure(error),
+    };
     let result = state.access(|access| {
         let ObjectKind::Func(function, _) = &object.kind else { return Err(tinywasm::Error::Other("expected function".into())); };
         let ty = function.ty(access.store())?.clone();

crates/c-api/src/lib.rs

@@ -1,8 +1,27 @@
-//! Cargo-built implementation of the WebAssembly C API.
+//! C API implementation for TinyWasm.
 //!
-//! The public contract is in `include/wasm.h` and `include/tinywasm.h`.
-//! All pointer arguments follow those headers' ownership and lifetime rules.
-//! Stores and their objects are confined to the creating thread.
+//! See `include/wasm.h` and `include/tinywasm.h` for the C interface and ownership rules.
+//! Use a store and its objects only on the thread that created the store.
+//!
+//! # Symbol prefix
+//!
+//! By default, the library exports the names in `wasm.h`. To avoid collisions
+//! with another WebAssembly C API implementation, build with a prefix:
+//!
+//! ```sh
+//! make -C crates/c-api TINYWASM_C_API_PREFIX=my_
+//! ```
+//!
+//! Define the same prefix before including `tinywasm.h` in C or C++:
+//!
+//! ```c
+//! #define TINYWASM_C_API_PREFIX my_
+//! #include "tinywasm.h"
+//! ```
+//!
+//! When building with Cargo directly, enable `custom-prefix` and set
+//! `TINYWASM_C_API_PREFIX`. Include `tinywasm.h` before `wasm.h` so the aliases
+//! take effect.
 #![allow(non_camel_case_types)]
 #![deny(unsafe_op_in_unsafe_fn)]
 
@@ -38,9 +57,12 @@ fn boxed<T>(value: T) -> *mut T {
 }
 
 /// Deletes a nullable owned opaque handle.
+///
+/// # Safety
+/// `value` must be null or a live handle returned by `boxed` whose ownership
+/// has been transferred to this call exactly once.
 unsafe fn delete<T>(value: *mut T) {
     if !value.is_null() {
-        // SAFETY: the caller transfers a handle allocated by `boxed` exactly once.
         unsafe { drop(Box::from_raw(value)) };
     }
 }

crates/c-api/src/module.rs

@@ -122,17 +122,15 @@ export! { pub unsafe extern "C" fn wasm_instance_exports(value: *const wasm_inst
         let state = object.state()?;
         let ObjectKind::Instance(instance) = &object.kind else { return Err(tinywasm::Error::Other("expected instance".into())); };
         state.access(|access| {
-            // Build owned handles only after all fallible conversions complete.
-            let objects = instance.exports().map(|(_, item)| {
-                let kind = match item {
+            let kinds = instance.exports().map(|(_, item)| {
+                Ok(match item {
                     ExternItem::Func(func) => { let reference = func.as_func_ref(access.store())?; ObjectKind::Func(func, reference) },
                     ExternItem::Global(global) => ObjectKind::Global(global), ExternItem::Memory(memory) => ObjectKind::Memory(memory),
                     ExternItem::Table(table) => ObjectKind::Table(table), ExternItem::Tag(_) => return Err(tinywasm::Error::Other("tag exports are unsupported".into())),
                     ExternItem::MemoryShared(_) => return Err(tinywasm::Error::Other("shared memory exports are unsupported".into())),
-                };
-                Ok(state.intern(kind))
+                })
             }).collect::<tinywasm::Result<Vec<_>>>()?;
-            Ok(Vector::from_vec(objects.into_iter().map(|object| boxed(wasm_ref_t(object))).collect()))
+            Ok(Vector::from_vec(kinds.into_iter().map(|kind| boxed(wasm_ref_t(state.intern(kind)))).collect()))
         })
     })();
     unsafe { out.write(result.unwrap_or_else(failure)) };

crates/c-api/src/objects.rs

@@ -11,7 +11,7 @@ use std::{
 };
 use tinywasm::{FuncRef, Function, Global, Memory, Module, ModuleInstance, Table};
 
-/// A finalizer owns exactly one C environment or host-info value.
+/// Calls the optional finalizer when replaced or dropped.
 pub(crate) struct HostInfo {
     pub(crate) data: *mut c_void,
     pub(crate) finalizer: Option<unsafe extern "C" fn(*mut c_void)>,

crates/c-api/src/tests.rs

@@ -150,3 +150,32 @@ fn memory_pointer_lifetime() {
         wasm_engine_delete(engine);
     }
 }
+
+#[test]
+fn function_call_after_store_delete() {
+    let binary = Vector::from_vec(wat::parse_str(r#"(module (func (export "noop")))"#).unwrap());
+    unsafe {
+        let engine = wasm_engine_new();
+        let store = wasm_store_new(engine);
+        let module = wasm_module_new(store, &binary);
+        let imports = Vector::default();
+        let instance = wasm_instance_new(store, module, &imports, ptr::null_mut());
+        let mut exports = Vector::default();
+        wasm_instance_exports(instance, &mut exports);
+        let function = wasm_func_copy(wasm_extern_as_func(exports.as_slice()[0]));
+        drop(exports);
+        wasm_instance_delete(instance);
+        wasm_module_delete(module);
+        wasm_store_delete(store);
+
+        let empty = Vector::default();
+        let mut results = Vector::default();
+        assert!(wasm_func_call(function, &empty, &mut results).is_null());
+        let mut message = Vector::default();
+        crate::tinywasm_last_error_message(&mut message);
+        assert!(message.as_slice().ends_with(b"store has been deleted\0"));
+
+        wasm_func_delete(function);
+        wasm_engine_delete(engine);
+    }
+}

crates/c-api/src/values.rs

@@ -45,6 +45,9 @@ impl Element for wasm_val_t {
 
 impl wasm_val_t {
     /// Reads a valid C value and roots any reference in the owning runtime store.
+    ///
+    /// # Safety
+    /// The value must be initialized, including the union field selected by `kind`.
     pub(crate) unsafe fn to_runtime(&self, state: &Rc<StoreState>, store: &mut Store) -> tinywasm::Result<WasmValue> {
         Ok(unsafe {
             match self.kind {
@@ -92,6 +95,9 @@ impl wasm_val_t {
 }
 
 /// Converts a borrowed C reference, preserving store identity.
+///
+/// # Safety
+/// `value` must be null or a live C handle for the duration of this call.
 pub(crate) unsafe fn reference_to_runtime(
     value: *const wasm_ref_t,
     kind: u8,

crates/c-api/src/vectors.rs

@@ -5,8 +5,14 @@ use crate::{objects::*, types::*, values::wasm_val_t};
 /// An element owned by a C API vector.
 pub trait Element: Default {
     /// Copies the element and any owned handle.
+    ///
+    /// # Safety
+    /// The element and any handle it contains must be initialized and live.
     unsafe fn copy(&self) -> Self;
     /// Releases any owned handle.
+    ///
+    /// # Safety
+    /// The element must own its handle and must not have been destroyed already.
     unsafe fn destroy(&mut self);
 }
 
@@ -51,19 +57,27 @@ impl<T: Element> Vector<T> {
     }
 
     /// Borrows initialized elements. Zero-length vectors may have null data.
+    ///
+    /// # Safety
+    /// For nonempty vectors, `data` must point to `size` live, initialized
+    /// elements that are not mutated for the duration of the borrow.
     pub(crate) unsafe fn as_slice(&self) -> &[T] {
         if self.size == 0 { &[] } else { unsafe { slice::from_raw_parts(self.data, self.size) } }
     }
 
     /// Borrows initialized elements exclusively.
+    ///
+    /// # Safety
+    /// For nonempty vectors, `data` must point to `size` live, initialized
+    /// elements exclusively accessible for the duration of the borrow.
     pub(crate) unsafe fn as_mut_slice(&mut self) -> &mut [T] {
         if self.size == 0 { &mut [] } else { unsafe { slice::from_raw_parts_mut(self.data, self.size) } }
     }
 }
 
 impl<T: Element> Clone for Vector<T> {
     fn clone(&self) -> Self {
-        // SAFETY: Rust-owned vectors always contain initialized, live elements.
+        // SAFETY: the source vector must contain initialized, live elements.
         unsafe { Self::from_vec(self.as_slice().iter().map(|value| value.copy()).collect()) }
     }
 }