@daneren2005/shared-memory-objects 0.0.2 → 0.0.4

package/README.md

@@ -1,6 +1,9 @@
 # Shared Memory Objects
 A library to try to make making a multi-threaded game in Javascript possible.  This package is to provide a wrapper to create objects and data structures that are backed by a SharedArrayBuffer and can be shared between multiple threads.  The end result is a package that has all of the slowness of Javascript with all of the baggage of dealing with manual memory allocations.  If you need to multi-thread you are probably better of just using a different language and compiling to WebAssembly.  But if you, like me, just want to use Javascript/Typescript and are willing to deal with dealing with manual memory allocations then this library could save you some time.
 
+A demo can be found at https://daneren2005.github.io/ecs-sharedarraybuffer-playground/#/shared-memory-objects  
+The code is at https://github.com/daneren2005/ecs-sharedarraybuffer-playground/tree/dev/src/shared-memory-objects
+
 ## Basics
 The core of this package is the MemoryHeap.  You should usually just have a single heap that is shared between all of your different threads.  Each heap can have multiple MemoryBuffers.  By default each buffer is only 8KB but it can be configured up to 1MB, and you can have up to 4k buffers for a total of 4GB.  When you allocate memory, if there is not enough space it will allocate another buffers automatically.  When allocating memory, you will get a AllocatedMemory object that is a wrapper around the allocated memory by calling `heap.allocUI32({count of 32 bit numbers})`.  By default AllocatedMemory is backed by a Uint32Array but you can get any type of array from `AllocatedMemory.getArray(Int32Array);`.
 
