@powersync/common 1.50.0 → 1.51.0

package/dist/bundle.cjs

@@ -782,19 +782,69 @@ class SyncingService {
 }
 
 /**
- * An asynchronous mutex implementation.
+ * A simple fixed-capacity queue implementation.
+ *
+ * Unlike a naive queue implemented by `array.push()` and `array.shift()`, this avoids moving array elements around
+ * and is `O(1)` for {@link addLast} and {@link removeFirst}.
+ */
+class Queue {
+    table;
+    // Index of the first element in the table.
+    head;
+    // Amount of items currently in the queue.
+    _length;
+    constructor(initialItems) {
+        this.table = [...initialItems];
+        this.head = 0;
+        this._length = this.table.length;
+    }
+    get isEmpty() {
+        return this.length == 0;
+    }
+    get length() {
+        return this._length;
+    }
+    removeFirst() {
+        if (this.isEmpty) {
+            throw new Error('Queue is empty');
+        }
+        const result = this.table[this.head];
+        this._length--;
+        this.table[this.head] = undefined;
+        this.head = (this.head + 1) % this.table.length;
+        return result;
+    }
+    addLast(element) {
+        if (this.length == this.table.length) {
+            throw new Error('Queue is full');
+        }
+        this.table[(this.head + this._length) % this.table.length] = element;
+        this._length++;
+    }
+}
+
+/**
+ * An asynchronous semaphore implementation with associated items per lease.
  *
  * @internal This class is meant to be used in PowerSync SDKs only, and is not part of the public API.
  */
-class Mutex {
-    inCriticalSection = false;
+class Semaphore {
+    // Available items that are not currently assigned to a waiter.
+    available;
+    size;
     // Linked list of waiters. We don't expect the wait list to become particularly large, and this allows removing
     // aborted waiters from the middle of the list efficiently.
     firstWaiter;
     lastWaiter;
-    addWaiter(onAcquire) {
+    constructor(elements) {
+        this.available = new Queue(elements);
+        this.size = this.available.length;
+    }
+    addWaiter(requestedItems, onAcquire) {
         const node = {
             isActive: true,
+            acquiredItems: [],
+            remainingItems: requestedItems,
             onAcquire,
             prev: this.lastWaiter
         };
@@ -820,52 +870,92 @@ class Mutex {
         if (waiter == this.lastWaiter)
             this.lastWaiter = prev;
     }
-    acquire(abort) {
+    requestPermits(amount, abort) {
+        if (amount <= 0 || amount > this.size) {
+            throw new Error(`Invalid amount of items requested (${amount}), must be between 1 and ${this.size}`);
+        }
         return new Promise((resolve, reject) => {
             function rejectAborted() {
-                reject(abort?.reason ?? new Error('Mutex acquire aborted'));
+                reject(abort?.reason ?? new Error('Semaphore acquire aborted'));
             }
             if (abort?.aborted) {
                 return rejectAborted();
             }
-            let holdsMutex = false;
+            let waiter;
             const markCompleted = () => {
-                if (!holdsMutex)
-                    return;
-                holdsMutex = false;
-                const waiter = this.firstWaiter;
-                if (waiter) {
-                    this.deactivateWaiter(waiter);
-                    // Still in critical section, but owned by next waiter now.
-                    waiter.onAcquire();
+                const items = waiter.acquiredItems;
+                waiter.acquiredItems = []; // Avoid releasing items twice.
+                for (const element of items) {
+                    // Give to next waiter, if possible.
+                    const nextWaiter = this.firstWaiter;
+                    if (nextWaiter) {
+                        nextWaiter.acquiredItems.push(element);
+                        nextWaiter.remainingItems--;
+                        if (nextWaiter.remainingItems == 0) {
+                            nextWaiter.onAcquire();
+                        }
+                    }
+                    else {
+                        // No pending waiter, return lease into pool.
+                        this.available.addLast(element);
+                    }
                 }
-                else {
-                    this.inCriticalSection = false;
+            };
+            const onAbort = () => {
+                abort?.removeEventListener('abort', onAbort);
+                if (waiter.isActive) {
+                    this.deactivateWaiter(waiter);
+                    rejectAborted();
                 }
             };
-            if (!this.inCriticalSection) {
-                this.inCriticalSection = true;
-                holdsMutex = true;
-                return resolve(markCompleted);
+            const resolvePromise = () => {
+                this.deactivateWaiter(waiter);
+                abort?.removeEventListener('abort', onAbort);
+                const items = waiter.acquiredItems;
+                resolve({ items, release: markCompleted });
+            };
+            waiter = this.addWaiter(amount, resolvePromise);
+            // If there are items in the pool that haven't been assigned, we can pull them into this waiter. Note that this is
+            // only the case if we're the first waiter (otherwise, items would have been assigned to an earlier waiter).
+            while (!this.available.isEmpty && waiter.remainingItems > 0) {
+                waiter.acquiredItems.push(this.available.removeFirst());
+                waiter.remainingItems--;
             }
-            else {
-                let node;
-                const onAbort = () => {
-                    abort?.removeEventListener('abort', onAbort);
-                    if (node.isActive) {
-                        this.deactivateWaiter(node);
-                        rejectAborted();
-                    }
-                };
-                node = this.addWaiter(() => {
-                    abort?.removeEventListener('abort', onAbort);
-                    holdsMutex = true;
-                    resolve(markCompleted);
-                });
-                abort?.addEventListener('abort', onAbort);
+            if (waiter.remainingItems == 0) {
+                return resolvePromise();
             }
+            abort?.addEventListener('abort', onAbort);
         });
     }
+    /**
+     * Requests a single item from the pool.
+     *
+     * The returned `release` callback must be invoked to return the item into the pool.
+     */
+    async requestOne(abort) {
+        const { items, release } = await this.requestPermits(1, abort);
+        return { release, item: items[0] };
+    }
+    /**
+     * Requests access to all items from the pool.
+     *
+     * The returned `release` callback must be invoked to return items into the pool.
+     */
+    requestAll(abort) {
+        return this.requestPermits(this.size, abort);
+    }
+}
+/**
+ * An asynchronous mutex implementation.
+ *
+ * @internal This class is meant to be used in PowerSync SDKs only, and is not part of the public API.
+ */
+class Mutex {
+    inner = new Semaphore([null]);
+    async acquire(abort) {
+        const { release } = await this.inner.requestOne(abort);
+        return release;
+    }
     async runExclusive(fn, abort) {
         const returnMutex = await this.acquire(abort);
         try {
@@ -10662,7 +10752,7 @@ function requireDist () {
 
 var distExports = requireDist();
 
-var version = "1.50.0";
+var version = "1.51.0";
 var PACKAGE = {
 	version: version};
 
@@ -14654,6 +14744,7 @@ exports.OnChangeQueryProcessor = OnChangeQueryProcessor;
 exports.OpType = OpType;
 exports.OplogEntry = OplogEntry;
 exports.Schema = Schema;
+exports.Semaphore = Semaphore;
 exports.SqliteBucketStorage = SqliteBucketStorage;
 exports.SyncDataBatch = SyncDataBatch;
 exports.SyncDataBucket = SyncDataBucket;