wasmslime/src/instance.zig

const Engine = @import("./engine.zig").Engine;
const Module = @import("./module.zig").Module;
const Store = @import("./store.zig").Store;
const Memory = @import("./memory.zig").Memory;
const Diagnostics = @import("./diagnostics.zig").Diagnostics;
const Error = @import("./error.zig").Error;
const Trap = @import("./trap.zig").Trap;
const Name = @import("./vec.zig").Name;
const Vec = @import("./vec.zig").Vec;

const _extern = @import("./extern.zig");
const Extern = _extern.Extern;
const ExternType = _extern.ExternType;

/// Representation of a instance in Wasmtime.
///
/// Instances are represented with a 64-bit identifying integer in Wasmtime.
/// They do not have any destructor associated with them. Instances cannot
/// interoperate between `Store` instances and if the wrong instance is passed
/// to the wrong store then it may trigger an assertion to abort the process.
pub const Instance = extern struct {
    /// Internal identifier of what store this belongs to, never zero.
    store_id: u64,
    /// Internal index within the store.
    index: usize,

    /// This function will instantiate a WebAssembly module with the provided
    /// imports, creating a WebAssembly instance. The returned instance can
    /// then afterwards be inspected for exports.
    ///
    /// This function requires that `imports` is the same size as the imports
    /// that `module` has. Additionally the `imports` array must be 1:1 lined
    /// up with the imports of the `module` specified. This is intended to be
    /// relatively low level, and `Linker` is provided for a more ergonomic
    /// name-based resolution API.
    ///
    /// Note that this function requires that all `imports` specified must be
    /// owned by the `Store` represented by the `context` provided as well.
    ///
    /// This function does not take ownership of any of its arguments, but all
    /// return values (Error or Trap) are owned by the caller.
    pub fn init(
        context: *Store.Context,
        module: *const Module,
        imports: []const Extern,
        diag: ?*Diagnostics,
    ) !Instance {
        var result: Instance = undefined;
        var trap: ?*Trap = null;
        const err = wasmtime_instance_new(context, module, imports.ptr, imports.len, &result, &trap);
        return try Diagnostics.handleErrorOrTrap(err, error.InstanceInit, trap, result, diag);
    }

    /// Gets an exported `Extern` by name from this instance, converted to the
    /// specified type. If `T` is `Extern` no conversion is done.
    ///
    /// Returns `error.ExportNotFound` if export with that name is not found.
    /// Returns `error.IncorrectType` if the export isn't the right type.
    pub fn get(
        self: *const Instance,
        context: *Store.Context,
        name: []const u8,
        comptime T: type,
    ) !T {
        var result: Extern = undefined;
        return if (wasmtime_instance_export_get(context, self, name.ptr, name.len, &result)) result.as(T) else error.ExportNotFound;
    }

    /// Get an exported `Memory`'s data slice from this instance.
    ///
    /// Returns `error.ExportNotFound` if export with that name is not found.
    /// Returns `error.IncorrectType` if the export isn't the a `Memory`.
    pub fn getData(
        self: *const Instance,
        context: *Store.Context,
        name: []const u8,
    ) ![]u8 {
        return (try self.get(context, name, Memory)).getData(context);
    }

    /// Gets an exported `Extern` by index from this instance, converted to
    /// the specified type. If `T` is `Extern` no conversion is done.
    ///
    /// Returns `error.ExportNotFound` if export with that name is not found.
    /// Returns `error.IncorrectType` if the export isn't the right type.
    pub fn getByIndex(
        self: *const Instance,
        context: *Store.Context,
        index: usize,
        comptime T: type,
    ) !struct { result: T, name: []const u8 } {
        var result: Extern = undefined;
        var name: [*]const u8 = null;
        var name_len: usize = undefined;
        return if (wasmtime_instance_export_nth(context, self, index, &name, &name_len, &result))
            .{ .result = result.as(T), .name = name[0..name_len] }
        else
            error.ExportNotFound;
    }

    extern "c" fn wasmtime_instance_new(*Store.Context, *const Module, [*]const Extern, usize, *Instance, *?*Trap) ?*Error;
    extern "c" fn wasmtime_instance_export_get(*Store.Context, *const Instance, [*]const u8, usize, *Extern) bool;
    extern "c" fn wasmtime_instance_export_nth(*Store.Context, *const Instance, usize, *[*]const u8, *usize, *Extern) bool;
};

