Engine API: Migrate CLI module

Author: kateinoigakukun

Sources/CLI/Commands/Explore.swift

@@ -14,24 +14,28 @@ struct Explore: ParsableCommand {
 
     func run() throws {
         let module = try parseWasm(filePath: FilePath(path))
-        var hostModuleStubs: [String: HostModule] = [:]
+        // Instruction dumping requires token threading model for now
+        let configuration = EngineConfiguration(threadingModel: .token)
+        let engine = Engine(configuration: configuration)
+        let store = Store(engine: engine)
+
+        var imports: Imports = [:]
         for importEntry in module.imports {
-            var hostModule = hostModuleStubs[importEntry.module] ?? HostModule()
             switch importEntry.descriptor {
             case .function(let typeIndex):
                 let type = module.types[Int(typeIndex)]
-                hostModule.functions[importEntry.name] = HostFunction(type: type) { _, _ in
-                    fatalError("unreachable")
-                }
+                imports.define(
+                    module: importEntry.module,
+                    name: importEntry.name,
+                    Function(store: store, type: type) { _, _ in
+                        fatalError("unreachable")
+                    }
+                )
             default:
                 fatalError("Import \(importEntry) not supported in explore mode yet")
             }
-            hostModuleStubs[importEntry.module] = hostModule
         }
-        // Instruction dumping requires token threading model for now
-        let configuration = EngineConfiguration(threadingModel: .token)
-        let runtime = Runtime(hostModules: hostModuleStubs, configuration: configuration)
-        let instance = try runtime.instantiate(module: module)
+        let instance = try module.instantiate(store: store, imports: imports)
         var stdout = Stdout()
         try instance.dumpFunctions(to: &stdout, module: module)
     }

Sources/CLI/Commands/Run.swift

@@ -161,10 +161,13 @@ struct Run: ParsableCommand {
             $0[$1] = $1
         }
         let wasi = try WASIBridgeToHost(args: [path] + arguments, environment: environment, preopens: preopens)
-        let runtime = Runtime(hostModules: wasi.hostModules, interceptor: interceptor, configuration: deriveRuntimeConfiguration())
-        let moduleInstance = try runtime.instantiate(module: module)
+        let engine = Engine(configuration: deriveRuntimeConfiguration(), interceptor: interceptor)
+        let store = Store(engine: engine)
+        var imports = Imports()
+        wasi.link(to: &imports, store: store)
+        let moduleInstance = try module.instantiate(store: store, imports: imports)
         return {
-            let exitCode = try wasi.start(moduleInstance, runtime: runtime)
+            let exitCode = try wasi.start(moduleInstance)
             throw ExitCode(Int32(exitCode))
         }
     }
@@ -192,11 +195,16 @@ struct Run: ParsableCommand {
             return nil
         }
 
-        let runtime = Runtime(interceptor: interceptor, configuration: deriveRuntimeConfiguration())
-        let moduleInstance = try runtime.instantiate(module: module)
+        let engine = Engine(configuration: deriveRuntimeConfiguration(), interceptor: interceptor)
+        let store = Store(engine: engine)
+        let instance = try module.instantiate(store: store)
         return {
             log("Started invoking function \"\(functionName)\" with parameters: \(parameters)", verbose: true)
-            let results = try runtime.invoke(moduleInstance, function: functionName, with: parameters)
+            guard let toInvoke = instance.exports[function: functionName] else {
+                log("Error: Function \"\(functionName)\" not found in the module.")
+                return
+            }
+            let results = try toInvoke.invoke(parameters)
             print(results.description)
         }
     }

Sources/WasmKit/Engine.swift

@@ -16,6 +16,10 @@ public final class Engine {
         self.interceptor = interceptor
         self.funcTypeInterner = Interner()
     }
