superlock 1.4.1 → 1.4.3

package/README.md

@@ -9,9 +9,9 @@
 **superlock** aims to be:
 
 - **Simple**: Designed for usage with `async` and `await`
-- **Powerful**: Mutex & Semaphore patterns supported
+- **Powerful**: Mutex, semaphore, and fair queuing
 - **Secure**: Auto lock release toa void dead locks
-- **Lightweight**: No dependencies, just ~50 LOC
+- **Lightweight**: No dependencies
 - **Well-tested**: 100% code coverage
 
 ## Install
@@ -46,7 +46,43 @@ console.log(executions)
 
 ### as semaphore
 
-Just call `withLock(n)` being `n` the maximum of concurrency desired for the lock.
+Just call `withLock(n)` being `n` the maximum of concurrency desired for the lock:
+
+```js
+const { setTimeout } = require('timers/promises')
+const { withLock } = require('superlock')
+
+const lock = withLock(2)
+
+const executions = await Promise.all(
+  [...Array(10).keys()].map(index =>
+    lock(async () => {
+      await setTimeout(Math.random() * 100)
+      return index
+    })
+  )
+)
+
+console.log(executions)
+```
+
+### as fair queue
+
+`withLock` and `createLock` are one FIFO queue. A caller that enqueues a lot of work keeps taking the next slot.
+
+`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.
+
+```js
+const { withFairQueue } = require('superlock')
+
+const queue = withFairQueue()
+
+await queue(async () => {
+  /* your code execution */
+}, userId)
+```
+
+A second queued call for the same user waits until each other waiting user has had a turn. Pass an `AbortSignal` as the third argument when the caller can give up. Aborting while the call is queued skips the function.
 
 ### with cancellation
 
@@ -109,11 +145,122 @@ Type: `AbortSignal`
 
 When provided, aborting it drops the acquisition while it is still waiting in the queue: no slot is taken and the wrapped function never runs.
 
+### createLock([slots=1])
+
+The FIFO semaphore behind `withLock`. The promise resolves to a release function you call when the work is done:
+
+```js
+const { createLock } = require('superlock')
+
+const lock = createLock()
+const release = await lock()
+
+try {
+  /* your code execution */
+} finally {
+  release()
+}
+```
+
+An optional `AbortSignal` is the first argument. If it aborts while the call is queued, the promise resolves `null` and no slot is taken.
+
+#### slots
+
+Type: `number`<br>
+Default: `1`
+
+How many callers can hold the lock at once.
+
+### createFairQueue([slots=1])
+
+The fair queue behind `withFairQueue`, in the same way `createLock` is behind `withLock`. The promise resolves to a release function you call when the work is done. `createFairLock` is this function.
+
+```js
+const { createFairQueue } = require('superlock')
+
+const queue = createFairQueue()
+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.
+
+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.
+
+#### slots
+
+Type: `number`<br>
+Default: `1`
+
+How many callers can hold the queue at once.
+
+#### signal
+
+Type: `AbortSignal`
+
+Optional first argument. Aborting it while the call is queued resolves `null` and does not take a slot.
+
+#### key
+
+Type: any
+
+Optional second argument. Identifies the queue.
+
+### withFairQueue([slots=1])
+
+It returns a function that runs your code under [fair queuing](https://en.wikipedia.org/wiki/Fair_queuing). The queue is released when the function finishes, including when it throws.
+
+```js
+const { withFairQueue } = require('superlock')
+
+const queue = withFairQueue()
+
+await queue(() => {
+  /* your code execution */
+}, key)
+```
+
+An `AbortSignal` is an optional third argument:
+
+```js
+await queue(() => {
+  /* your code execution */
+}, key, signal)
+```
+
+If `signal` aborts while the call is still queued, the function is skipped and the call resolves `undefined`.
+
+#### slots
+
+Type: `number`<br>
+Default: `1`
+
+How many callers can hold the queue at once.
+
+#### key
+
+Type: any
+
+Optional second argument. Identifies the queue. A missing key shares one queue.
+
+#### signal
+
+Type: `AbortSignal`
+
+Optional third argument. Aborting it while the call is queued skips the function.
+
 ### .isLocked()
 
 Type: `boolean`
 
-It returns `false` if there is at least one free concurrency slots in the lock.
+It returns `false` if there is at least one free concurrency slots in the lock. `createLock`, `createFairQueue`, and `withFairQueue` expose it too.
+
+### .awaiting()
+
+Type: `number`
+
+How many callers are waiting for a slot. On a fair queue that is the total across every key.
 
 ## License
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "superlock",
   "description": "Minimal async mutex and semaphore for serializing critical sections in Node.js.",
   "homepage": "https://github.com/Kikobeats/superlock",
-  "version": "1.4.1",
+  "version": "1.4.3",
   "types": "src/index.d.ts",
   "main": "src/index.js",
   "exports": {

package/src/fair.js

@@ -5,38 +5,77 @@ 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()
   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 enqueue = (key, waiter) => {
     let entry = queues.get(key)
     if (!entry) {
-      entry = { key, queue: new LinkedList(), ringNode: ring.enqueue(key) }
+      // 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)
     }
     waiting++
     waiter.entry = entry
+    waiter.joinSeq = ++seq
     waiter.node = entry.queue.enqueue(waiter)
   }
 
-  const grant = () => {
-    if (ring.size() === 0) return
+  // 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 node =
+    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 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 entry = queues.get(node.data)
     const waiter = entry.queue.dequeue()
     waiting--
-    if (entry.queue.size() === 0) drop(entry)
-    last = entry.key
+    // 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()
   }
 
@@ -45,34 +84,46 @@ module.exports = (slots = 1) => {
     grant()
   }
 
-  const acquire = (resolve, key) => {
+  const acquire = resolve => {
     --slots
-    last = key
     resolve(release)
   }
 
   const lock = (signal, key) =>
     new Promise(resolve => {
-      if (signal != null && typeof signal.addEventListener !== 'function') {
+      if (
+        signal != null &&
+        (typeof signal.addEventListener !== 'function' ||
+          typeof signal.removeEventListener !== 'function' ||
+          typeof signal.aborted !== 'boolean')
+      ) {
         throw new TypeError('`signal` needs to be an AbortSignal.')
       }
       const id = key === undefined ? SHARED : key
       if (signal?.aborted) return resolve(null)
-      if (!lock.isLocked()) return acquire(resolve, id)
+      if (!lock.isLocked()) {
+        last = id
+        return acquire(resolve)
+      }
 
-      const waiter = { acquire: () => acquire(resolve, id) }
+      const waiter = { acquire: () => acquire(resolve) }
       enqueue(id, waiter)
 
       if (signal != null) {
         const onAbort = () => {
-          waiter.entry.queue.remove(waiter.node)
+          const entry = waiter.entry
+          entry.queue.remove(waiter.node)
           waiting--
-          if (waiter.entry.queue.size() === 0) drop(waiter.entry)
+          if (entry.queue.size() === 0) {
+            const current = queues.get(last) === entry
+            const cursor = drop(entry)
+            if (current) last = cursor
+          }
           resolve(null)
         }
         waiter.acquire = () => {
           signal.removeEventListener('abort', onAbort)
-          acquire(resolve, id)
+          acquire(resolve)
         }
         signal.addEventListener('abort', onAbort, { once: true })
       }

package/src/index.d.ts

@@ -9,14 +9,27 @@ interface LockInterface extends Lock {
 
 declare function createLock(slots?: number): LockInterface;
 
-declare type FairLock = (signal: AbortSignal | undefined | null, key?: unknown) => Promise<Release | null>;
+declare type FairQueue = (signal?: AbortSignal | null, key?: unknown) => Promise<Release | null>;
 
-interface FairLockInterface extends FairLock {
+interface FairQueueInterface extends FairQueue {
   isLocked: () => boolean;
   awaiting: () => number;
 }
 
-declare function createFairLock(slots?: number): FairLockInterface;
+declare function createFairQueue(slots?: number): FairQueueInterface;
+
+declare function createFairLock(slots?: number): FairQueueInterface;
+
+interface FairLockInterface extends FairQueueInterface {}
+
+declare type WithFairQueue = <T>(fn: () => Promise<T>, key?: unknown, signal?: AbortSignal | null) => Promise<T | undefined>;
+
+interface WithFairQueueInterface extends WithFairQueue {
+  isLocked: () => boolean;
+  awaiting: () => number;
+}
+
+declare function withFairQueue(slots?: number): WithFairQueueInterface;
 
 declare type WithLock = <T>(fn: () => Promise<T>, signal?: AbortSignal) => Promise<T | undefined>;
 
@@ -27,4 +40,4 @@ interface WithLockInterface extends WithLock {
 
 declare function withLock(opts?: number): WithLockInterface;
 
-export { withLock, createLock, createFairLock, WithLockInterface, FairLockInterface };
+export { withLock, createLock, withFairQueue, createFairQueue, createFairLock, WithLockInterface, WithFairQueueInterface, FairQueueInterface, FairLockInterface };

package/src/index.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const createFairLock = require('./fair')
+const createFairQueue = require('./fair')
 const createLock = require('./create')
 
 const withLock = opts => {
@@ -22,4 +22,29 @@ const withLock = opts => {
   return withLock
 }
 
-module.exports = { withLock, createLock, createFairLock }
+const withFairQueue = opts => {
+  const lock = createFairQueue(opts)
+
+  const withFairQueue = async (fn, key, signal) => {
+    const release = await lock(signal, key)
+    if (!release) return
+    try {
+      return await fn()
+    } finally {
+      release()
+    }
+  }
+
+  withFairQueue.isLocked = lock.isLocked
+  withFairQueue.awaiting = lock.awaiting
+
+  return withFairQueue
+}
+
+module.exports = {
+  withLock,
+  createLock,
+  withFairQueue,
+  createFairQueue,
+  createFairLock: createFairQueue
+}

package/src/linked-list.js

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