From 721995c5213e99330ba353eae1f56f104c680ceb Mon Sep 17 00:00:00 2001 From: jlong145 Date: Wed, 10 Jan 2024 21:42:43 -0500 Subject: [PATCH] add jsdoc comments --- src/InstanceWrapper.ts | 82 ++++++++++++++++++++++++++++++++++++++ src/WasmInstanceWrapper.ts | 46 ++++++++++++++++++++- 2 files changed, 127 insertions(+), 1 deletion(-) diff --git a/src/InstanceWrapper.ts b/src/InstanceWrapper.ts index 6e692d6..27a8dc0 100644 --- a/src/InstanceWrapper.ts +++ b/src/InstanceWrapper.ts @@ -7,15 +7,52 @@ import { WorkerBridge } from "./WorkerBridge.ts"; import { WorkerManager } from "./WorkerManager.ts"; import { WorkerMethod, WorkerWrapper } from "./WorkerWrapper.ts"; +/** + * Base class for worker imlementation + * All methods within a class which extends this + * will be run within the web worker + * + * @example + * export class FibDefinition extends WorkerDefinition { + * constructor() { + * super(); + * } + * + * public method fib(buffer: SharedArrayBuffer, args: Record): Promise { + * var a = 1, b = 0, temp; + + while (num >= 0){ + temp = a; + a = a + b; + b = temp; + num--; + } + let buff = new Uint8Array(buffer); + buff[0] = b; + * } +* } + */ export class WorkerDefinition { public execMap: Record< string, (args: Record) => Promise > = {}; + + /** + * worker instance, can be stopped by calling terminateWorker + */ public worker: Worker | undefined = undefined; constructor() {} + /** + * Run implemented methods from within the worker instance + * + * example: await workerDefintion.execute('foo', {bar: true}); + * @param {keyof} name of method impleemnted on this class + * @param {Record} args to pass to the method + * @returns {SharedArrayBuffer} + */ public execute( name: keyof this, args: Record = {}, @@ -23,11 +60,49 @@ export class WorkerDefinition { return this.execMap[name as unknown as string](args); } + /** + * Calls terminate on the worker instace + */ public terminateWorker() { this.worker?.terminate(); } } +/** + * Creates a new worker and initalizes it with methods from + * the class instance provided. Currently will create the worker as a module + * the current implementation will bind onmessage handlers in the worker + * the imlpementation is used internally and should not be modified. + * **note** when using with file generation, the worker instance will be loaded into the global object as `worker` + * + * @example + * class FibWorkerDefinition extends Worker Definition { + * + * constructor() { super(); } + * + * public method fib(buffer: SharedArrayBuffer, args: Record): Promise { + * var a = 1, b = 0, temp; + cosnt num = args.limit; + while (num >= 0){ + temp = a; + a = a + b; + b = temp; + num--; + } + let buff = new Uint8Array(buffer); + buff[0] = b; + * } + * } + * + * const fibWorker = new FibWorkerDefinition(); + * const wrapper = new InstanceWrapper(fibWorker, {}); + * // start the worker + * await wrapper.start(); + * let buffer = await fibWorker.execute('fib', {limit: 20}); + * + * // log the result + * console.log(new Uint8Array(buffer)[0]); + */ export class InstanceWrapper { private _config: InstanceConfiguration; private _instance: WorkerInstance; @@ -90,6 +165,9 @@ export class InstanceWrapper { ); } + /** + * Regenerates the worker + */ public restart() { this?._wb?.workerBootstrap( this._instance as T, @@ -99,6 +177,10 @@ export class InstanceWrapper { ); } + /** + * Creates the worker and bridging as generated output as `bridge` to a directory + * the bootstrapping logic will load methods from the provided instance to the global object + */ public create(provider: DiskIOProvider): void { const byteEncoder = new TextEncoder(); diff --git a/src/WasmInstanceWrapper.ts b/src/WasmInstanceWrapper.ts index 2355e88..926fde1 100644 --- a/src/WasmInstanceWrapper.ts +++ b/src/WasmInstanceWrapper.ts @@ -7,28 +7,64 @@ import { WorkerBridge } from "./WorkerBridge.ts"; import { WorkerManager } from "./WorkerManager.ts"; import { WorkerMethod, WorkerWrapper } from "./WorkerWrapper.ts"; +/** + * Base class for worker imlementation. + * All methods within a class which extends this + * Allows for WASM modules to be loaded and initalized + * through a file path as a constructor argument. If any + * supporting javascript is needed, it may be loaded through + * configuring `addons` when configuring the Wrapper. + */ export class WasmWorkerDefinition { public execMap: Record< string, (options?: Record) => Promise > = {}; + + /** + * Worker instance, can be stopped by calling terminateWorker + */ public worker: Worker | undefined = undefined; + + /** + * Path to the WASM module being loaded into the worker. + */ public ModulePath: string; + private workerString = ""; constructor(modulePath: string) { this.ModulePath = modulePath; } + /** + * Run implemented methods from within the worker instance + * @example + * await workerDefintion.execute('foo', {bar: true}); + * @param {keyof} name of method impleemnted on this class + * @param {Record} args to pass to the method + * @returns {SharedArrayBuffer} + */ public execute(name: keyof this, options?: any): Promise { return this.execMap[name as unknown as string](options); } + /** + * Calls terminate on the worker instace + */ public terminateWorker() { this.worker?.terminate(); } } +/** + * Creates a new worker and initalizes it with methods from + * the class instance provided. Currently will create the worker as a module + * the current implementation will bind onmessage handlers in the worker + * the imlpementation is used internally and should not be modified. + * + * **note** when using with file generation, the worker instance will be loaded into the global object as `worker` + */ export class WasmInstanceWrapper { private _instance: WasmWorkerInstance; private _config: InstanceConfiguration; @@ -134,7 +170,8 @@ export class WasmInstanceWrapper { } /** - * Creates + * Create the web worker, adds an instance of a Worker object to the given class instance. + * Current only supports the `onmessage` handler. but object may be accesed as the `worker` property */ public async start() { this?._wb?.bufferMap(this._instance); @@ -150,6 +187,10 @@ export class WasmInstanceWrapper { ); } + /** + * Creates the worker and bridging as generated output as `bridge` to a directory + * the bootstrapping logic will load methods from the provided instance to the global object + */ public create(provider: DiskIOProvider): void { if (!this._config.outputPath) { throw new Error( @@ -171,6 +212,9 @@ ${this?._wm?.CreateOnMessageHandler()}`; ); } + /** + * Regenerates the worker + */ public restart() { this?._wb?.workerBootstrap( this._instance as T,