@thi.ng/wasm-api 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-08-23T10:37:04Z
+- **Last updated**: 2022-08-24T09:52:32Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,18 @@ 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.10.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.10.0) (2022-08-24)
+
+#### 🚀 Features
+
+- add events, update allocator handling ([89416b1](https://github.com/thi-ng/umbrella/commit/89416b1))
+  - add INotify impl for WasmBridge
+  - emit event when WASM memory has changed (e.g. to recreate user views)
+  - reverse logic so that NO allocator is used by default and instead must
+    be explicitly enabled (rather than disabled)
+  - update Zig & C bindings
+  - add/update docstrings
+
 ## [0.9.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.9.0) (2022-08-23)
 
 #### 🚀 Features

package/README.md

@@ -418,12 +418,28 @@ TypeScript code generator explicitly.
 
 ### Memory allocations
 
-The `WasmBridge` includes support for malloc/free-style allocations (within the
-linear WASM memory), _unless_ these are explicitly disabled on the WASM side. Please see for further reference:
-
-- [`/include/wasmapi.zig`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/include/wasmapi.zig#L6) - comments about WASM-side allocator handling
-- [`WasmBridge.allocate()`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmBridge.html#allocate) - allocating memory from JS side
-- [`WasmBridge.free()`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmBridge.html#free) - freeing previously allocated memory
+If explicitly enabled on the WASM side, the `WasmBridge` includes support for
+malloc/free-style allocations (within the linear WASM memory) from the JS side
+(Note: This is a breaking change in v0.10.0, now using a more flexible approach
+& reverse logic of earlier alpha versions).
+
+The actual allocator is implementation specific and suitable generic mechanisms
+are defined for both the included Zig & C bindings. Please see for further
+reference:
+
+- [`/include/wasmapi.zig`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/include/wasmapi.zig#L6):
+  comments about WASM-side allocator handling in Zig
+- [`/include/wasmapi.h`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/include/wasmapi.h#L19):
+  comments about WASM-side allocator handling in C/C++
+- [`WasmBridge.allocate()`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmBridge.html#allocate):
+  allocating memory from JS side
+- [`WasmBridge.free()`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmBridge.html#free):
+  freeing previously allocated memory from JS side
+
+Note: The provided Zig mechanism supports the idiomatic (Zig) pattern of working
+with multiple allocators in different parts of the application and supports
+dynamic assignments/swapping of the exposed allocator. See comments in source
+file for more details...
 
 ```ts
 try {
@@ -431,7 +447,7 @@ try {
 	const addr = bridge.allocate(256);
 
 	// write string to reserved memory
-	// max. 256 bytes written, zero terminated
+	// max. 256 bytes, zero terminated
 	const num = bridge.setString("hello WASM world!", addr, 256, true);
 
 	// call WASM function doing something w/ the string
@@ -440,7 +456,7 @@ try {
 	// cleanup
 	bridge.free(addr, 256);
 } catch(e) {
-	// allocation error
+	// deal with allocation error
 	// ...
 }
 ```
@@ -521,7 +537,7 @@ node --experimental-repl-await
 > const wasmApi = await import("@thi.ng/wasm-api");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 4.34 KB
+Package sizes (gzipped, pre-treeshake): ESM: 4.48 KB
 
 **IMPORTANT:** The package includes various code generators and supporting
 functions which are NOT required during runtime. Hence the actual package size

package/api.d.ts

@@ -1,6 +1,7 @@
 import type { BigType, FloatType, Fn, Fn2 } from "@thi.ng/api";
 import type { WasmBridge } from "./bridge.js";
 export declare const PKG_NAME = "@thi.ng/wasm-api";
+export declare const EVENT_MEMORY_CHANGED = "memory-changed";
 export declare type BigIntArray = bigint[] | BigInt64Array | BigUint64Array;
 /**
  * Common interface for WASM/JS child APIs which will be used in combination
@@ -27,9 +28,9 @@ export interface IWasmAPI<T extends WasmExports = WasmExports> {
     getImports(): WebAssembly.ModuleImports;
 }
 /**
- * Base interface of exports declared by the WASM module. At the very least, the
- * module needs to export its memory and the functions defined in this
- * interface.
+ * Base interface of exports declared by the WASM module. At the very least, a
+ * compatible 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
@@ -45,21 +46,34 @@ export interface WasmExports {
      */
     memory: WebAssembly.Memory;
     /**
-     * Implementation specific memory allocation function (likely heap-based).
-     * If successful returns address of new memory block, or zero if
-     * unsuccessful.
+     * Implementation specific WASM memory allocation function. 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...
+     * #### Zig
+     *
+     * Using the supplied Zig bindings (see `/include/wasmapi.zig`), it's the
+     * user's responsibility to define a public `WASM_ALLOCATOR` in the root
+     * source file to enable allocations, e.g. using the
+     * [`std.heap.GeneralPurposeAllocator`](https://ziglang.org/documentation/master/#Choosing-an-Allocator)
+     * (which also automatically handles growing the WASM memory). However, as
+     * mentioned, the underlying mechanism is purposefully left to the actual
+     * WASM-side implementation. If no allocator is defined this function
+     * returns zero, which in turn will cause {@link WasmBridge.allocate} to
+     * throw an error.
+     *
+     * #### C/C++
+     *
+     * Using the supplied C bindings (see `/include/wasmapi.h`), it's the user's
+     * responsibility to enable allocation support by defining the
+     * `WASMAPI_MALLOC` symbol (and compiling the WASM module with a malloc
+     * implementation).
      */
     _wasm_allocate(numBytes: number): number;
     /**
      * Implementation specific function to free a previously allocated chunk of
-     * of WASM memory (allocated via {@link WasmExports._wasm_allocate}).
+     * of WASM memory (allocated via {@link WasmExports._wasm_allocate}, also
+     * see remarks for that function).
      *
      * @param addr
      * @param numBytes

package/api.js

@@ -1,4 +1,5 @@
 export const PKG_NAME = "@thi.ng/wasm-api";
+export const EVENT_MEMORY_CHANGED = "memory-changed";
 /**
  * WASM usize type. Assuming wasm32 until wasm64 surfaces, then need an option.
  */

package/bridge.d.ts

@@ -1,7 +1,7 @@
 /// <reference types="node" />
-import type { NumericArray } from "@thi.ng/api";
+import type { Event, INotify, Listener, NumericArray } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
-import type { BigIntArray, CoreAPI, IWasmAPI, WasmExports, IWasmMemoryAccess } from "./api.js";
+import { BigIntArray, CoreAPI, IWasmAPI, WasmExports, IWasmMemoryAccess } from "./api.js";
 export declare const OutOfMemoryError: {
     new (msg?: string | undefined): {
         name: string;
@@ -28,7 +28,7 @@ export declare const OutOfMemoryError: {
  * 64bit integers are handled via JS `BigInt` and hence require the host env to
  * support it. No polyfill is provided.
  */
-export declare class WasmBridge<T extends WasmExports = WasmExports> implements IWasmMemoryAccess {
+export declare class WasmBridge<T extends WasmExports = WasmExports> implements IWasmMemoryAccess, INotify {
     modules: Record<string, IWasmAPI<T>>;
     logger: ILogger;
     i8: Int8Array;
@@ -66,14 +66,23 @@ export declare class WasmBridge<T extends WasmExports = WasmExports> implements
      * then initializes all declared bridge child API modules. Returns false if
      * any of the module initializations failed.
      *
+     * @remarks
+     * Emits the {@link EVENT_MEMORY_CHANGED} event just before returning (and
+     * AFTER all child API modules have been initialized).
+     *
      * @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).
+     * Called automatically during initialization. Initializes and/or updates
+     * the various typed WASM memory views (e.g. after growing the WASM memory
+     * and the previous buffer becoming detached). Unless `notify` is false,
+     * the {@link EVENT_MEMORY_CHANGED} event will be emitted if the memory
+     * views had to be updated.
+     *
+     * @param notify
      */
-    ensureMemory(): void;
+    ensureMemory(notify?: boolean): 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
@@ -137,6 +146,10 @@ export declare class WasmBridge<T extends WasmExports = WasmExports> implements
      * `numBytes` value must be the same as previously given to
      * {@link WasmBridge.allocate}.
      *
+     * @remarks
+     * This function always succeeds, regardless of presence of an active
+     * allocator on the WASM side or validity of given arguments.
+     *
      * @param addr
      * @param numBytes
      */
@@ -208,5 +221,11 @@ export declare class WasmBridge<T extends WasmExports = WasmExports> implements
      */
     setString(str: string, addr: number, maxBytes: number, terminate?: boolean): number;
     getElementById(addr: number, len?: number): HTMLElement;
+    /** {@inheritDoc @thi.ng/api#INotify.addListener} */
+    addListener(id: string, fn: Listener, scope?: any): boolean;
+    /** {@inheritDoc @thi.ng/api#INotify.removeListener} */
+    removeListener(id: string, fn: Listener, scope?: any): boolean;
+    /** {@inheritDoc @thi.ng/api#INotify.notify} */
+    notify(event: Event): void;
 }
 //# sourceMappingURL=bridge.d.ts.map

package/bridge.js

@@ -1,7 +1,10 @@
+import { __decorate } from "tslib";
+import { INotifyMixin } from "@thi.ng/api/mixins/inotify";
 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";
+import { EVENT_MEMORY_CHANGED, } from "./api.js";
 const B32 = BigInt(32);
 export const OutOfMemoryError = defError(() => "Out of memory");
 /**
@@ -20,7 +23,7 @@ export const OutOfMemoryError = defError(() => "Out of memory");
  * 64bit integers are handled via JS `BigInt` and hence require the host env to
  * support it. No polyfill is provided.
  */
-export class WasmBridge {
+let WasmBridge = class WasmBridge {
     constructor(modules = {}, logger = new ConsoleLogger("wasm")) {
         this.modules = modules;
         this.logger = logger;
@@ -86,24 +89,34 @@ export class WasmBridge {
      * then initializes all declared bridge child API modules. Returns false if
      * any of the module initializations failed.
      *
+     * @remarks
+     * Emits the {@link EVENT_MEMORY_CHANGED} event just before returning (and
+     * AFTER all child API modules have been initialized).
+     *
      * @param exports
      */
     async init(exports) {
         this.exports = exports;
-        this.ensureMemory();
+        this.ensureMemory(false);
         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;
         }
+        this.notify({ id: EVENT_MEMORY_CHANGED, value: this.exports.memory });
         return true;
     }
     /**
-     * Called automatically. Initializes and/or updates the various typed WASM
-     * memory views (e.g. after growing the WASM memory).
+     * Called automatically during initialization. Initializes and/or updates
+     * the various typed WASM memory views (e.g. after growing the WASM memory
+     * and the previous buffer becoming detached). Unless `notify` is false,
+     * the {@link EVENT_MEMORY_CHANGED} event will be emitted if the memory
+     * views had to be updated.
+     *
+     * @param notify
      */
-    ensureMemory() {
+    ensureMemory(notify = true) {
         const buf = this.exports.memory.buffer;
         if (this.u8 && this.u8.buffer === buf)
             return;
@@ -117,6 +130,11 @@ export class WasmBridge {
         this.u64 = new BigUint64Array(buf);
         this.f32 = new Float32Array(buf);
         this.f64 = new Float64Array(buf);
+        notify &&
+            this.notify({
+                id: EVENT_MEMORY_CHANGED,
+                value: this.exports.memory,
+            });
     }
     /**
      * Required use for WASM module instantiation to provide JS imports to the
@@ -192,7 +210,7 @@ export class WasmBridge {
         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.logger.debug(`allocated ${numBytes} bytes @ 0x${U32(addr)} .. 0x${U32(addr + numBytes - 1)}`);
         this.ensureMemory();
         clear && this.u8.fill(0, addr, addr + numBytes);
         return addr;
@@ -203,6 +221,10 @@ export class WasmBridge {
      * `numBytes` value must be the same as previously given to
      * {@link WasmBridge.allocate}.
      *
+     * @remarks
+     * This function always succeeds, regardless of presence of an active
+     * allocator on the WASM side or validity of given arguments.
+     *
      * @param addr
      * @param numBytes
      */
@@ -403,4 +425,17 @@ export class WasmBridge {
         el == null && illegalArgs(`missing DOM element #${id}`);
         return el;
     }
-}
+    /** {@inheritDoc @thi.ng/api#INotify.addListener} */
+    // @ts-ignore: mixin
+    addListener(id, fn, scope) { }
+    /** {@inheritDoc @thi.ng/api#INotify.removeListener} */
+    // @ts-ignore: mixin
+    removeListener(id, fn, scope) { }
+    /** {@inheritDoc @thi.ng/api#INotify.notify} */
+    // @ts-ignore: mixin
+    notify(event) { }
+};
+WasmBridge = __decorate([
+    INotifyMixin
+], WasmBridge);
+export { WasmBridge };

package/include/wasmapi.h

@@ -16,16 +16,17 @@ extern "C" {
 // Same as EMSCRIPTEN_KEEP_ALIVE, ensures symbol will be exported
 #define WASM_KEEP __attribute__((used))
 
-// Generate stubs only if explicitly disabled by defining this symbol
-#ifdef WASMAPI_NO_MALLOC
-size_t WASM_KEEP _wasm_allocate(size_t num_bytes) { return 0; }
-void WASM_KEEP _wasm_free(size_t addr) {}
-#else
+// Generate malloc/free wrappers only if explicitly enabled by defining this
+// symbol. If undefined some function stubs are exported.
+#ifdef WASMAPI_MALLOC
 #include <stdlib.h>
 size_t WASM_KEEP _wasm_allocate(size_t numBytes) {
   return (size_t)malloc(numBytes);
 }
 void WASM_KEEP _wasm_free(size_t addr) { free((void*)addr); }
+#else
+size_t WASM_KEEP _wasm_allocate(size_t num_bytes) { return 0; }
+void WASM_KEEP _wasm_free(size_t addr) {}
 #endif
 
 WASM_IMPORT("wasmapi", void, printI8, wasm_)(int8_t x);

package/include/wasmapi.zig

@@ -3,28 +3,26 @@
 const std = @import("std");
 const root = @import("root");
 
-/// Initialize the allocator to be exposed to the WASM host env
+/// Obtains 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.
+/// then this allocator will be used, otherwise the implementations
+/// of the two mentioned functions are no-ops.
+/// The `WASM_ALLOCATOR` can be changed and/or enabled/disabled dynamically
+/// This helper function here is used to always lookup the current value/impl.
+///
 /// 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();
-    }
-};
+/// effectively disabling allocations from the WASM host side if no
+/// `WASM_ALLOCATOR` is set (or set to null).
+pub fn allocator() ?std.mem.Allocator {
+    return if (@hasDecl(root, "WASM_ALLOCATOR")) root.WASM_ALLOCATOR else null;
+}
 
-/// Attempts to allocate memory using configured `allocator` and if
+/// 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) |alloc| {
+    if (allocator()) |alloc| {
         var mem = alloc.alignedAlloc(u8, 16, numBytes) catch return 0;
         return @ptrToInt(mem.ptr);
     }
@@ -33,11 +31,10 @@ pub export fn _wasm_allocate(numBytes: usize) usize {
 
 /// Frees chunk of heap memory (previously allocated using `_wasm_allocate()`)
 /// starting at given address and of given byte length.
-/// Note: This is a no-op if the allocator is explicitly disabled (see `setAllocator()`),
+/// Note: This is a no-op if no allocator is configured (see `allocator()`)
 pub export fn _wasm_free(addr: usize, numBytes: usize) void {
-    if (allocator) |alloc| {
+    if (allocator()) |alloc| {
         var mem = [2]usize{ addr, numBytes };
-        printFmt("{d}", .{@ptrCast(*[]u8, &mem).*});
         alloc.free(@ptrCast(*[]u8, &mem).*);
     }
 }
@@ -169,7 +166,7 @@ pub fn printStr(msg: []const u8) void {
 /// to output it via JS, then frees string's memory again
 /// (Only available if the allocator used by `_wasm_allocate()` hasn't been disabled.)
 pub fn printFmt(comptime fmt: []const u8, args: anytype) void {
-    if (allocator) |alloc| {
+    if (allocator()) |alloc| {
         const res = std.fmt.allocPrint(alloc, fmt, args) catch return;
         defer alloc.free(res);
         printStr(res);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/wasm-api",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Generic, modular, extensible API bridge, glue code and bindings code generator for hybrid JS & WebAssembly projects",
   "type": "module",
   "module": "./index.js",
@@ -57,14 +57,20 @@
     "typescript": "^4.7.4"
   },
   "keywords": [
+    "allocator",
     "api",
     "bindings",
     "c",
     "codegen",
+    "event",
     "id",
     "logger",
     "memory",
+    "string",
+    "struct",
+    "typedarray",
     "typescript",
+    "utf8",
     "wasm",
     "webassembly",
     "wrapper",
@@ -117,5 +123,5 @@
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "be8423e2019e95c14a096260a93b9762dde0c768\n"
+  "gitHead": "4264b91052b8c1f74db9fd51dc48c830dc0d5829\n"
 }