Engine API: Minor documentation updates and add accessors for entities

Author: kateinoigakukun

Sources/WasmKit/Docs.docc/Docs.md

@@ -89,20 +89,26 @@ See [examples](https://github.com/swiftwasm/WasmKit/tree/main/Examples) for exec
 
 ### Basic Concepts
 
+- ``Engine``
+- ``Store``
 - ``Module``
 - ``Instance``
-- ``Runtime``
-- ``Store``
+- ``Function``
 
 ### Binary Parser
 
 - ``parseWasm(bytes:features:)``
 - ``parseWasm(filePath:features:)``
 
+### Other WebAssembly Entities
+
+- ``Global``
+- ``Memory``
+- ``Table``
+
 ### Extending Runtime
 
-- ``HostModule``
-- ``HostFunction``
+- ``Imports``
 - ``Caller``
 - ``GuestMemory``
 - ``UnsafeGuestPointer``

Sources/WasmKit/Engine.swift

@@ -1,7 +1,12 @@
 import _CWasmKit.Platform
 
 /// A WebAssembly execution engine.
+///
+/// An engine is responsible storing the configuration for the execution of
+/// WebAssembly code such as interpreting mode, enabled features, etc.
+/// Typically, you will need a single engine instance per application.
 public final class Engine {
+    /// The engine configuration.
     public let configuration: EngineConfiguration
     let interceptor: EngineInterceptor?
     let funcTypeInterner: Interner<FunctionType>
@@ -22,6 +27,7 @@ public final class Engine {
     public func instantiate(module: Module) -> Instance { fatalError() }
 }
 
+/// The configuration for the WebAssembly execution engine.
 public struct EngineConfiguration {
     /// The threading model, which determines how to dispatch instruction
     /// execution, to use for the virtual machine interpreter.

Sources/WasmKit/Execution/Instances.swift

@@ -143,7 +143,7 @@ public struct Exports: Sequence {
 }
 
 /// A stateful instance of a WebAssembly module.
-/// Usually instantiated by ``Runtime/instantiate(module:)``.
+/// Usually instantiated by ``Module/instantiate(store:imports:)``.
 /// > Note:
 /// <https://webassembly.github.io/spec/core/exec/runtime.html#module-instances>
 public struct Instance {
@@ -310,6 +310,30 @@ typealias InternalTable = EntityHandle<TableEntity>
 public struct Table: Equatable {
     let handle: InternalTable
     let allocator: StoreAllocator
+
+    init(handle: InternalTable, allocator: StoreAllocator) {
+        self.handle = handle
+        self.allocator = allocator
+    }
+
+    /// Creates a new table instance with the given type.
+    public init(store: Store, type: TableType) throws {
+        self.init(
+            handle: try store.allocator.allocate(tableType: type, resourceLimiter: store.resourceLimiter),
+            allocator: store.allocator
+        )
+    }
+
+    /// The type of the table instance.
+    public var type: TableType {
+        handle.tableType
+    }
+
+    /// Accesses the element at the given index.
+    public subscript(index: Int) -> Reference {
+        get { handle.elements[index] }
+        nonmutating set { handle.withValue { $0.elements[index] = newValue } }
+    }
 }
 
 struct MemoryEntity /* : ~Copyable */ {
@@ -389,6 +413,11 @@ public struct Memory: Equatable {
     public var data: [UInt8] {
         handle.data
     }
+
+    /// The type of the memory instance.
+    public var type: MemoryType {
+        handle.limit
+    }
 }
 
 extension Memory: GuestMemory {

Sources/WasmKit/Execution/Runtime.swift

@@ -205,8 +205,9 @@ public final class Runtime {
 ///     return []
 /// }
 /// ```
+@available(*, deprecated, renamed: "Function", message: "`HostFunction` is now unified with `Function`")
 public struct HostFunction {
-    // @available(*, deprecated, renamed: "Function.init(store:type:implementation:)")
+    @available(*, deprecated, renamed: "Function.init(store:type:implementation:)", message: "Use `Engine`-based API instead")
     public init(type: FunctionType, implementation: @escaping (Caller, [Value]) throws -> [Value]) {
         self.type = type
         self.implementation = implementation
@@ -217,6 +218,7 @@ public struct HostFunction {
 }
 
 /// A collection of globals and functions that are exported from a host module.
+@available(*, deprecated, message: "Use `Imports`")
 public struct HostModule {
     public init(
         globals: [String: Global] = [:],

Sources/WasmKit/Execution/Store.swift

@@ -16,7 +16,7 @@ public final class Store {
     /// The allocator allocating and retaining resources for this store.
     let allocator: StoreAllocator
     /// The engine associated with this store.
-    let engine: Engine
+    public let engine: Engine
 
     /// Create a new store associated with the given engine.
     public init(engine: Engine) {

Sources/WasmKit/Execution/StoreAllocator.swift

@@ -467,7 +467,7 @@ extension StoreAllocator {
 
     /// > Note:
     /// <https://webassembly.github.io/spec/core/exec/modules.html#alloc-table>
-    private func allocate(tableType: TableType, resourceLimiter: any ResourceLimiter) throws -> InternalTable {
+    func allocate(tableType: TableType, resourceLimiter: any ResourceLimiter) throws -> InternalTable {
         let pointer = try tables.allocate(initializing: TableEntity(tableType, resourceLimiter: resourceLimiter))
         return InternalTable(unsafe: pointer)
     }

Sources/WasmKitWASI/WASIBridgeToHost+WasmKit.swift

@@ -16,6 +16,7 @@ extension WASIBridgeToHost {
         }
     }
 
+    @available(*, deprecated, renamed: "link(to:store:)", message: "Use `Engine`-based API instead")
     public var hostModules: [String: HostModule] {
         wasiHostModules.mapValues { (module: WASIHostModule) -> HostModule in
             HostModule(

Sources/WasmParser/Docs.docc/Docs.md

@@ -60,7 +60,6 @@ while let payload = try parser.parseNext() {
 
 ### Core Module Elements
 
-- ``FunctionType``
 - ``Import``
 - ``ImportDescriptor``
 - ``Export``

Sources/WasmParser/InstructionVisitor.swift

@@ -1243,9 +1243,7 @@ public struct InstructionTracingVisitor<V: InstructionVisitor>: InstructionVisit
 /// A visitor for WebAssembly instructions.
 ///
 /// The visitor pattern is used while parsing WebAssembly expressions to allow for easy extensibility.
-/// See the following parsing functions:
-/// - ``parseExpression(bytes:features:hasDataCount:visitor:)``
-/// - ``parseExpression(stream:features:hasDataCount:visitor:)``
+/// See the expression parsing method ``Code/parseExpression(visitor:)``
 public protocol InstructionVisitor {
 
     /// The return type of visitor methods.

Utilities/Sources/WasmGen.swift

@@ -61,9 +61,7 @@ enum WasmGen {
             /// A visitor for WebAssembly instructions.
             ///
             /// The visitor pattern is used while parsing WebAssembly expressions to allow for easy extensibility.
-            /// See the following parsing functions:
-            /// - ``parseExpression(bytes:features:hasDataCount:visitor:)``
-            /// - ``parseExpression(stream:features:hasDataCount:visitor:)``
+            /// See the expression parsing method ``Code/parseExpression(visitor:)``
             public protocol InstructionVisitor {
 
                 /// The return type of visitor methods.