Add Caller.captureBacktrace() (#328)

This allows a Wasm host function to capture a back trace, which can be useful for debugging.

Author: pcbeard

Sources/WasmKit/Execution/Errors.swift

@@ -3,19 +3,19 @@ import WasmTypes
 import struct WasmParser.Import
 
 /// The backtrace of the trap.
-struct Backtrace: CustomStringConvertible, Sendable {
+public struct Backtrace: CustomStringConvertible, Sendable {
     /// A symbol in the backtrace.
-    struct Symbol: @unchecked Sendable {
+    public struct Symbol: @unchecked Sendable {
         /// The name of the symbol.
-        let name: String?
+        public let name: String?
         let address: Pc
     }
 
     /// The symbols in the backtrace.
-    let symbols: [Symbol]
+    public let symbols: [Symbol]
 
     /// Textual description of the backtrace.
-    var description: String {
+    public var description: String {
         symbols.enumerated().map { (index, symbol) in
             let name = symbol.name ?? "unknown"
             return "    \(index): (\(symbol.address)) \(name)"

Sources/WasmKit/Execution/Execution.swift

@@ -711,7 +711,8 @@ extension Execution {
         let instance = self.currentInstance(sp: sp)
         let caller = Caller(
             instanceHandle: instance,
-            store: store.value
+            store: store.value,
+            sp: sp
         )
         let results = try function.implementation(caller, Array(parameters))
         guard resolvedType.results.count == results.count else {

Sources/WasmKit/Execution/Function.swift

@@ -34,6 +34,9 @@ import struct WasmTypes.FunctionType
 /// }
 /// ```
 public struct Function: Equatable {
+    /// The type of a host function implementation closure.
+    public typealias Implementation = (borrowing Caller, [Value]) throws -> [Value]
+
     internal let handle: InternalFunction
     let store: Store
 
@@ -52,7 +55,7 @@ public struct Function: Equatable {
     public init(
         store: Store,
         parameters: [ValueType], results: [ValueType] = [],
-        body: @escaping (Caller, [Value]) throws -> [Value]
+        body: @escaping Implementation
     ) {
         self.init(store: store, type: FunctionType(parameters: parameters, results: results), body: body)
     }
@@ -66,7 +69,7 @@ public struct Function: Equatable {
     public init(
         store: Store,
         type: FunctionType,
-        body: @escaping (Caller, [Value]) throws -> [Value]
+        body: @escaping Implementation
     ) {
         self.init(handle: store.allocator.allocate(type: type, implementation: body, engine: store.engine), store: store)
     }

Sources/WasmKit/Execution/Runtime.swift

@@ -181,13 +181,13 @@ public final class Runtime {
 @available(*, deprecated, renamed: "Function", message: "`HostFunction` is now unified with `Function`")
 public struct HostFunction {
     @available(*, deprecated, renamed: "Function.init(store:type:implementation:)", message: "Use `Engine`-based API instead")
-    public init(type: FunctionType, implementation: @escaping (Caller, [Value]) throws -> [Value]) {
+    public init(type: FunctionType, implementation: @escaping Function.Implementation) {
         self.type = type
         self.implementation = implementation
     }
 
     public let type: FunctionType
-    public let implementation: (Caller, [Value]) throws -> [Value]
+    public let implementation: Function.Implementation
 }
 
 /// A collection of globals and functions that are exported from a host module.

Sources/WasmKit/Execution/Store.swift

@@ -36,8 +36,11 @@ extension Store: Equatable {
 }
 
 /// A caller context passed to host functions
-public struct Caller {
+/// Not copyable to avoid storing stale stack pointer.
+public struct Caller: ~Copyable {
     private let instanceHandle: InternalInstance?
+    /// The stack pointer at the point of the host function call.
+    private let sp: Sp?
     /// The instance that called the host function.
     /// - Note: This property is `nil` if a `Function` backed by a host function is called directly.
     public var instance: Instance? {
@@ -55,15 +58,25 @@ public struct Caller {
     @available(*, unavailable, message: "Use `engine` instead")
     public var runtime: Runtime { fatalError() }
 
-    init(instanceHandle: InternalInstance?, store: Store) {
+    init(instanceHandle: InternalInstance?, store: Store, sp: Sp? = nil) {
         self.instanceHandle = instanceHandle
         self.store = store
+        self.sp = sp
+    }
+
+    /// Captures the current WebAssembly call stack backtrace.
+    ///
+    /// Returns `nil` if the caller context does not have stack pointer information
+    /// (e.g., when a host function is called directly rather than from WebAssembly).
+    public func captureBacktrace() -> Backtrace? {
+        guard let sp else { return nil }
+        return Execution.captureBacktrace(sp: sp, store: store)
     }
 }
 
 struct HostFunctionEntity {
     let type: InternedFuncType
-    let implementation: (Caller, [Value]) throws -> [Value]
+    let implementation: Function.Implementation
 }
 
 extension Store {

Sources/WasmKit/Execution/StoreAllocator.swift

@@ -510,7 +510,7 @@ extension StoreAllocator {
 
     internal func allocate(
         type: FunctionType,
-        implementation: @escaping (Caller, [Value]) throws -> [Value],
+        implementation: @escaping Function.Implementation,
         engine: Engine
     ) -> InternalFunction {
         let pointer = hostFunctions.allocate(

Sources/WasmKitWASI/WASIBridgeToHost+WasmKit.swift

@@ -33,7 +33,7 @@ extension WASIBridgeToHost {
         }
     }
 
-    private func makeHostFunction(_ function: WASIHostFunction) -> ((Caller, [Value]) throws -> [Value]) {
+    private func makeHostFunction(_ function: WASIHostFunction) -> Function.Implementation {
         { caller, values -> [Value] in
             guard case .memory(let memory) = caller.instance?.export("memory") else {
                 throw WASIError(description: "Missing required \"memory\" export")