@@ -8,6 +11,50 @@ Each allocated memory location can be stored as an int pointer.  You can use `ge
 
 When passing memory to another thread you can either pass a pointer or a serialized version of the buffer position/byte offset in order to re-create the object in the other thread.
 
+## Getting Started
+`npm install @daneren2005/shared-memory-objects`
+
+Example to update blocks of memory from a thread.
+```
+let heap = new MemoryHeap();
+let memory = heap.allocUI32(4);
+
+// Pass memory to another thread
+thread.postMessage({
+	heap: heap.getSharedMemory(),
+	memory: memory.getSharedMemory()
+});
+
+// From worker thread re-construct memory and change it
+self.onmessage = (e) => {
+	let heap = new MemoryHeap(e.data.heap);
+	let memory = new AllocatedMemory(heap, e.data.memory);
+	memory.data[2] = 5;
+};
+```
+
+// Example to work with data structures from a thread.  When constructing a new structure you just pass the heap.  When re-creating a structure from an already initialized memory location pass the heap and the shared memory location for it.
+```
+let heap = new MemoryHeap();
+let list = new SharedList(heap);
+
+// Pass memory to another thread
+thread.postMessage({
+	heap: heap.getSharedMemory(),
+	list: list.getSharedMemory()
+});
+
+// From worker thread re-construct memory and change it
+self.onmessage = (e) => {
+	let heap = new MemoryHeap(e.data.heap);
+	let list = new SharedList(heap, e.data.list);
+
+	list.push(5);
+};
+```
+let mainList = new SharedList(memory);
+let secondList = new SharedList(memory, mainList.getSharedMemory());
+
 ## Data Structures
 - SharedList
 - SharedVector

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daneren2005/shared-memory-objects",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "author": "daneren2005@gmail.com",
   "description": "Creating objects with a SharedArrayBuffer",
   "homepage": "https://github.com/daneren2005/shared-memory-objects#readme",
@@ -34,7 +34,8 @@
     "test:ui": "vitest --ui --api 9527",
     "test:unit": "vitest run",
     "test:unit:watch": "vitest",
-    "type-check": "tsc --build --force"
+    "type-check": "tsc --build --force",
+    "prepare": "husky"
   },
   "devDependencies": {
     "@rushstack/eslint-patch": "^1.10.1",

package/src/main.ts

@@ -1,14 +1,15 @@
 import AllocatedMemory, { type SharedAllocatedMemory } from './allocated-memory';
 import MemoryBuffer from './memory-buffer';
-import MemoryHeap, { type MemoryHeapMemory } from './memory-heap';
+import MemoryHeap, { type MemoryHeapMemory, type GrowBufferData } from './memory-heap';
 
 import SharedList, { type SharedListMemory } from './shared-list';
-import SharedMap from './shared-map';
+import SharedMap, { type SharedMapMemory } from './shared-map';
 import SharedPointerList from './shared-pointer-list';
 import SharedString from './shared-string';
-import SharedVector from './shared-vector';
+import SharedVector, { type SharedVectorMemory } from './shared-vector';
 
-import type { TypedArrayConstructor } from './interfaces/typed-array-constructor';
+export * from './interfaces/typed-array';
+export * from './interfaces/typed-array-constructor';
 
 export * from './utils/16-from-32-array';
 export * from './utils/16-from-64-array';
@@ -23,13 +24,14 @@ export {
 	MemoryBuffer,
 	MemoryHeap,
 	type MemoryHeapMemory,
+	type GrowBufferData,
 
 	SharedList,
 	type SharedListMemory,
 	SharedMap,
+	type SharedMapMemory,
 	SharedPointerList,
 	SharedString,
 	SharedVector,
-
-	type TypedArrayConstructor
+	type SharedVectorMemory
 };

package/src/memory-buffer.ts

@@ -265,7 +265,7 @@ export default class MemoryBuffer {
 		let block = this._used;
 		while(block) {
 			if(block === addr) {
-				return this.blockSize(addr);
+				return this.blockSize(addr) - SIZEOF_MEM_BLOCK;
 			}
 			block = this.blockNext(block);
 		}

package/src/memory-heap.ts

@@ -1,18 +1,19 @@
-import AllocatedMemory from './allocated-memory';
+import AllocatedMemory, { type SharedAllocatedMemory } from './allocated-memory';
 import prettyBytes from 'pretty-bytes';
 import { MAX_BYTE_OFFSET_LENGTH, MAX_POSITION_LENGTH } from './utils/pointer';
 import MemoryBuffer from './memory-buffer';
 
-// TODO: Once we are certain this behaves correctly we should probably up to something like 1MB - we will have a ton of entities so don't want to waste time allocating new buffers constantly
 const DEFAULT_BUFFER_SIZE = 8_192;
+const BUFFER_SIZE_INDEX = 0;
+const BUFFER_COUNT_INDEX = 1;
 export default class MemoryHeap {
 	buffers: Array<MemoryBuffer>;
-	onGrowBufferHandlers: Array<OnGrowBuffer> = [];
+	private onGrowBufferHandlers: Array<OnGrowBuffer> = [];
 	isClone: boolean;
 	private memory: AllocatedMemory;
 
 	get bufferSize() {
-		return this.memory.data[0];
+		return this.memory.data[BUFFER_SIZE_INDEX];
 	}
 
 	constructor(config?: MemoryHeapConfig | MemoryHeapMemory) {
@@ -40,7 +41,7 @@ export default class MemoryHeap {
 			this.buffers = [
 				startBuffer
 			];
-			const data = startBuffer.callocAs('u32', 1);
+			const data = startBuffer.callocAs('u32', 2);
 			if(data) {
 				this.memory = new AllocatedMemory(this, {
 					bufferPosition: 0,
@@ -49,7 +50,8 @@ export default class MemoryHeap {
 			} else {
 				throw new Error('Failed to initialize first byte from buffer');
 			}
-			this.memory.data[0] = bufferSize;
+			this.memory.data[BUFFER_SIZE_INDEX] = bufferSize;
+			this.memory.data[BUFFER_COUNT_INDEX] = 1;
 			this.isClone = false;
 
 			for(let i = 1; i < (config?.initialBuffers ?? 1); i++) {
@@ -58,28 +60,37 @@ export default class MemoryHeap {
 		}
 	}
 
-	addSharedBuffer(buffer: SharedArrayBuffer) {
-		this.buffers.push(new MemoryBuffer({
-			buf: buffer,
+	addSharedBuffer(data: GrowBufferData) {
+		this.buffers[data.bufferPosition] = new MemoryBuffer({
+			buf: data.buffer,
 			skipInitialization: true
-		}));
+		});
 	}
 
 	private createBuffer(bufferSize?: number): MemoryBuffer {
-		if(this.isClone) {
-			throw new Error('Creating new buffer from worker threads not currently supported');
-		}
-
-		// TODO: Look into if we should turn off splitting - I think memory is going to get fragmented really quick if we free an Entity with 100 bytes and re-allocate a new one with 80 bytes and just lose the rest
-		//       As we add stuff like ListMemory that does tons of small allocations that might be fine since they can fill in any small space we have
 		return new MemoryBuffer({
-			buf: new SharedArrayBuffer(bufferSize ?? this.bufferSize)
+			buf: new SharedArrayBuffer(bufferSize ?? this.bufferSize),
+
+			// We can't use this unless we can 100% guarantee that every thread will stop using memory the instant it is freed
+			// ex: Allocate 16 bytes.  Thread A frees that allocation and then allocates 12 bytes and 4 bytes, but Thread B is mid-execution on the old allocation can changes the internal state of the 4-byte allocation breaking everything
+			// After the internal state is wrong MemoryBuffer will loose track of which blocks are where and how big they are
+			compact: false,
+			split: false
 		});
 	}
 
+	addOnGrowBufferHandlers(handler: OnGrowBuffer) {
+		this.onGrowBufferHandlers.push(handler);
+	}
+
 	allocUI32(count: number): AllocatedMemory {
 		for(let i = 0; i < this.buffers.length; i++) {
 			const buffer = this.buffers[i];
+			// Should just mean we haven't synced this buffer from another thread yet
+			if(!buffer) {
+				continue;
+			}
+
 			// Should be fine to initialize all values as 0s since unsigned/signed ints and floats all store 0 as all 0s
 			const data = buffer.callocAs('u32', count);
 			if(data) {
@@ -96,8 +107,13 @@ export default class MemoryHeap {
 
 		// If we get here we need to grow another buffer to continue allocating new memory
 		const buffer = this.createBuffer();
-		this.buffers.push(buffer);
-		this.onGrowBufferHandlers.forEach(handler => handler(buffer.buf as SharedArrayBuffer));
+		let nextBufferPosition = Atomics.add(this.memory.data, BUFFER_COUNT_INDEX, 1);
+		// Setting index set by internal Atomic count so we can create new buffers from multiple threads and keep position consistent
+		this.buffers[nextBufferPosition] = buffer;
+		this.onGrowBufferHandlers.forEach(handler => handler({
+			bufferPosition: nextBufferPosition,
+			buffer: buffer.buf as SharedArrayBuffer
+		}));
 
 		const data = buffer.callocAs('u32', count);
 		if(data) {
@@ -110,6 +126,15 @@ export default class MemoryHeap {
 		}
 	}
 
+	getSharedAlloc(shared: SharedAllocatedMemory): AllocatedMemory | undefined {
+		// Should just mean it hasn't synced to this thread yet
+		if(this.buffers[shared.bufferPosition] === undefined) {
+			return undefined;
+		}
+
+		return new AllocatedMemory(this, shared);
+	}
+
 	get currentUsed() {
 		return this.totalAllocated - this.buffers.reduce((total, memPool) => total + memPool.stats().available, 0);
 	}
@@ -136,7 +161,11 @@ function myPrettyBytes(bytes: number) {
 	});
 }
 
-type OnGrowBuffer = (newBuffer: SharedArrayBuffer) => void;
+type OnGrowBuffer = (newBuffer: GrowBufferData) => void;
+interface GrowBufferData {
+	bufferPosition: number
+	buffer: SharedArrayBuffer
+}
 
 interface MemoryHeapConfig {
 	bufferSize?: number
@@ -146,4 +175,4 @@ interface MemoryHeapMemory {
 	buffers: Array<SharedArrayBuffer>
 }
 
-export type { MemoryHeapConfig, MemoryHeapMemory };
+export type { MemoryHeapConfig, MemoryHeapMemory, GrowBufferData };

package/src/shared-list.ts

@@ -62,6 +62,7 @@ export default class SharedList<T extends Uint32Array | Int32Array | Float32Arra
 		this.memory = memory;
 
 		if(config && 'firstBlock' in config) {
+			// TODO: How to handle referencing memory we don't have access to yet because buffer not synced from worker?
 			this.firstBlock = new AllocatedMemory(memory, config.firstBlock);
 			this.uint16Array = new Uint16Array(this.firstBlock.data.buffer, this.firstBlock.bufferByteOffset + (LENGTH_INDEX + 1) * Uint32Array.BYTES_PER_ELEMENT, 2);
 		} else {
@@ -119,6 +120,7 @@ export default class SharedList<T extends Uint32Array | Int32Array | Float32Arra
 
 		if(lastBlockPointer) {
 			let { bufferPosition: lastBlockPosition, bufferByteOffset: lastBlockByteOffset } = getPointer(lastBlockPointer);
+			// TODO: How to handle referencing memory we don't have access to yet because buffer not synced from worker?
 			let lastBlock = new Uint32Array(this.memory.buffers[lastBlockPosition].buf, lastBlockByteOffset, 1);
 			storeRawPointer(lastBlock, 0, newBlockPointer);
 		} else {
@@ -175,6 +177,11 @@ export default class SharedList<T extends Uint32Array | Int32Array | Float32Arra
 		let lastBlockByteOffset = 0;
 		while(nextBlockByteOffset) {
 			let memPool = this.memory.buffers[nextBlockPosition];
+			// Short circuit iterations if we can't access memory
+			if(!memPool) {
+				return;
+			}
+
 			let blockRecord = new Uint32Array(memPool.buf, nextBlockByteOffset, 2);
 			let blockData = this.getDataBlock(blockRecord);