+
+    /// Migration aid for the old ``Runtime/instantiate(module:)``
+    @available(*, unavailable, message: "Use ``Module/instantiate(store:imports:)`` instead")
+    public func instantiate(module: Module) -> Instance { fatalError() }
 }
 
 public struct EngineConfiguration {

Sources/WasmKit/Execution/Instances.swift

@@ -82,6 +82,61 @@ struct InstanceEntity /* : ~Copyable */ {
 
 typealias InternalInstance = EntityHandle<InstanceEntity>
 
+/// A map of exported entities by name.
+public struct Exports: Sequence {
+    let store: Store
+    let values: [String: InternalExternalValue]
+
+    /// Returns the exported entity with the given name.
+    public subscript(_ name: String) -> ExternalValue? {
+        guard let entity = values[name] else { return nil }
+        return ExternalValue(handle: entity, store: store)
+    }
+
+    /// Returns the exported function with the given name.
+    public subscript(function name: String) -> Function? {
+        guard case .function(let function) = self[name] else { return nil }
+        return function
+    }
+
+    /// Returns the exported table with the given name.
+    public subscript(table name: String) -> Table? {
+        guard case .table(let table) = self[name] else { return nil }
+        return table
+    }
+
+    /// Returns the exported memory with the given name.
+    public subscript(memory name: String) -> Memory? {
+        guard case .memory(let memory) = self[name] else { return nil }
+        return memory
+    }
+
+    /// Returns the exported global with the given name.
+    public subscript(global name: String) -> Global? {
+        guard case .global(let global) = self[name] else { return nil }
+        return global
+    }
+
+    public struct Iterator: IteratorProtocol {
+        private let store: Store
+        private var iterator: Dictionary<String, InternalExternalValue>.Iterator
+
+        init(parent: Exports) {
+            self.store = parent.store
+            self.iterator = parent.values.makeIterator()
+        }
+
+        public mutating func next() -> (String, ExternalValue)? {
+            guard let (name, entity) = iterator.next() else { return nil }
+            return (name, ExternalValue(handle: entity, store: store))
+        }
+    }
+
+    public func makeIterator() -> Iterator {
+        Iterator(parent: self)
+    }
+}
+
 /// A stateful instance of a WebAssembly module.
 /// Usually instantiated by ``Runtime/instantiate(module:)``.
 /// > Note:
@@ -113,11 +168,9 @@ public struct Instance {
         return function
     }
 
-    public typealias Exports = [String: ExternalValue]
-
     /// A dictionary of exported entities by name.
     public var exports: Exports {
-        handle.exports.mapValues { ExternalValue(handle: $0, store: store) }
+        Exports(store: store, values: handle.exports)
     }
 
     /// Dumps the textual representation of all functions in the instance.

Sources/WasmKit/Execution/Runtime.swift

@@ -24,6 +24,7 @@ public final class Runtime {
     /// - Parameter hostModules: Host module names mapped to their corresponding ``HostModule`` definitions.
     /// - Parameter interceptor: An optional runtime interceptor to intercept execution of instructions.
     /// - Parameter configuration: An optional runtime configuration to customize the runtime behavior.
+    @available(*, deprecated)
     public init(
         hostModules: [String: HostModule] = [:],
         interceptor: EngineInterceptor? = nil,
@@ -59,7 +60,7 @@ extension Runtime {
             throw ImportError.moduleInstanceAlreadyRegistered(name)
         }
 
-        availableExports[name] = instance.exports
+        availableExports[name] = Dictionary(uniqueKeysWithValues: instance.exports)
     }
 
     /// Legacy compatibility method to register a host module with a name.

Sources/WasmKit/Imports.swift

@@ -9,15 +9,15 @@ public struct Imports {
     }
 
     /// Define a value to be imported by the given module and name.
-    public mutating func define(module: String, name: String, _ value: ExternalValue) {
-        definitions[module, default: [:]][name] = value
+    public mutating func define<Extern: ExternalValueConvertible>(module: String, name: String, _ value: Extern) {
+        definitions[module, default: [:]][name] = value.externalValue
     }
 
     /// Define a set of values to be imported by the given module.
     /// - Parameters:
     ///   - module: The module name to be used for resolving the imports.
     ///   - values: The values to be imported keyed by their name.
-    public mutating func define(module: String, _ values: Instance.Exports) {
+    public mutating func define(module: String, _ values: Exports) {
         definitions[module, default: [:]].merge(values, uniquingKeysWith: { _, new in new })
     }
 
@@ -36,6 +36,10 @@ public protocol ExternalValueConvertible {
     var externalValue: ExternalValue { get }
 }
 
+extension ExternalValue: ExternalValueConvertible {
+    public var externalValue: ExternalValue { self }
+}
+
 extension Memory: ExternalValueConvertible {
     public var externalValue: ExternalValue { .memory(self) }
 }

Sources/WasmKitWASI/WASIBridgeToHost+WasmKit.swift

@@ -4,30 +4,50 @@ import WasmKit
 public typealias WASIBridgeToHost = WASI.WASIBridgeToHost
 
 extension WASIBridgeToHost {
+    public func link(to imports: inout Imports, store: Store) {
+        var imports = Imports()
+        for (moduleName, module) in wasiHostModules {
+            for (name, function) in module.functions {
+                imports.define(
+                    module: moduleName,
+                    name: name,
+                    Function(store: store, type: function.type, body: makeHostFunction(function))
+                )
+            }
+        }
+    }
+
     public var hostModules: [String: HostModule] {
         wasiHostModules.mapValues { (module: WASIHostModule) -> HostModule in
             HostModule(
                 functions: module.functions.mapValues { function -> HostFunction in
-                    makeHostFunction(function)
+                    HostFunction(type: function.type, implementation: makeHostFunction(function))
                 })
         }
     }
 
-    private func makeHostFunction(_ function: WASIHostFunction) -> HostFunction {
-        HostFunction(type: function.type) { caller, values -> [Value] in
+    private func makeHostFunction(_ function: WASIHostFunction) -> ((Caller, [Value]) throws -> [Value]) {
+        { caller, values -> [Value] in
             guard case let .memory(memory) = caller.instance?.export("memory") else {
                 throw WASIError(description: "Missing required \"memory\" export")
             }
             return try function.implementation(memory, values)
         }
     }
 
-    public func start(_ instance: Instance, runtime: Runtime) throws -> UInt32 {
+    public func start(_ instance: Instance) throws -> UInt32 {
         do {
-            _ = try runtime.invoke(instance, function: "_start")
+            guard let start = instance.exports[function: "_start"] else {
+                throw WASIError(description: "Missing required \"_start\" function")
+            }
+            _ = try start()
         } catch let code as WASIExitCode {
             return code.code
         }
         return 0
     }
+
+    public func start(_ instance: Instance, runtime: Runtime) throws -> UInt32 {
+        return try start(instance)
+    }
 }