c-api: new wasmtime_trap_new_code function (#10765)

* c-api: new wasmtime_trap_new_code function

* review comments

* remove accidental include

Author: dotcarmen

crates/c-api/README.md

@@ -72,3 +72,13 @@ fn main() {
         .compile("your_library");
 }
 ```
+
+## Testing
+
+Running tests for the C API can be done using cmake from the root of the repo:
+
+```sh
+$ cmake -S examples -B examples/build -DBUILD_SHARED_LIBS=OFF -DBUILD_TESTS=ON
+$ cmake --build examples/build --config Debug
+$ CTEST_OUTPUT_ON_FAILURE=1 cmake --build examples/build --config Debug --target test
+```

crates/c-api/include/wasmtime/trap.h

@@ -47,12 +47,40 @@ enum wasmtime_trap_code_enum {
   WASMTIME_TRAP_CODE_UNREACHABLE_CODE_REACHED,
   /// Execution has potentially run too long and may be interrupted.
   WASMTIME_TRAP_CODE_INTERRUPT,
+  /// When the `component-model` feature is enabled this trap represents a
+  /// function that was `canon lift`'d, then `canon lower`'d, then called.
+  /// This combination of creation of a function in the component model
+  /// generates a function that always traps and, when called, produces this
+  /// flavor of trap.
+  WASMTIME_TRAP_CODE_ALWAYS_TRAP_ADAPTER,
   /// Execution has run out of the configured fuel amount.
   WASMTIME_TRAP_CODE_OUT_OF_FUEL,
+  /// Used to indicate that a trap was raised by atomic wait operations on non
+  /// shared memory.
+  WASMTIME_TRAP_CODE_ATOMIC_WAIT_NON_SHARED_MEMORY,
+  /// Call to a null reference.
+  WASMTIME_TRAP_CODE_NULL_REFERENCE,
+  /// Attempt to access beyond the bounds of an array.
+  WASMTIME_TRAP_CODE_ARRAY_OUT_OF_BOUNDS,
+  /// Attempted an allocation that was too large to succeed.
+  WASMTIME_TRAP_CODE_ALLOCATION_TOO_LARGE,
+  /// Attempted to cast a reference to a type that it is not an instance of.
+  WASMTIME_TRAP_CODE_CAST_FAILURE,
+  /// When the `component-model` feature is enabled this trap represents a
+  /// scenario where one component tried to call another component but it
+  /// would have violated the reentrance rules of the component model,
+  /// triggering a trap instead.
+  WASMTIME_TRAP_CODE_CANNOT_ENTER_COMPONENT,
+  /// Async-lifted export failed to produce a result by calling `task.return`
+  /// before returning `STATUS_DONE` and/or after all host tasks completed.
+  WASMTIME_TRAP_CODE_NO_ASYNC_RESULT,
+  /// A Pulley opcode was executed at runtime when the opcode was disabled at
+  /// compile time.
+  WASMTIME_TRAP_CODE_DISABLED_OPCODE,
 };
 
 /**
- * \brief Creates a new trap.
+ * \brief Creates a new trap with the given message.
  *
  * \param msg the message to associate with this trap
  * \param msg_len the byte length of `msg`
@@ -61,6 +89,15 @@ enum wasmtime_trap_code_enum {
  */
 WASM_API_EXTERN wasm_trap_t *wasmtime_trap_new(const char *msg, size_t msg_len);
 
+/**
+ * \brief Creates a new trap from the given trap code.
+ *
+ * \param code the trap code to associate with this trap
+ *
+ * The #wasm_trap_t returned is owned by the caller.
+ */
+WASM_API_EXTERN wasm_trap_t *wasmtime_trap_new_code(wasmtime_trap_code_t code);
+
 /**
  * \brief Attempts to extract the trap code from this trap.
  *

crates/c-api/include/wasmtime/trap.hh

@@ -129,7 +129,10 @@ public:
   explicit Trap(std::string_view msg)
       : Trap(wasmtime_trap_new(msg.data(), msg.size())) {}
 
-  /// Returns the descriptive message associated with this trap
+  /// Creates a new trap with the given wasmtime trap code.
+  Trap(wasmtime_trap_code_enum code) : Trap(wasmtime_trap_new_code(code)) {}
+
+  /// Returns the descriptive message associated with this trap.
   std::string message() const {
     wasm_byte_vec_t msg;
     wasm_trap_message(ptr.get(), &msg);

crates/c-api/src/trap.rs

@@ -65,6 +65,14 @@ pub unsafe extern "C" fn wasmtime_trap_new(message: *const u8, len: usize) -> Bo
     })
 }
 
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn wasmtime_trap_new_code(code: u8) -> Box<wasm_trap_t> {
+    let trap = Trap::from_u8(code).unwrap();
+    Box::new(wasm_trap_t {
+        error: Error::new(trap),
+    })
+}
+
 #[unsafe(no_mangle)]
 pub extern "C" fn wasm_trap_message(trap: &wasm_trap_t, out: &mut wasm_message_t) {
     let mut buffer = Vec::new();
@@ -121,22 +129,7 @@ pub extern "C" fn wasmtime_trap_code(raw: &wasm_trap_t, code: &mut u8) -> bool {
         Some(trap) => trap,
         None => return false,
     };
-    *code = match trap {
-        Trap::StackOverflow => 0,
-        Trap::MemoryOutOfBounds => 1,
-        Trap::HeapMisaligned => 2,
-        Trap::TableOutOfBounds => 3,
-        Trap::IndirectCallToNull => 4,
-        Trap::BadSignature => 5,
-        Trap::IntegerOverflow => 6,
-        Trap::IntegerDivisionByZero => 7,
-        Trap::BadConversionToInteger => 8,
-        Trap::UnreachableCodeReached => 9,
-        Trap::Interrupt => 10,
-        Trap::OutOfFuel => 11,
-        Trap::AlwaysTrapAdapter => unreachable!("component model not supported"),
-        _ => unreachable!(),
-    };
+    *code = *trap as u8;
     true
 }
 

crates/c-api/tests/trap.cc

@@ -29,8 +29,46 @@ TEST(Trap, Smoke) {
   for (auto &frame : trace) {
   }
 
-  EXPECT_TRUE(func.call(store, {}).err().message().find("unreachable") !=
+  auto unreachable_trap = std::get<Trap>(func.call(store, {}).err().data);
+
+  EXPECT_EQ(unreachable_trap.code(),
+            WASMTIME_TRAP_CODE_UNREACHABLE_CODE_REACHED);
+  EXPECT_TRUE(unreachable_trap.message().find("unreachable") !=
               std::string::npos);
   EXPECT_EQ(func.call(store, {1}).err().message(),
             "expected 0 arguments, got 1");
+
+  Trap out_of_fuel(WASMTIME_TRAP_CODE_OUT_OF_FUEL);
+  EXPECT_EQ(out_of_fuel.code(), WASMTIME_TRAP_CODE_OUT_OF_FUEL);
+  EXPECT_TRUE(out_of_fuel.message().find("all fuel consumed") !=
+              std::string::npos);
+}
+
+TEST(Trap, Codes) {
+#define TEST_CODE(trapcode)                                                    \
+  EXPECT_EQ(Trap(WASMTIME_TRAP_CODE_##trapcode).code(),                        \
+            WASMTIME_TRAP_CODE_##trapcode);
+
+  TEST_CODE(STACK_OVERFLOW);
+  TEST_CODE(MEMORY_OUT_OF_BOUNDS);
+  TEST_CODE(HEAP_MISALIGNED);
+  TEST_CODE(TABLE_OUT_OF_BOUNDS);
+  TEST_CODE(INDIRECT_CALL_TO_NULL);
+  TEST_CODE(BAD_SIGNATURE);
+  TEST_CODE(INTEGER_OVERFLOW);
+  TEST_CODE(INTEGER_DIVISION_BY_ZERO);
+  TEST_CODE(BAD_CONVERSION_TO_INTEGER);
+  TEST_CODE(UNREACHABLE_CODE_REACHED);
+  TEST_CODE(INTERRUPT);
+  TEST_CODE(ALWAYS_TRAP_ADAPTER);
+  TEST_CODE(OUT_OF_FUEL);
+  TEST_CODE(ATOMIC_WAIT_NON_SHARED_MEMORY);
+  TEST_CODE(NULL_REFERENCE);
+  TEST_CODE(ARRAY_OUT_OF_BOUNDS);
+  TEST_CODE(ALLOCATION_TOO_LARGE);
+  TEST_CODE(CAST_FAILURE);
+  TEST_CODE(CANNOT_ENTER_COMPONENT);
+  TEST_CODE(NO_ASYNC_RESULT);
+  TEST_CODE(DISABLED_OPCODE);
+#undef TEST_CODE
 }