Version 0.1.0 (#1)

* Initialized package
mogoe1 · Sep 9, 2021 · 3a48fa8 · 3a48fa8
1 parent 97a00c8
commit 3a48fa8
Show file tree

Hide file tree

Showing 12 changed files with 7,892 additions and 1 deletion.
diff --git a/.eslintrc b/.eslintrc
@@ -0,0 +1,41 @@
+{
+    "root": true,
+    "parser": "@typescript-eslint/parser",
+    "ignorePatterns": ["example/**", "/*.*"],
+    "plugins": [
+        "@typescript-eslint"
+    ],
+    "extends": [
+        "standard",
+        "eslint:recommended",
+        "plugin:@typescript-eslint/eslint-recommended",
+        "plugin:@typescript-eslint/recommended"
+    ],
+    "rules": {
+        "prefer-template": "error",
+        "quotes": [
+            "error",
+            "double"
+        ],
+        "indent": [
+            "error",
+            4
+        ],
+        "semi": [
+            "error",
+            "always"
+        ],
+        "space-before-function-paren": [
+            "error",
+            "never"
+        ],
+        "no-trailing-spaces": [
+            "error",
+            {
+                "ignoreComments": true
+            }
+        ],
+        "@typescript-eslint/type-annotation-spacing": "error",
+        "no-useless-return": "warn"
+    }
+}
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,3 @@
+node_modules
+/docs
+/lib
diff --git a/.nvmrc b/.nvmrc
@@ -0,0 +1 @@
+14.17.3
diff --git a/README.md b/README.md
@@ -1 +1,56 @@
-# ReentrantLock
+# ReentrantLock
+A lock designed for multi-threaded browser environments.
+
+## Installing
+<strike> `npm install @mogoe1/reentrant-lock` </strike> (we are not on npm yet)
+
+	npm install --save git+https://github.com/mogoe1/reentrant-lock.git
+
+## Notes
+* The implementation relies on SharedArrayBuffers. Make sure your site meets the [security requirements](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer#security_requirements).
+* The implementation relies on Atomics.waitAsync which is implemented by [v8](https://v8.dev/features/atomics) but not documented at mdn yet. You might want to proivide a [polyfill](https://github.com/tc39/proposal-atomics-wait-async/blob/master/polyfill.js).
+
+## Quickstart
+The following example shows how a reentrant-lock can be used to make sure only one thrad at a time has access to a shared ressource.
+
+```js
+// file: main.js
+import { ReentrantLock } from "@mogoe1/reentrant-lock";
+
+const lock = ReentrantLock.create();
+const worker = new Worker("worker.js", { type: "module" });
+
+lock.lockAsync().then(_ => {
+    worker.postMessage(lock.buffer);
+
+    // exclusive access to resource
+    console.log("locked!");
+    lock.unlock();
+    console.log("unlocked");
+});
+```
+
+```js
+// file: worker.js
+import { ReentrantLock } from "@mogoe1/reentrant-lock";
+
+self.addEventListener("message", message => {
+    const buffer = message.data;
+    const lock = new ReentrantLock(new Int32Array(buffer));
+
+    let newlyLocked = lock.lock(); // this blocks the worker thread untill the main thread unlocks it's ReentrantLock instance!
+    console.log(newlyLocked); // true
+    newlyLocked =  lock.lock(); // lock can be called multiple times without blocking more than once
+    console.log(newlyLocked); // false
+
+    // exclusive access to resource here
+
+    let stillOwned = lock.unlock();
+    console.log(stillOwned); // true, because lock was called twice without unlock
+    stillOwned = lock.unlock();
+    console.log(stillOwned); // false, because unlock was called as often as lock
+});
+```
+
+## API
+The API is documented at https://mogoe1.github.io/reentrant-lock/classes/ReentrantLock.html.
diff --git a/example/index.html b/example/index.html
@@ -0,0 +1,3 @@
+<body>
+    <script type="module" src="example/main.js"></script>
+</body>
diff --git a/example/main.js b/example/main.js
@@ -0,0 +1,14 @@
+// file: main.js
+import { ReentrantLock } from "../lib/ReentrantLock.js";
+
+const lock = ReentrantLock.create();
+const worker = new Worker("./example/worker.js", { type: "module" });
+
+lock.lockAsync().then(_ => {
+    worker.postMessage(lock.buffer);
+
+    // exclusive access to resource
+    console.log("locked!");
+    lock.unlock();
+    console.log("unlocked");
+});
diff --git a/example/worker.js b/example/worker.js
@@ -0,0 +1,18 @@
+// file: worker.js
+import { ReentrantLock } from "../lib/ReentrantLock.js";
+
+self.addEventListener("message", message => {
+    const buffer = message.data;
+    const lock = new ReentrantLock(new Int32Array(buffer));
+
+    lock.lock(); // this blocks the worker thread untill the main thread unlocks it's ReentrantLock instance!
+    const newlyLocked = lock.lock(); // lock can be called multiple times without blocking more than once
+    console.log(newlyLocked); // false, because this instance was locked prior to the previous line
+
+    // exclusive access to resource
+
+    let stillOwned = lock.unlock();
+    console.log(stillOwned); // true, because lock was called twice without unlock
+    stillOwned = lock.unlock();
+    console.log(stillOwned); // false, because unlock was called as often as lock
+});