@powersync/common 1.50.0 → 1.51.0

package/dist/index.d.cts

@@ -3037,16 +3037,45 @@ declare class TriggerManagerImpl implements TriggerManager {
 
 type UnlockFn = () => void;
 /**
- * An asynchronous mutex implementation.
+ * 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.
  */
-declare class Mutex {
-    private inCriticalSection;
+declare class Semaphore<T> {
+    private readonly available;
+    readonly size: number;
     private firstWaiter?;
     private lastWaiter?;
+    constructor(elements: Iterable<T>);
     private addWaiter;
     private deactivateWaiter;
+    private requestPermits;
+    /**
+     * Requests a single item from the pool.
+     *
+     * The returned `release` callback must be invoked to return the item into the pool.
+     */
+    requestOne(abort?: AbortSignal): Promise<{
+        item: T;
+        release: UnlockFn;
+    }>;
+    /**
+     * Requests access to all items from the pool.
+     *
+     * The returned `release` callback must be invoked to return items into the pool.
+     */
+    requestAll(abort?: AbortSignal): Promise<{
+        items: T[];
+        release: UnlockFn;
+    }>;
+}
+/**
+ * An asynchronous mutex implementation.
+ *
+ * @internal This class is meant to be used in PowerSync SDKs only, and is not part of the public API.
+ */
+declare class Mutex {
+    private inner;
     acquire(abort?: AbortSignal): Promise<UnlockFn>;
     runExclusive<T>(fn: () => PromiseLike<T> | T, abort?: AbortSignal): Promise<T>;
 }
@@ -4395,5 +4424,5 @@ interface ParsedQuery {
 }
 declare const parseQuery: <T>(query: string | CompilableQuery<T>, parameters: any[]) => ParsedQuery;
 
-export { ATTACHMENT_TABLE, AbortOperation, AbstractPowerSyncDatabase, AbstractPowerSyncDatabaseOpenFactory, AbstractQueryProcessor, AbstractRemote, AbstractStreamingSyncImplementation, ArrayComparator, AttachmentContext, AttachmentQueue, AttachmentService, AttachmentState, AttachmentTable, BaseObserver, Column, ColumnType, ConnectionClosedError, ConnectionManager, ControlledExecutor, CrudBatch, CrudEntry, CrudTransaction, DBAdapterDefaultMixin, DBGetUtilsDefaultMixin, DEFAULT_CRUD_BATCH_LIMIT, DEFAULT_CRUD_UPLOAD_THROTTLE_MS, DEFAULT_INDEX_COLUMN_OPTIONS, DEFAULT_INDEX_OPTIONS, DEFAULT_LOCK_TIMEOUT_MS, DEFAULT_POWERSYNC_CLOSE_OPTIONS, DEFAULT_POWERSYNC_DB_OPTIONS, DEFAULT_PRESSURE_LIMITS, DEFAULT_REMOTE_LOGGER, DEFAULT_REMOTE_OPTIONS, DEFAULT_RETRY_DELAY_MS, DEFAULT_ROW_COMPARATOR, DEFAULT_STREAMING_SYNC_OPTIONS, DEFAULT_STREAM_CONNECTION_OPTIONS, DEFAULT_SYNC_CLIENT_IMPLEMENTATION, DEFAULT_TABLE_OPTIONS, DEFAULT_WATCH_QUERY_OPTIONS, DEFAULT_WATCH_THROTTLE_MS, DataStream, DiffTriggerOperation, DifferentialQueryProcessor, EMPTY_DIFFERENTIAL, EncodingType, FalsyComparator, FetchImplementationProvider, FetchStrategy, GetAllQuery, Index, IndexedColumn, InvalidSQLCharacters, LockType, LogLevel, MAX_AMOUNT_OF_COLUMNS, MAX_OP_ID, MEMORY_TRIGGER_CLAIM_MANAGER, Mutex, OnChangeQueryProcessor, OpType, OpTypeEnum, OplogEntry, PSInternalTable, PowerSyncControlCommand, RowUpdateType, Schema, SqliteBucketStorage, SyncClientImplementation, SyncDataBatch, SyncDataBucket, SyncProgress, SyncStatus, SyncStreamConnectionMethod, SyncingService, Table, TableV2, TriggerManagerImpl, UpdateType, UploadQueueStats, WatchedQueryListenerEvent, attachmentFromSql, column, compilableQueryWatch, createBaseLogger, createLogger, extractTableUpdates, isBatchedUpdateNotification, isContinueCheckpointRequest, isDBAdapter, isPowerSyncDatabaseOptionsWithSettings, isSQLOpenFactory, isSQLOpenOptions, isStreamingKeepalive, isStreamingSyncCheckpoint, isStreamingSyncCheckpointComplete, isStreamingSyncCheckpointDiff, isStreamingSyncCheckpointPartiallyComplete, isStreamingSyncData, isSyncNewCheckpointRequest, parseQuery, runOnSchemaChange, sanitizeSQL, sanitizeUUID, timeoutSignal };
+export { ATTACHMENT_TABLE, AbortOperation, AbstractPowerSyncDatabase, AbstractPowerSyncDatabaseOpenFactory, AbstractQueryProcessor, AbstractRemote, AbstractStreamingSyncImplementation, ArrayComparator, AttachmentContext, AttachmentQueue, AttachmentService, AttachmentState, AttachmentTable, BaseObserver, Column, ColumnType, ConnectionClosedError, ConnectionManager, ControlledExecutor, CrudBatch, CrudEntry, CrudTransaction, DBAdapterDefaultMixin, DBGetUtilsDefaultMixin, DEFAULT_CRUD_BATCH_LIMIT, DEFAULT_CRUD_UPLOAD_THROTTLE_MS, DEFAULT_INDEX_COLUMN_OPTIONS, DEFAULT_INDEX_OPTIONS, DEFAULT_LOCK_TIMEOUT_MS, DEFAULT_POWERSYNC_CLOSE_OPTIONS, DEFAULT_POWERSYNC_DB_OPTIONS, DEFAULT_PRESSURE_LIMITS, DEFAULT_REMOTE_LOGGER, DEFAULT_REMOTE_OPTIONS, DEFAULT_RETRY_DELAY_MS, DEFAULT_ROW_COMPARATOR, DEFAULT_STREAMING_SYNC_OPTIONS, DEFAULT_STREAM_CONNECTION_OPTIONS, DEFAULT_SYNC_CLIENT_IMPLEMENTATION, DEFAULT_TABLE_OPTIONS, DEFAULT_WATCH_QUERY_OPTIONS, DEFAULT_WATCH_THROTTLE_MS, DataStream, DiffTriggerOperation, DifferentialQueryProcessor, EMPTY_DIFFERENTIAL, EncodingType, FalsyComparator, FetchImplementationProvider, FetchStrategy, GetAllQuery, Index, IndexedColumn, InvalidSQLCharacters, LockType, LogLevel, MAX_AMOUNT_OF_COLUMNS, MAX_OP_ID, MEMORY_TRIGGER_CLAIM_MANAGER, Mutex, OnChangeQueryProcessor, OpType, OpTypeEnum, OplogEntry, PSInternalTable, PowerSyncControlCommand, RowUpdateType, Schema, Semaphore, SqliteBucketStorage, SyncClientImplementation, SyncDataBatch, SyncDataBucket, SyncProgress, SyncStatus, SyncStreamConnectionMethod, SyncingService, Table, TableV2, TriggerManagerImpl, UpdateType, UploadQueueStats, WatchedQueryListenerEvent, attachmentFromSql, column, compilableQueryWatch, createBaseLogger, createLogger, extractTableUpdates, isBatchedUpdateNotification, isContinueCheckpointRequest, isDBAdapter, isPowerSyncDatabaseOptionsWithSettings, isSQLOpenFactory, isSQLOpenOptions, isStreamingKeepalive, isStreamingSyncCheckpoint, isStreamingSyncCheckpointComplete, isStreamingSyncCheckpointDiff, isStreamingSyncCheckpointPartiallyComplete, isStreamingSyncData, isSyncNewCheckpointRequest, parseQuery, runOnSchemaChange, sanitizeSQL, sanitizeUUID, timeoutSignal };
 export type { AbstractQueryProcessorOptions, AbstractRemoteOptions, AbstractStreamingSyncImplementationOptions, AdditionalConnectionOptions, ArrayComparatorOptions, ArrayQueryDefinition, AttachmentData, AttachmentErrorHandler, AttachmentRecord, AttachmentTableOptions, BSONImplementation, BaseColumnType, BaseConnectionOptions, BaseListener, BaseObserverInterface, BasePowerSyncDatabaseOptions, BaseTriggerDiffRecord, BatchedUpdateNotification, BucketChecksum, BucketDescription, BucketOperationProgress, BucketRequest, BucketState, BucketStorageAdapter, BucketStorageListener, Checkpoint, ChecksumCache, ColumnOptions, ColumnsType, CompilableQuery, CompilableQueryWatchHandler, CompiledQuery, ConnectionManagerListener, ConnectionManagerOptions, ConnectionManagerSyncImplementationResult, ConnectionPool, ContinueCheckpointRequest, ControlledExecutorOptions, CreateDiffTriggerOptions, CreateLoggerOptions, CreateSyncImplementationOptions, CrudRequest, CrudResponse, CrudUploadNotification, DBAdapter, DBAdapterListener, DBGetUtils, DBLockOptions, DataStreamCallback, DataStreamListener, DataStreamOptions, DifferentialQueryProcessorOptions, DifferentialWatchedQuery, DifferentialWatchedQueryComparator, DifferentialWatchedQueryListener, DifferentialWatchedQueryOptions, DifferentialWatchedQuerySettings, DisconnectAndClearOptions, Disposable, ExtractColumnValueType, ExtractedTriggerDiffRecord, FetchImplementation, GetAllQueryOptions, IndexColumnOptions, IndexOptions, IndexShorthand, InternalConnectionOptions, InternalSubscriptionAdapter, LinkQueryOptions, LocalStorageAdapter, LockContext, LockOptions, MutableWatchedQueryState, OnChangeQueryProcessorOptions, OpId, OpTypeJSON, OplogEntryJSON, ParsedQuery, PendingStatement, PendingStatementParameter, PowerSyncBackendConnector, PowerSyncCloseOptions, PowerSyncConnectionOptions, PowerSyncCredentials, PowerSyncDBListener, PowerSyncDatabaseOptions, PowerSyncDatabaseOptionsWithDBAdapter, PowerSyncDatabaseOptionsWithOpenFactory, PowerSyncDatabaseOptionsWithSettings, PowerSyncOpenFactoryOptions, ProgressWithOperations, Query, QueryParam, QueryResult, RawTableType, RemoteConnector, RemoteStorageAdapter, RequiredAdditionalConnectionOptions, RequiredPowerSyncConnectionOptions, RowType, SQLOnChangeOptions, SQLOpenFactory, SQLOpenOptions, SQLWatchOptions, SavedProgress, SchemaTableType, SocketSyncStreamOptions, SqlExecutor, StandardWatchedQuery, StandardWatchedQueryOptions, StreamingSyncCheckpoint, StreamingSyncCheckpointComplete, StreamingSyncCheckpointDiff, StreamingSyncCheckpointPartiallyComplete, StreamingSyncDataJSON, StreamingSyncImplementation, StreamingSyncImplementationListener, StreamingSyncKeepalive, StreamingSyncLine, StreamingSyncLineOrCrudUploadComplete, StreamingSyncRequest, StreamingSyncRequestParameterType, SubscribedStream, SyncDataBucketJSON, SyncDataFlowStatus, SyncLocalDatabaseResult, SyncNewCheckpointRequest, SyncPriorityStatus, SyncRequest, SyncResponse, SyncStatusOptions, SyncStream, SyncStreamDescription, SyncStreamOptions, SyncStreamStatus, SyncStreamSubscribeOptions, SyncStreamSubscription, SyncSubscriptionDescription, TableOptions, TableOrRawTableOptions, TableUpdateOperation, TableV2Options, TrackDiffOptions, TrackPreviousOptions, Transaction, TriggerClaimManager, TriggerCreationHooks, TriggerDiffDeleteRecord, TriggerDiffHandlerContext, TriggerDiffInsertRecord, TriggerDiffRecord, TriggerDiffUpdateRecord, TriggerManager, TriggerManagerConfig, TriggerRemoveCallback, TriggerRemoveCallbackOptions, UnlockFn, UpdateNotification, WatchCompatibleQuery, WatchExecuteOptions, WatchHandler, WatchOnChangeEvent, WatchOnChangeHandler, WatchedAttachmentItem, WatchedQuery, WatchedQueryComparator, WatchedQueryDifferential, WatchedQueryListener, WatchedQueryOptions, WatchedQueryRowDifferential, WatchedQuerySettings, WatchedQueryState, WithDiffOptions };

package/lib/utils/mutex.d.ts

@@ -1,15 +1,44 @@
 export type UnlockFn = () => void;
 /**
- * An asynchronous mutex implementation.
+ * 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.
  */
-export declare class Mutex {
-    private inCriticalSection;
+export declare class Semaphore<T> {
+    private readonly available;
+    readonly size: number;
     private firstWaiter?;
     private lastWaiter?;
+    constructor(elements: Iterable<T>);
     private addWaiter;
     private deactivateWaiter;
+    private requestPermits;
+    /**
+     * Requests a single item from the pool.
+     *
+     * The returned `release` callback must be invoked to return the item into the pool.
+     */
+    requestOne(abort?: AbortSignal): Promise<{
+        item: T;
+        release: UnlockFn;
+    }>;
+    /**
+     * Requests access to all items from the pool.
+     *
+     * The returned `release` callback must be invoked to return items into the pool.
+     */
+    requestAll(abort?: AbortSignal): Promise<{
+        items: T[];
+        release: UnlockFn;
+    }>;
+}
+/**
+ * An asynchronous mutex implementation.
+ *
+ * @internal This class is meant to be used in PowerSync SDKs only, and is not part of the public API.
+ */
+export declare class Mutex {
+    private inner;
     acquire(abort?: AbortSignal): Promise<UnlockFn>;
     runExclusive<T>(fn: () => PromiseLike<T> | T, abort?: AbortSignal): Promise<T>;
 }

package/lib/utils/mutex.js

@@ -1,17 +1,26 @@
+import { Queue } from './queue.js';
 /**
- * An asynchronous mutex implementation.
+ * 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.
  */
-export class Mutex {
-    inCriticalSection = false;
+export 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
         };
@@ -37,52 +46,92 @@ export 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.
+ */
+export 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 {

package/lib/utils/mutex.js.map

@@ -1 +1 @@
-{"version":3,"file":"mutex.js","sourceRoot":"","sources":["../../src/utils/mutex.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mutex.js","sourceRoot":"","sources":["../../src/utils/mutex.ts"],"names":[],"mappings":"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"}

package/lib/utils/queue.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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}.
+ */
+export declare class Queue<T> {
+    private table;
+    private head;
+    private _length;
+    constructor(initialItems: Iterable<T>);
+    get isEmpty(): boolean;
+    get length(): number;
+    removeFirst(): T;
+    addLast(element: T): void;
+}

package/lib/utils/queue.js

@@ -0,0 +1,42 @@
+/**
+ * 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}.
+ */
+export 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++;
+    }
+}
+//# sourceMappingURL=queue.js.map

package/lib/utils/queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.js","sourceRoot":"","sources":["../../src/utils/queue.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,OAAO,KAAK;IACR,KAAK,CAAoB;IACjC,2CAA2C;IACnC,IAAI,CAAS;IACrB,0CAA0C;IAClC,OAAO,CAAS;IAExB,YAAY,YAAyB;QACnC,IAAI,CAAC,KAAK,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;QACd,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IACnC,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,WAAW;QACT,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,gBAAgB,CAAC,CAAC;QACpC,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAM,CAAC;QAC1C,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC;QAClC,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;QAChD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,OAAO,CAAC,OAAU;QAChB,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC;QACnC,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC;QACrE,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powersync/common",
-  "version": "1.50.0",
+  "version": "1.51.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"

package/src/utils/mutex.ts

@@ -1,21 +1,32 @@
+import { Queue } from './queue.js';
+
 export type UnlockFn = () => void;
 
 /**
- * An asynchronous mutex implementation.
+ * 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.
  */
-export class Mutex {
-  private inCriticalSection = false;
+export class Semaphore<T> {
+  // Available items that are not currently assigned to a waiter.
+  private readonly available: Queue<T>;
 
+  readonly size: number;
   // 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.
-  private firstWaiter?: MutexWaitNode;
-  private lastWaiter?: MutexWaitNode;
+  private firstWaiter?: SemaphoreWaitNode<T>;
+  private lastWaiter?: SemaphoreWaitNode<T>;
 
-  private addWaiter(onAcquire: () => void): MutexWaitNode {
-    const node: MutexWaitNode = {
+  constructor(elements: Iterable<T>) {
+    this.available = new Queue(elements);
+    this.size = this.available.length;
+  }
+
+  private addWaiter(requestedItems: number, onAcquire: () => void): SemaphoreWaitNode<T> {
+    const node: SemaphoreWaitNode<T> = {
       isActive: true,
+      acquiredItems: [],
+      remainingItems: requestedItems,
       onAcquire,
       prev: this.lastWaiter
     };
@@ -30,7 +41,7 @@ export class Mutex {
     return node;
   }
 
-  private deactivateWaiter(waiter: MutexWaitNode) {
+  private deactivateWaiter(waiter: SemaphoreWaitNode<T>) {
     const { prev, next } = waiter;
     waiter.isActive = false;
 
@@ -40,77 +51,129 @@ export class Mutex {
     if (waiter == this.lastWaiter) this.lastWaiter = prev;
   }
 
-  acquire(abort?: AbortSignal): Promise<UnlockFn> {
+  private requestPermits(amount: number, abort?: AbortSignal): Promise<{ items: T[]; release: UnlockFn }> {
+    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: SemaphoreWaitNode<T>;
 
       const markCompleted = () => {
-        if (!holdsMutex) return;
-        holdsMutex = false;
+        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);
+          }
+        }
+      };
+
+      const onAbort = () => {
+        abort?.removeEventListener('abort', onAbort);
 
-        const waiter = this.firstWaiter;
-        if (waiter) {
+        if (waiter.isActive) {
           this.deactivateWaiter(waiter);
-          // Still in critical section, but owned by next waiter now.
-          waiter.onAcquire();
-        } else {
-          this.inCriticalSection = false;
+          rejectAborted();
         }
       };
 
-      if (!this.inCriticalSection) {
-        this.inCriticalSection = true;
-        holdsMutex = true;
-        return resolve(markCompleted);
-      } else {
-        let node: MutexWaitNode;
+      const resolvePromise = () => {
+        this.deactivateWaiter(waiter);
+        abort?.removeEventListener('abort', onAbort);
 
-        const onAbort = () => {
-          abort?.removeEventListener('abort', onAbort);
+        const items = waiter.acquiredItems;
+        resolve({ items, release: markCompleted });
+      };
 
-          if (node.isActive) {
-            this.deactivateWaiter(node);
-            rejectAborted();
-          }
-        };
+      waiter = this.addWaiter(amount, resolvePromise);
 
-        node = this.addWaiter(() => {
-          abort?.removeEventListener('abort', onAbort);
-          holdsMutex = true;
-          resolve(markCompleted);
-        });
+      // 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--;
+      }
 
-        abort?.addEventListener('abort', onAbort);
+      if (waiter.remainingItems == 0) {
+        return resolvePromise();
       }
+
+      abort?.addEventListener('abort', onAbort);
     });
   }
 
-  async runExclusive<T>(fn: () => PromiseLike<T> | T, abort?: AbortSignal): Promise<T> {
-    const returnMutex = await this.acquire(abort);
+  /**
+   * Requests a single item from the pool.
+   *
+   * The returned `release` callback must be invoked to return the item into the pool.
+   */
+  async requestOne(abort?: AbortSignal): Promise<{ item: T; release: UnlockFn }> {
+    const { items, release } = await this.requestPermits(1, abort);
+    return { release, item: items[0] };
+  }
 
-    try {
-      return await fn();
-    } finally {
-      returnMutex();
-    }
+  /**
+   * Requests access to all items from the pool.
+   *
+   * The returned `release` callback must be invoked to return items into the pool.
+   */
+  requestAll(abort?: AbortSignal): Promise<{ items: T[]; release: UnlockFn }> {
+    return this.requestPermits(this.size, abort);
   }
 }
 
-interface MutexWaitNode {
+interface SemaphoreWaitNode<T> {
   /**
    * Whether the waiter is currently active (not aborted and not fullfilled).
    */
   isActive: boolean;
+  acquiredItems: T[];
+  remainingItems: number;
   onAcquire: () => void;
-  prev?: MutexWaitNode;
-  next?: MutexWaitNode;
+  prev?: SemaphoreWaitNode<T>;
+  next?: SemaphoreWaitNode<T>;
+}
+
+/**
+ * An asynchronous mutex implementation.
+ *
+ * @internal This class is meant to be used in PowerSync SDKs only, and is not part of the public API.
+ */
+export class Mutex {
+  private inner = new Semaphore([null]);
+
+  async acquire(abort?: AbortSignal): Promise<UnlockFn> {
+    const { release } = await this.inner.requestOne(abort);
+    return release;
+  }
+
+  async runExclusive<T>(fn: () => PromiseLike<T> | T, abort?: AbortSignal): Promise<T> {
+    const returnMutex = await this.acquire(abort);
+
+    try {
+      return await fn();
+    } finally {
+      returnMutex();
+    }
+  }
 }
 
 /**

package/src/utils/queue.ts

@@ -0,0 +1,48 @@
+/**
+ * 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}.
+ */
+export class Queue<T> {
+  private table: (T | undefined)[];
+  // Index of the first element in the table.
+  private head: number;
+  // Amount of items currently in the queue.
+  private _length: number;
+
+  constructor(initialItems: Iterable<T>) {
+    this.table = [...initialItems];
+    this.head = 0;
+    this._length = this.table.length;
+  }
+
+  get isEmpty(): boolean {
+    return this.length == 0;
+  }
+
+  get length(): number {
+    return this._length;
+  }
+
+  removeFirst(): T {
+    if (this.isEmpty) {
+      throw new Error('Queue is empty');
+    }
+
+    const result = this.table[this.head] as T;
+    this._length--;
+    this.table[this.head] = undefined;
+    this.head = (this.head + 1) % this.table.length;
+    return result;
+  }
+
+  addLast(element: T) {
+    if (this.length == this.table.length) {
+      throw new Error('Queue is full');
+    }
+
+    this.table[(this.head + this._length) % this.table.length] = element;
+    this._length++;
+  }
+}