@daneren2005/shared-memory-objects 0.0.0 → 0.0.2

package/README.md

@@ -1,4 +1,28 @@
 # Shared Memory Objects
-A library to try to make making a multi-threaded game in Javascript possible.
+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.
 
-TODO
+## 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);`.
+
+Each allocated memory location can be stored as an int pointer.  You can use `getPointer(int)` to get the bufferPosition (ie: buffer index in the heap) and bufferByteOffset that the memory location points to.  You can also convert a bufferPosition/bufferByteOffset pair to an int pointer with `createPointer(bufferPosition, bufferByteOffset)`.  The pointer format is uses 12 bits for the buffer index and the remaining 20 bits for the byte offset in that buffer for a total of 1MB per buffer and 4GB total of memory.  Each allocated memory object can return either a pointer via `allocatedMemory.pointer` or the raw position/byte offset via `allocatedMemory.getSharedMemory()`.
+
+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.
+
+## Data Structures
+- SharedList
+- SharedVector
+- SharedMap
+- SharedString
+
+## Thread Safety
+- Memory allocations is thread safe as long as it does not need to create a new buffer.  Right now that can only be done from the main thread.
+- SharedList, SharedVector, and SharedMap are all not thread safe.
+- SharedString is thread safe with a lock on read/write with a cached version of the string so it doesn't need to lock after the first read unless the string has changed.
+
+## TODO
+- Make creating new buffers from allocations possible from multiple threads
+- Make data structures thread safe
+- Add basic thread safe object example
+
+## Credit
+The entire core of this library is based on a fork of @thi.ng/malloc found at https://github.com/thi-ng/umbrella/blob/develop/packages/malloc.  The only big difference between our MemoryBuffer and their MemPool is making allocations/freeing memory thread safe.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daneren2005/shared-memory-objects",
-  "version": "0.0.0",
+  "version": "0.0.2",
   "author": "daneren2005@gmail.com",
   "description": "Creating objects with a SharedArrayBuffer",
   "homepage": "https://github.com/daneren2005/shared-memory-objects#readme",
@@ -8,7 +8,6 @@
     "sharedarraybuffer"
   ],
   "license": "MIT",
