superlock 1.4.3 → 1.4.5

package/README.md

@@ -1,8 +1,19 @@
-[![Last version](https://img.shields.io/github/v/tag/Kikobeats/superlock?style=flat-square)](https://github.com/Kikobeats/superlock/releases)
-[![Coverage Status](https://img.shields.io/coverallsCoverage/github/Kikobeats/superlock?style=flat-square)](https://coveralls.io/github/Kikobeats/superlock)
-[![NPM Status](https://img.shields.io/npm/dm/superlock?style=flat-square)](https://www.npmjs.com/package/superlock)
-
-> A mutex/semaphore implementation made easy to use.
+<p align="center">
+  <a href="https://superlock.js.org/">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="docs/anatomy/wordmark.svg">
+      <img alt="superlock" src="docs/anatomy/wordmark-light.svg" width="640">
+    </picture>
+  </a>
+</p>
+
+<p align="center" class="subtitle">The minimal Node.js concurrency toolkit.</p>
+
+<p align="center" class="badges">
+  <a href="https://github.com/Kikobeats/superlock/releases"><img alt="Last version" src="https://img.shields.io/github/v/tag/Kikobeats/superlock?style=flat-square"></a>
+  <a href="https://coveralls.io/github/Kikobeats/superlock"><img alt="Coverage Status" src="https://img.shields.io/coverallsCoverage/github/Kikobeats/superlock?style=flat-square"></a>
+  <a href="https://www.npmjs.com/package/superlock"><img alt="NPM Status" src="https://img.shields.io/npm/dm/superlock?style=flat-square"></a>
+</p>
 
 ## Why
 
@@ -10,7 +21,7 @@
 
 - **Simple**: Designed for usage with `async` and `await`
 - **Powerful**: Mutex, semaphore, and fair queuing
-- **Secure**: Auto lock release toa void dead locks
+- **Secure**: Auto lock release to avoid deadlocks
 - **Lightweight**: No dependencies
 - **Well-tested**: 100% code coverage
 
@@ -24,7 +35,14 @@ $ npm install superlock --save
 
 ### as mutex
 
-The lock is a mutex by default:
+The lock is a mutex by default: one caller holds it, the rest wait in arrival order.
+
+<a href="https://superlock.js.org/#/?id=as-mutex">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/anatomy/mutex.svg">
+    <img alt="A coin-feed escapement: tokens queue in a column, a pusher one token thick carries exactly one at a time to a press, and the next drops in only after release()." src="docs/anatomy/mutex-light.svg">
+  </picture>
+</a>
 
 ```js
 const { setTimeout } = require('timers/promises')
@@ -46,7 +64,14 @@ console.log(executions)
 
 ### as semaphore
 
-Just call `withLock(n)` being `n` the maximum of concurrency desired for the lock:
+Call `withLock(n)` with `n` as the maximum concurrency for the lock. Up to `n` callers hold it at once; a freed slot goes to the oldest waiter:
+
+<a href="https://superlock.js.org/#/?id=as-semaphore">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/anatomy/semaphore.svg">
+    <img alt="Twin lanes fed by one column: a diverter drops the oldest waiting token into whichever of two lanes is free, and each lane releases on its own." src="docs/anatomy/semaphore-light.svg">
+  </picture>
+</a>
 
 ```js
 const { setTimeout } = require('timers/promises')
@@ -72,6 +97,13 @@ console.log(executions)
 
 `withFairQueue` is [fair queuing](https://en.wikipedia.org/wiki/Fair_queuing): one queue per key, and a free slot rotates across those keys. The same key is still served in arrival order. Callers that omit the key share one queue.
 
+<a href="https://superlock.js.org/#/?id=as-fair-queue">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/anatomy/fair-queue.svg">
+    <img alt="An indexing table: one column per key around a rotating dial that feeds one press, visiting the keys in turn so a deep column cannot starve the others." src="docs/anatomy/fair-queue-light.svg">
+  </picture>
+</a>
+
 ```js
 const { withFairQueue } = require('superlock')
 
@@ -184,7 +216,7 @@ const release = await queue(undefined, key)
 release()
 ```
 
-One key is served in arrival order. Across keys, a free slot goes to the next key that is waiting, then wraps around. A key with nobody left waiting leaves the rotation.
+One key is served in arrival order. Across keys, a free slot goes to the waiting key that has gone longest without a turn; keys that never had one go first, in arrival order. A key that still holds a slot waits behind keys that hold none. Calls that arrive while a round is being served wait until every call that was already waiting has had its turn.
 
 A missing key shares one queue. Any other value, including `null`, is its own queue. `null` and a missing signal do not cancel. A value that is not an `AbortSignal` throws `TypeError`. Aborting after the slot was granted does nothing.
 
@@ -264,7 +296,7 @@ How many callers are waiting for a slot. On a fair queue that is the total acros
 
 ## License
 
-**superlock** © [Kiko Beats](https://kikobeats.com), released under the [MIT](https://github.com/Kikobeats/lock/blob/master/LICENSE.md) License.<br>
-Authored and maintained by [Kiko Beats](https://kikobeats.com) with help from [contributors](https://github.com/Kikobeats/lock/contributors).
+**superlock** © [Kiko Beats](https://kikobeats.com), released under the [MIT](https://github.com/Kikobeats/superlock/blob/master/LICENSE.md) License.<br>
+Authored and maintained by [Kiko Beats](https://kikobeats.com) with help from [contributors](https://github.com/Kikobeats/superlock/contributors).
 
 > [kikobeats.com](https://kikobeats.com) · GitHub [Kiko Beats](https://github.com/Kikobeats) · X [@Kikobeats](https://x.com/Kikobeats)

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "superlock",
-  "description": "Minimal async mutex and semaphore for serializing critical sections in Node.js.",
-  "homepage": "https://github.com/Kikobeats/superlock",
-  "version": "1.4.3",
+  "description": "The minimal Node.js concurrency toolkit: mutex, semaphore and fair queue for async/await, with no dependencies.",
+  "homepage": "https://superlock.js.org/",
+  "version": "1.4.5",
   "types": "src/index.d.ts",
   "main": "src/index.js",
   "exports": {
@@ -39,12 +39,22 @@
     "@commitlint/cli": "latest",
     "@commitlint/config-conventional": "latest",
     "ava": "7",
+    "browser-sync": "latest",
     "c8": "latest",
     "ci-publish": "latest",
+    "concurrently": "latest",
+    "cssnano": "latest",
+    "cssnano-preset-advanced": "latest",
     "finepack": "latest",
     "git-authors-cli": "latest",
     "github-generate-release": "latest",
+    "gulp": "5",
+    "gulp-concat": "latest",
+    "gulp-postcss": "latest",
+    "gulp-uglify": "latest",
     "nano-staged": "latest",
+    "postcss": "latest",
+    "postcss-focus": "latest",
     "simple-git-hooks": "latest",
     "standard": "latest",
     "standard-version": "latest"
@@ -56,10 +66,14 @@
     "src"
   ],
   "scripts": {
+    "build": "gulp build",
     "clean": "rm -rf node_modules",
     "contributors": "(npx git-authors-cli && npx finepack && git add package.json && git commit -m 'build: contributors' --no-verify) || true",
     "coverage": "c8 report --reporter=text-lcov > coverage/lcov.info",
+    "dev": "concurrently \"gulp\" \"npm run dev:server\"",
+    "dev:server": "browser-sync start --server --files \"index.html, README.md, static/**/*.(css|js)\"",
     "lint": "standard",
+    "og": "node docs/og/build.mjs",
     "postrelease": "npm run release:tags && npm run release:github && (ci-publish || npm publish --access=public)",
     "prerelease": "npm run contributors",
     "pretest": "npm run lint",
@@ -75,6 +89,11 @@
       "!test/helpers.js"
     ]
   },
+  "c8": {
+    "include": [
+      "src/**/*.js"
+    ]
+  },
   "commitlint": {
     "extends": [
       "@commitlint/config-conventional"

package/src/fair.js

@@ -3,90 +3,89 @@
 const LinkedList = require('./linked-list')
 
 const SHARED = Symbol('shared')
-const NONE = Symbol('none')
-
-// Map keys use SameValueZero, so NaN is one key and === cannot find it.
-const sameKey = (a, b) => a === b || (Number.isNaN(a) && Number.isNaN(b))
 
 module.exports = (slots = 1) => {
-  const queues = new Map()
-  const ring = new LinkedList()
+  const keys = new Map()
+  const turns = new LinkedList()
+  let newestWithoutTurn
   let waiting = 0
-  let last = NONE
   let seq = 0
   let barrier = 0
 
-  const drop = entry => {
-    const predecessor = entry.ringNode.prev
-    ring.remove(entry.ringNode)
-    queues.delete(entry.key)
-    return predecessor ? predecessor.data : NONE
+  const entryOf = key => {
+    let entry = keys.get(key)
+    if (!entry) {
+      entry = { key, queue: new LinkedList(), holders: 0 }
+      entry.turnNode = turns.insertAfter(newestWithoutTurn, entry)
+      newestWithoutTurn = entry.turnNode
+      keys.set(key, entry)
+    }
+    return entry
   }
 
-  const enqueue = (key, waiter) => {
-    let entry = queues.get(key)
-    if (!entry) {
-      // The holder is the cursor and is not on the ring yet. Put that key
-      // at the head so the next grant starts on the keys already waiting
-      // and reaches the holder last. At the tail, the cursor would step
-      // into keys that arrive later and skip the ones already in front.
-      const ringNode = sameKey(key, last)
-        ? ring.prepend(key)
-        : ring.enqueue(key)
-      entry = { key, queue: new LinkedList(), ringNode }
-      queues.set(key, entry)
+  const leaveTurns = entry => {
+    if (entry.turnNode === newestWithoutTurn) {
+      newestWithoutTurn = entry.turnNode.prev
     }
-    waiting++
-    waiter.entry = entry
-    waiter.joinSeq = ++seq
-    waiter.node = entry.queue.enqueue(waiter)
+    turns.remove(entry.turnNode)
   }
 
-  // The key's oldest waiter decides. A later waiter on a key that joined
-  // this round has a newer sequence and must not inherit the round.
-  const eligible = entry => entry.queue.head.data.joinSeq <= barrier
-
-  // Start just after the cursor and wrap once. Stop is required: the
-  // ring is not circular, so the walk jumps from the tail back to the head.
-  const selectNode = () => {
-    const current = queues.get(last)
-    const start =
-      current && current.ringNode.next ? current.ringNode.next : ring.head
-    let node = start
-    do {
-      if (eligible(queues.get(node.data))) return node
-      node = node.next || ring.head
-    } while (node !== start)
+  const markTurn = entry => {
+    if (entry.turnNode === newestWithoutTurn) {
+      newestWithoutTurn = entry.turnNode.prev
+    }
+    turns.moveToTail(entry.turnNode)
   }
 
-  const grant = () => {
-    if (ring.size() === 0) return
-    // Waiters past the barrier stay out until every earlier waiter has
-    // been served. When none of those remain, move the barrier up.
-    let node = selectNode()
-    if (!node) {
-      barrier = seq
-      node = selectNode()
+  const forgetIfIdle = entry => {
+    if (entry.holders > 0 || entry.queue.size() > 0) return
+    leaveTurns(entry)
+    keys.delete(entry.key)
+  }
+
+  const inRound = entry => entry.queue.head.data.joinSeq <= barrier
+
+  // A smaller holder count does not outrank an older turn.
+  const longestWithoutTurn = () => {
+    let holding
+    for (let node = turns.head; node; node = node.next) {
+      const entry = node.data
+      if (entry.queue.size() === 0 || !inRound(entry)) continue
+      if (entry.holders === 0) return entry
+      if (!holding) holding = entry
     }
-    const entry = queues.get(node.data)
-    const waiter = entry.queue.dequeue()
-    waiting--
-    // A key that just left the ring must not stay as `last`. The next grant
-    // would miss it in the map and restart at the head, skipping whoever
-    // was behind it.
-    if (entry.queue.size() === 0) last = drop(entry)
-    else last = entry.key
-    waiter.acquire()
+    return holding
   }
 
-  const release = () => {
-    ++slots
-    grant()
+  const nextEntry = () => {
+    const entry = longestWithoutTurn()
+    if (entry) return entry
+    barrier = seq
+    return longestWithoutTurn()
   }
 
-  const acquire = resolve => {
+  const take = entry => {
     --slots
-    resolve(release)
+    entry.holders++
+    markTurn(entry)
+    let released = false
+    return () => {
+      if (released) return
+      released = true
+      entry.holders--
+      markTurn(entry)
+      forgetIfIdle(entry)
+      ++slots
+      grant()
+    }
+  }
+
+  const grant = () => {
+    if (waiting === 0) return
+    const entry = nextEntry()
+    const waiter = entry.queue.dequeue()
+    waiting--
+    waiter.acquire(take(entry))
   }
 
   const lock = (signal, key) =>
@@ -99,31 +98,24 @@ module.exports = (slots = 1) => {
       ) {
         throw new TypeError('`signal` needs to be an AbortSignal.')
       }
-      const id = key === undefined ? SHARED : key
       if (signal?.aborted) return resolve(null)
-      if (!lock.isLocked()) {
-        last = id
-        return acquire(resolve)
-      }
+      const entry = entryOf(key === undefined ? SHARED : key)
+      if (!lock.isLocked()) return resolve(take(entry))
 
-      const waiter = { acquire: () => acquire(resolve) }
-      enqueue(id, waiter)
+      const waiter = { joinSeq: ++seq, acquire: resolve }
+      waiter.node = entry.queue.enqueue(waiter)
+      waiting++
 
       if (signal != null) {
         const onAbort = () => {
-          const entry = waiter.entry
           entry.queue.remove(waiter.node)
           waiting--
-          if (entry.queue.size() === 0) {
-            const current = queues.get(last) === entry
-            const cursor = drop(entry)
-            if (current) last = cursor
-          }
+          forgetIfIdle(entry)
           resolve(null)
         }
-        waiter.acquire = () => {
+        waiter.acquire = release => {
           signal.removeEventListener('abort', onAbort)
-          acquire(resolve)
+          resolve(release)
         }
         signal.addEventListener('abort', onAbort, { once: true })
       }

package/src/linked-list.js

@@ -31,6 +31,29 @@ module.exports = class LinkedList {
     return node
   }
 
+  insertAfter (previous, data) {
+    if (!previous) return this.prepend(data)
+    const node = new Node(data)
+    node.prev = previous
+    node.next = previous.next
+    if (previous.next) previous.next.prev = node
+    else this.tail = node
+    previous.next = node
+    this.length++
+    return node
+  }
+
+  moveToTail (node) {
+    if (node === this.tail) return
+    if (node.prev) node.prev.next = node.next
+    else this.head = node.next
+    node.next.prev = node.prev
+    node.prev = this.tail
+    node.next = undefined
+    this.tail.next = node
+    this.tail = node
+  }
+
   dequeue () {
     if (!this.head) return
     const { data } = this.head