/// An opaque object representing the type of an import.
pub const ImportType = opaque {
    /// Returns the module this import is importing from.
    pub fn getModule(self: *const ImportType) []const u8 {
        return wasm_importtype_module(self).toSlice();
    }

    /// Returns the name this import is importing from.
    ///
    /// Note that `null` can be returned which means that the import name is
    /// not provided. This is for imports with the module linking proposal
    /// that only have the module specified.
    pub fn getName(self: *const ImportType) ?[]const u8 {
        return if (wasm_importtype_name(self)) |name| name.toSlice() else null;
    }

    /// Returns the type of item this import is importing.
    pub fn getType(self: *const ImportType) *const ExternType {
        return wasm_importtype_type(self);
    }

    // extern "c" fn wasm_importtype_new(*Name, *Name, *ExternType) *ImportType;
    // extern "c" fn wasm_importtype_copy(*const ImportType) *ImportType;
    extern "c" fn wasm_importtype_module(*const ImportType) *const Name;
    extern "c" fn wasm_importtype_name(*const ImportType) ?*const Name;
    extern "c" fn wasm_importtype_type(*const ImportType) *const ExternType;
};

pub const ImportTypeVec = Vec(*ImportType, wasm_importtype_vec_new_empty, wasm_importtype_vec_new_uninitialized, wasm_importtype_vec_new, wasm_importtype_vec_copy, wasm_importtype_vec_delete);
extern "c" fn wasm_importtype_vec_new_empty(*anyopaque, usize) void;
extern "c" fn wasm_importtype_vec_new_uninitialized(*anyopaque, usize) void;
extern "c" fn wasm_importtype_vec_new(*anyopaque, usize, [*]const ?*ImportType) void;
extern "c" fn wasm_importtype_vec_copy(*anyopaque, *const anyopaque) void;
extern "c" fn wasm_importtype_vec_delete(*anyopaque) void;

/// An opaque object representing the type of an export.
pub const ExportType = opaque {
    /// Returns the name of this export.
    pub fn getName(self: *const ExportType) ?[]const u8 {
        return if (wasm_exporttype_name(self)) |name| name.toSlice() else null;
    }

    /// Returns the type of this export.
    pub fn getType(self: *const ExportType) *const ExternType {
        return wasm_exporttype_type(self);
    }

    // extern "c" fn wasm_exporttype_new(*Name, *Name, *ExternType) *ExportType;
    // extern "c" fn wasm_exporttype_copy(*const ExportType) *ExportType;
    extern "c" fn wasm_exporttype_name(*const ExportType) ?*const Name;
    extern "c" fn wasm_exporttype_type(*const ExportType) *const ExternType;
};

pub const ExportTypeVec = Vec(*ExportType, wasm_exporttype_vec_new_empty, wasm_exporttype_vec_new_uninitialized, wasm_exporttype_vec_new, wasm_exporttype_vec_copy, wasm_exporttype_vec_delete);
extern "c" fn wasm_exporttype_vec_new_empty(*anyopaque, usize) void;
extern "c" fn wasm_exporttype_vec_new_uninitialized(*anyopaque, usize) void;
extern "c" fn wasm_exporttype_vec_new(*anyopaque, usize, [*]const ?*ImportType) void;
extern "c" fn wasm_exporttype_vec_copy(*anyopaque, *const anyopaque) void;
extern "c" fn wasm_exporttype_vec_delete(*anyopaque) void;