@thi.ng/wasm-api 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-08-07T15:28:01Z
+- **Last updated**: 2022-08-08T22:36:17Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,17 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [0.5.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.5.0) (2022-08-08)
+
+#### 🚀 Features
+
+- add memory allocation ([980c1f2](https://github.com/thi-ng/umbrella/commit/980c1f2))
+  - add WasmBridge.allocate()/free()
+  - add WasmBridge.growMemory()
+  - extract WasmBridge.ensureMemory()
+  - update WasmExports
+  - update Zig bindings (configurable allocator, GPA as default)
+
 ## [0.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.4.0) (2022-08-07)
 
 #### 🚀 Features

package/api.d.ts

@@ -27,7 +27,8 @@ export interface IWasmAPI<T extends WasmExports = WasmExports> {
 }
 /**
  * Base interface of exports declared by the WASM module. At the very least, the
- * module needs to export its memory.
+ * module needs to export its memory and the functions defined in this
+ * interface.
  *
  * @remarks
  * This interface is supposed to be extended with the concrete exports defined
@@ -39,9 +40,32 @@ export interface IWasmAPI<T extends WasmExports = WasmExports> {
 export interface WasmExports {
     /**
      * The WASM module's linear memory buffer. The `WasmBridge` automatically
-     * creates various typed views of that memory.
+     * creates various typed views of that memory (i.e. u8, u16, u32, f32 etc.)
      */
     memory: WebAssembly.Memory;
+    /**
+     * Implementation specific memory allocation function (likely heap-based).
+     * If successful returns address of new memory block, or zero if
+     * unsuccessful.
+     *
+     * @remarks
+     * In the supplied Zig bindings (see `/zig/core.zig`), by default this is
+     * using the `std.heap.GeneralPurposeAllocator` (which also automatically
+     * handles growing the WASM memory), however as mentioned the underlying
+     * mechanism is purposefully left to the actual WASM-side implementation. In
+     * a C program, this would likely use `malloc()` or similar...
+     */
+    _wasm_allocate(numBytes: number): number;
+    /**
+     * Implementation specific function to free a previously allocated chunk of
+     * of WASM memory (allocated via {@link WasmExports._wasm_allocate}).
+     *
+     * @remarks
+     * In the supplied Zig bindings (/zig/core.zig) this is a no-op (currently).
+     *
+     * @param addr
+     */
+    _wasm_free(addr: number): void;
 }
 /**
  * Core API of WASM imports defined by the {@link WasmBridge}. The same

package/bridge.d.ts

@@ -1,6 +1,17 @@
+/// <reference types="node" />
 import type { NumericArray } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
 import type { BigIntArray, CoreAPI, IWasmAPI, WasmExports } from "./api.js";
+export declare const OutOfMemoryError: {
+    new (msg?: string | undefined): {
+        name: string;
+        message: string;
+        stack?: string | undefined;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function | undefined): void;
+    prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
+    stackTraceLimit: number;
+};
 /**
  * The main interop API bridge between the JS host environment and a WebAssembly
  * module. This class provides a small core API with various typed accessors and
@@ -58,6 +69,11 @@ export declare class WasmBridge<T extends WasmExports = WasmExports> {
      * @param exports
      */
     init(exports: T): Promise<boolean>;
+    /**
+     * Called automatically. Initializes and/or updates the various typed WASM
+     * memory views (e.g. after growing the WASM memory).
+     */
+    ensureMemory(): void;
     /**
      * Required use for WASM module instantiation to provide JS imports to the
      * module. Returns an object of all WASM imports declared by the bridge core
@@ -65,8 +81,9 @@ export declare class WasmBridge<T extends WasmExports = WasmExports> {
      *
      * @remarks
      * Since v0.4.0 each API module's imports will be in their own WASM import
-     * table, named using the same key which was assigned to the module when
-     * creating the WASM bridge.
+     * object, named using the same key which was assigned to the module when
+     * creating the WASM bridge. The bridge's core API will be named `core` and
+     * is reserved.
      *
      * @example
      * The following creates a bridge with a fictional `custom` API module:
@@ -92,6 +109,27 @@ export declare class WasmBridge<T extends WasmExports = WasmExports> {
      * ```
      */
     getImports(): WebAssembly.Imports;
+    /**
+     * Attempts to grow the WASM memory by an additional `numPages` (64KB/page)
+     * and if successful updates all typed memory views to use the new
+     * underlying buffer.
+     *
+     * @param numPages
+     */
+    growMemory(numPages: number): void;
+    /**
+     * Attempts to allocate `numBytes` using the exported WASM core API function
+     * {@link WasmExports._wasm_allocate} (implementation specific) and returns
+     * start address of the new memory block. If unsuccessful, throws an
+     * {@link OutOfMemoryError}.
+     *
+     * @remarks
+     * See {@link WasmExports._wasm_allocate} docs for further details.
+     *
+     * @param numBytes
+     */
+    allocate(numBytes: number): number;
+    free(addr: number): void;
     getI8(addr: number): number;
     getU8(addr: number): number;
     getI16(addr: number): number;

package/bridge.js

@@ -1,7 +1,9 @@
+import { defError } from "@thi.ng/errors/deferror";
 import { illegalArgs } from "@thi.ng/errors/illegal-arguments";
 import { U16, U32, U64HL, U8 } from "@thi.ng/hex";
 import { ConsoleLogger } from "@thi.ng/logger/console";
 const B32 = BigInt(32);
+export const OutOfMemoryError = defError(() => "Out of memory");
 /**
  * The main interop API bridge between the JS host environment and a WebAssembly
  * module. This class provides a small core API with various typed accessors and
@@ -85,7 +87,23 @@ export class WasmBridge {
      */
     async init(exports) {
         this.exports = exports;
-        const buf = exports.memory.buffer;
+        this.ensureMemory();
+        for (let id in this.modules) {
+            this.logger.debug(`initializing API module: ${id}`);
+            const status = await this.modules[id].init(this);
+            if (!status)
+                return false;
+        }
+        return true;
+    }
+    /**
+     * Called automatically. Initializes and/or updates the various typed WASM
+     * memory views (e.g. after growing the WASM memory).
+     */
+    ensureMemory() {
+        const buf = this.exports.memory.buffer;
+        if (this.u8 && this.u8.buffer === buf)
+            return;
         this.i8 = new Int8Array(buf);
         this.u8 = new Uint8Array(buf);
         this.i16 = new Int16Array(buf);
@@ -96,13 +114,6 @@ export class WasmBridge {
         this.u64 = new BigUint64Array(buf);
         this.f32 = new Float32Array(buf);
         this.f64 = new Float64Array(buf);
-        for (let id in this.modules) {
-            this.logger.debug(`initializing API module: ${id}`);
-            const status = await this.modules[id].init(this);
-            if (!status)
-                return false;
-        }
-        return true;
     }
     /**
      * Required use for WASM module instantiation to provide JS imports to the
@@ -111,8 +122,9 @@ export class WasmBridge {
      *
      * @remarks
      * Since v0.4.0 each API module's imports will be in their own WASM import
-     * table, named using the same key which was assigned to the module when
-     * creating the WASM bridge.
+     * object, named using the same key which was assigned to the module when
+     * creating the WASM bridge. The bridge's core API will be named `core` and
+     * is reserved.
      *
      * @example
      * The following creates a bridge with a fictional `custom` API module:
@@ -149,6 +161,40 @@ export class WasmBridge {
         }
         return this.imports;
     }
+    /**
+     * Attempts to grow the WASM memory by an additional `numPages` (64KB/page)
+     * and if successful updates all typed memory views to use the new
+     * underlying buffer.
+     *
+     * @param numPages
+     */
+    growMemory(numPages) {
+        this.exports.memory.grow(numPages);
+        this.ensureMemory();
+    }
+    /**
+     * Attempts to allocate `numBytes` using the exported WASM core API function
+     * {@link WasmExports._wasm_allocate} (implementation specific) and returns
+     * start address of the new memory block. If unsuccessful, throws an
+     * {@link OutOfMemoryError}.
+     *
+     * @remarks
+     * See {@link WasmExports._wasm_allocate} docs for further details.
+     *
+     * @param numBytes
+     */
+    allocate(numBytes) {
+        const addr = this.exports._wasm_allocate(numBytes);
+        if (!addr)
+            throw new OutOfMemoryError(`unable to allocate: ${numBytes}`);
+        this.logger.debug(`allocated ${numBytes} bytes @ 0x${U32(addr)}`);
+        this.ensureMemory();
+        return addr;
+    }
+    free(addr) {
+        this.logger.debug(`freeing memory @ 0x${U32(addr)}`);
+        this.exports._wasm_free(addr);
+    }
     getI8(addr) {
         return this.i8[addr];
     }
@@ -303,7 +349,7 @@ export class WasmBridge {
     setString(str, addr, maxBytes, terminate = true) {
         maxBytes = Math.min(maxBytes, this.u8.length - addr);
         const len = this.utf8Encoder.encodeInto(str, this.u8.subarray(addr, addr + maxBytes)).written;
-        if (len != null && len < maxBytes + (terminate ? 0 : 1)) {
+        if (len == null || len >= maxBytes + (terminate ? 0 : 1)) {
             illegalArgs(`error writing string to 0x${U32(addr)}`);
         }
         if (terminate) {

package/dev/hello.zig

@@ -3,6 +3,11 @@
 /// import externals
 /// see build command for configuration
 const js = @import("wasmapi");
+const std = @import("std");
+
+// var buf: [1024]u8 = undefined;
+// var fba = std.heap.FixedBufferAllocator.init(&buf);
+pub const WASM_ALLOCATOR: ?std.mem.Allocator = null; //fba.allocator();
 
 export fn start() void {
     js.printStr("hello world!");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/wasm-api",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Modular, extensible API bridge and generic glue code between JS & WebAssembly",
   "type": "module",
   "module": "./index.js",
@@ -31,7 +31,8 @@
     "doc:readme": "yarn doc:stats && tools:readme",
     "doc:stats": "tools:module-stats",
     "pub": "yarn npm publish --access public",
-    "test": "testament test"
+    "test": "testament test",
+    "test:build-zig": "zig build-lib -O ReleaseSmall -target wasm32-freestanding -dynamic --strip --pkg-begin wasmapi zig/core.zig --pkg-end test/custom.zig && wasm-dis -o custom.wast custom.wasm && cp custom.wasm test"
   },
   "dependencies": {
     "@thi.ng/api": "^8.3.9",
@@ -92,5 +93,5 @@
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "0eeb5054111cea51f4714b013dda8700ade3cd54\n"
+  "gitHead": "e579cb171fc720cbf0b71d3a5f4adfacccdaf214\n"
 }

package/test/custom.zig

@@ -1,7 +1,11 @@
 // Import JS core API
 const js = @import("wasmapi");
+const std = @import("std");
+
+pub const WASM_ALLOCATOR: ?std.mem.Allocator = null;
 
 /// Fill vec2 with random values
+/// Associate this function with the "custom" import section
 extern "custom" fn setVec2(addr: usize) void;
 
 export fn test_setVec2() void {

package/test/zig-cache/o/117d44467ded6ce3864cde3c180ef73c/builtin.zig

@@ -0,0 +1,39 @@
+const std = @import("std");
+/// Zig version. When writing code that supports multiple versions of Zig, prefer
+/// feature detection (i.e. with `@hasDecl` or `@hasField`) over version checks.
+pub const zig_version = std.SemanticVersion.parse("0.10.0-dev.3034+6fab6c3e4") catch unreachable;
+pub const zig_backend = std.builtin.CompilerBackend.stage1;
+/// Temporary until self-hosted supports the `cpu.arch` value.
+pub const stage2_arch: std.Target.Cpu.Arch = .wasm32;
+
+pub const output_mode = std.builtin.OutputMode.Lib;
+pub const link_mode = std.builtin.LinkMode.Dynamic;
+pub const is_test = false;
+pub const single_threaded = true;
+pub const abi = std.Target.Abi.musl;
+pub const cpu: std.Target.Cpu = .{
+    .arch = .wasm32,
+    .model = &std.Target.wasm.cpu.generic,
+    .features = std.Target.wasm.featureSet(&[_]std.Target.wasm.Feature{
+    }),
+};
+pub const os = std.Target.Os{
+    .tag = .freestanding,
+    .version_range = .{ .none = {} },
+};
+pub const target = std.Target{
+    .cpu = cpu,
+    .os = os,
+    .abi = abi,
+};
+pub const object_format = std.Target.ObjectFormat.wasm;
+pub const mode = std.builtin.Mode.ReleaseSmall;
+pub const link_libc = false;
+pub const link_libcpp = false;
+pub const have_error_return_tracing = false;
+pub const valgrind_support = false;
+pub const sanitize_thread = false;
+pub const position_independent_code = true;
+pub const position_independent_executable = false;
+pub const strip_debug_info = true;
+pub const code_model = std.builtin.CodeModel.default;

package/zig/core.zig

@@ -1,5 +1,42 @@
 //! JavaScript externals for https://thi.ng/wasm-api
 
+const std = @import("std");
+const root = @import("root");
+
+/// Initialize the allocator to be exposed to the WASM host env
+/// (via `_wasm_allocate()` and `_wasm_free()`).
+/// If the user defines a public `WASM_ALLOCATOR` in their root file
+/// then this allocator will be used, otherwise the implementation
+/// falls back to using GPA.
+/// Note: The type for this var is purposefully chosen as an optional,
+/// effectively disabling allocations from the WASM host side if
+/// `WASM_ALLOCATOR` is set to null.
+pub const allocator: ?std.mem.Allocator = alloc: {
+    if (@hasDecl(root, "WASM_ALLOCATOR")) {
+        break :alloc root.WASM_ALLOCATOR;
+    } else {
+        var gpa = std.heap.GeneralPurposeAllocator(.{}){};
+        break :alloc gpa.allocator();
+    }
+};
+
+/// Attempts to allocate memory using configured `allocator` and if
+/// successful returns address of new chunk or zero if failed
+/// Note: For SIMD compatibility all allocations are aligned to 16 bytes
+pub export fn _wasm_allocate(numBytes: usize) usize {
+    if (allocator) |a| {
+        var buf = a.alignedAlloc(u8, 16, numBytes) catch return 0;
+        return @ptrToInt(buf.ptr);
+    }
+    return 0;
+}
+
+/// Frees chunk of heap memory (previously allocated using `_wasm_allocate()`)
+/// starting at given address. Note: This is a no-op currently.
+pub export fn _wasm_free(addr: usize) void {
+    _ = addr;
+}
+
 /// Prints number using configured JS logger
 pub extern "core" fn printI8(x: i8) void;
 /// Prints number using configured JS logger