-  
   "repository": {
     "type": "git",
     "url": "git+ssh://git@github.com/daneren2005/shared-memory-objects.git"
@@ -16,12 +15,15 @@
   "bugs": {
     "url": "https://github.com/daneren2005/shared-memory-objects/issues"
   },
-
   "type": "module",
   "files": [
-    "dist"
+    "src/",
+    "!__tests__"
   ],
   "main": "./src/main.ts",
+  "exports": {
+    ".": "./src/main.ts"
+  },
   "scripts": {
     "dev": "vite",
     "lint": "eslint src/ --ext .js,.cjs,.mjs,.ts,.cts,.mts --ignore-path .gitignore",

package/src/allocated-memory.ts

@@ -0,0 +1,84 @@
+import type { TypedArray } from './interfaces/typed-array';
+import type { TypedArrayConstructor } from './interfaces/typed-array-constructor';
+import type MemoryBuffer from './memory-buffer';
+import type MemoryHeap from './memory-heap';
+import { createPointer } from './utils/pointer';
+
+export default class AllocatedMemory {
+	private readonly memory: MemoryHeap;
+
+	readonly bufferPosition: number;
+	get bufferByteOffset(): number {
+		return this.data.byteOffset;
+	}
+	get pointer(): number {
+		return createPointer(this.bufferPosition, this.bufferByteOffset);
+	}
+	private buffer: MemoryBuffer;
+	data: Uint32Array;
+
+	constructor(memory: MemoryHeap, config: AllocatedMemoryConfig | SharedAllocatedMemory) {
+		this.memory = memory;
+
+		if('buffer' in config) {
+			this.data = config.data;
+			this.buffer = config.buffer;
+			this.bufferPosition = this.memory.buffers.indexOf(config.buffer);
+		} else {
+			this.bufferPosition = config.bufferPosition;
+			this.buffer = memory.buffers[config.bufferPosition];
+
+			// Making sure these are the correct size is slow but in dev we want to make sure we aren't allowing to go out of bounds
+			if(import.meta.env.MODE === 'production') {
+				this.data = new Uint32Array(this.buffer.buf, config.bufferByteOffset);
+			} else {
+				this.data = new Uint32Array(this.buffer.buf, config.bufferByteOffset, this.buffer.lengthOf(config.bufferByteOffset));
+			}
+		}
+	}
+
+	getArray<T extends TypedArray>(type: TypedArrayConstructor<T>, offset: number, length: number): T {
+		if(import.meta.env.MODE === 'development') {
+			if(offset + length > this.data.length) {
+				console.warn(`Trying to grab more memory from AllocatedMemory.getArray then we have: ${offset} + ${length} > ${this.data.length}`);
+			}
+		}
+
+		return new type(this.data.buffer, this.data.byteOffset + offset * type.BYTES_PER_ELEMENT, length);
+	}
+	getArrayMemory(offset: number, length: number): SharedAllocatedMemory {
+		if(import.meta.env.MODE === 'development') {
+			if(offset + length > this.data.length) {
+				console.warn(`Trying to grab more memory from AllocatedMemory.getArrayMemory then we have: ${offset} + ${length} > ${this.data.length}`);
+			}
+		}
+
+		return {
+			bufferPosition: this.bufferPosition,
+			bufferByteOffset: this.bufferByteOffset + offset * this.data.BYTES_PER_ELEMENT
+		};
+	}
+
+	free() {
+		// NOTE: From worker thread you can't pass the array, you have to pass an explicit address to free
+		this.buffer.free(this.data.byteOffset);
+	}
+
+	getSharedMemory(): SharedAllocatedMemory {
+		return {
+			bufferPosition: this.bufferPosition,
+			bufferByteOffset: this.bufferByteOffset
+		};
+	}
+}
+
+interface AllocatedMemoryConfig {
+	data: Uint32Array
+	buffer: MemoryBuffer
+}
+
+interface SharedAllocatedMemory {
+	bufferPosition: number
+	bufferByteOffset: number
+}
+export type { SharedAllocatedMemory };

package/src/interfaces/pow2.ts

@@ -0,0 +1,3 @@
+type Pow2 = 0x1 | 0x2 | 0x4 | 0x8 | 0x10 | 0x20 | 0x40 | 0x80 | 0x100 | 0x200 | 0x400 | 0x800 | 0x1000 | 0x2000 | 0x4000 | 0x8000 | 0x10000 | 0x20000 | 0x40000 | 0x80000 | 0x100000 | 0x200000 | 0x400000 | 0x800000 | 0x1000000 | 0x2000000 | 0x4000000 | 0x8000000 | 0x10000000 | 0x20000000 | 0x40000000 | 0x80000000;
+
+export type { Pow2 };

package/src/interfaces/typed-array-constructor.ts

@@ -0,0 +1,6 @@
+interface TypedArrayConstructor<T> {
+	new(buffer: ArrayBufferLike, byteOffset: number, length: number): T
+	BYTES_PER_ELEMENT: number
+}
+
+export type { TypedArrayConstructor };

package/src/interfaces/typed-array.ts

@@ -0,0 +1 @@
+export type TypedArray = Float32Array | Float64Array | Int8Array | Int16Array | Int32Array | Uint8Array | Uint8ClampedArray | Uint16Array | Uint32Array;

package/src/lock/read-write-lock.ts

@@ -0,0 +1,41 @@
+const UNLOCKED = 0;
+const READ_LOCKED = 1;
+const WRITE_LOCKED = 2;
+
+export function readLock(data: Int32Array, index: number = 0) {
+	// Wait over and over again until we get that it was unlocked or read locked
+	while(Atomics.compareExchange(data, index, UNLOCKED, READ_LOCKED) === WRITE_LOCKED) {
+		Atomics.wait(data, index, WRITE_LOCKED);
+	}
+
+	Atomics.add(data, index + 1, 1);
+}
+export function writeLock(data: Int32Array, index: number = 0) {
+	// Write lock needs to be exclusive - wait until we were in UNLOCKED to proceed
+	let oldValue = Atomics.compareExchange(data, index, UNLOCKED, WRITE_LOCKED);
+	while(oldValue !== UNLOCKED) {
+		Atomics.wait(data, index, oldValue);
+		oldValue = Atomics.compareExchange(data, index, UNLOCKED, WRITE_LOCKED);
+	}
+}
+
+export function readUnlock(data: Int32Array, index: number = 0) {
+	let readCount = Atomics.sub(data, index + 1, 1) - 1;
+
+	if(readCount <= 0) {
+		if(Atomics.compareExchange(data, index, READ_LOCKED, UNLOCKED) !== READ_LOCKED) {
+			console.warn('We are unlocking when it was not read locked!');
+		}
+
+		Atomics.notify(data, index);
+	}
+}
+export function writeUnlock(data: Int32Array, index: number = 0) {
+	if(Atomics.compareExchange(data, index, WRITE_LOCKED, UNLOCKED) !== WRITE_LOCKED) {
+		console.warn('We are unlocking when it was not write locked!');
+	}
+
+	Atomics.notify(data, index);
+}
+
+export const READ_WRITE_LOCK_ALLOCATE_COUNT = 2;

package/src/lock/simple-lock.ts

@@ -0,0 +1,21 @@
+const UNLOCKED = 0;
+const LOCKED = 1;
+export function lock(data: Int32Array, index: number = 0) {
+	// Wait over and over again until we are one who set this from UNLOCKED to LOCKED
+	while(Atomics.compareExchange(data, index, UNLOCKED, LOCKED) !== UNLOCKED) {
+		if('WorkerGlobalScope' in self) {
+			Atomics.wait(data, index, LOCKED);
+		} else {
+			// TODO: Spin-locks suck....
+		}
+	}
+}
+export function unlock(data: Int32Array, index: number = 0) {
+	if(Atomics.compareExchange(data, index, LOCKED, UNLOCKED) !== LOCKED) {
+		console.warn('We are unlocking when it was not locked!');
+	}
+
+	Atomics.notify(data, index);
+}
+
+export const SIMPLE_LOCK_ALLOCATE_COUNT = 1;

package/src/main.ts

@@ -0,0 +1,35 @@
+import AllocatedMemory, { type SharedAllocatedMemory } from './allocated-memory';
+import MemoryBuffer from './memory-buffer';
+import MemoryHeap, { type MemoryHeapMemory } from './memory-heap';
+
+import SharedList, { type SharedListMemory } from './shared-list';
+import SharedMap from './shared-map';
+import SharedPointerList from './shared-pointer-list';
+import SharedString from './shared-string';
+import SharedVector from './shared-vector';
+
+import type { TypedArrayConstructor } from './interfaces/typed-array-constructor';
+
+export * from './utils/16-from-32-array';
+export * from './utils/16-from-64-array';
+export * from './utils/float32-atomics';
+export * from './utils/pointer';
+export * from './lock/simple-lock';
+export * from './lock/read-write-lock';
+
+export {
+	AllocatedMemory,
+	type SharedAllocatedMemory,
+	MemoryBuffer,
+	MemoryHeap,
+	type MemoryHeapMemory,
+
+	SharedList,
+	type SharedListMemory,
+	SharedMap,
+	SharedPointerList,
+	SharedString,
+	SharedVector,
+
+	type TypedArrayConstructor
+};