@fluidframework/matrix 2.0.0-internal.7.3.0 → 2.0.0-internal.7.4.0

package/dist/matrix.cjs

@@ -29,19 +29,30 @@ const undoprovider_1 = require("./undoprovider.cjs");
  * matrix data and physically stores data in Z-order to leverage CPU caches and
  * prefetching when reading in either row or column major order.  (See README.md
  * for more details.)
- *
- * @public
+ * @alpha
  */
 class SharedMatrix extends shared_object_base_1.SharedObject {
     static getFactory() {
         return new runtime_1.SharedMatrixFactory();
     }
-    constructor(runtime, id, attributes) {
+    /**
+     * Constructor for the Shared Matrix
+     * @param runtime - DataStore runtime.
+     * @param id - id of the dds
+     * @param attributes - channel attributes
+     * @param _isSetCellConflictResolutionPolicyFWW - Conflict resolution for Matrix set op is First Writer Win in case of
+     * race condition. Client can still overwrite values in case of no race.
+     */
+    constructor(runtime, id, attributes, _isSetCellConflictResolutionPolicyFWW) {
         super(id, runtime, attributes, "fluid_matrix_");
         this.id = id;
         this.consumers = new Set();
         this.cells = new sparsearray2d_1.SparseArray2D(); // Stores cell values.
         this.pending = new sparsearray2d_1.SparseArray2D(); // Tracks pending writes.
+        this.cellLastWriteTracker = new sparsearray2d_1.SparseArray2D(); // Tracks last writes sequence number and clientId in a cell.
+        this.userSwitchedSetCellPolicy = false; // Set to true when the user calls switchPolicy.
+        // Used to track if there is any reentrancy in setCell code.
+        this.reentrantCount = 0;
         // Invoked by PermutationVector to notify IMatrixConsumers of row insertion/deletions.
         this.onRowDelta = (position, removedCount, insertedCount) => {
             for (const consumer of this.consumers) {
@@ -58,14 +69,18 @@ class SharedMatrix extends shared_object_base_1.SharedObject {
             for (const rowHandle of rowHandles) {
                 this.cells.clearRows(/* rowStart: */ rowHandle, /* rowCount: */ 1);
                 this.pending.clearRows(/* rowStart: */ rowHandle, /* rowCount: */ 1);
+                this.cellLastWriteTracker.clearRows(/* rowStart: */ rowHandle, /* rowCount: */ 1);
             }
         };
         this.onColHandlesRecycled = (colHandles) => {
             for (const colHandle of colHandles) {
                 this.cells.clearCols(/* colStart: */ colHandle, /* colCount: */ 1);
                 this.pending.clearCols(/* colStart: */ colHandle, /* colCount: */ 1);
+                this.cellLastWriteTracker.clearCols(/* colStart: */ colHandle, /* colCount: */ 1);
             }
         };
+        this.setCellLwwToFwwPolicySwitchOpSeqNumber =
+            _isSetCellConflictResolutionPolicyFWW === true ? 0 : -1;
         this.rows = new permutationvector_1.PermutationVector("rows" /* SnapshotPath.rows */, this.logger, runtime, this.onRowDelta, this.onRowHandlesRecycled);
         this.cols = new permutationvector_1.PermutationVector("cols" /* SnapshotPath.cols */, this.logger, runtime, this.onColDelta, this.onColHandlesRecycled);
     }
@@ -105,6 +120,9 @@ class SharedMatrix extends shared_object_base_1.SharedObject {
     get colCount() {
         return this.cols.getLength();
     }
+    isSetCellConflictResolutionPolicyFWW() {
+        return this.setCellLwwToFwwPolicySwitchOpSeqNumber > -1 || this.userSwitchedSetCellPolicy;
+    }
     getCell(row, col) {
         // Perf: When possible, bounds checking is performed inside the implementation for
         //       'getHandle()' so that it can be elided in the case of a cache hit.  This
@@ -131,10 +149,6 @@ class SharedMatrix extends shared_object_base_1.SharedObject {
     setCell(row, col, value) {
         (0, core_utils_1.assert)(0 <= row && row < this.rowCount && 0 <= col && col < this.colCount, 0x01a /* "Trying to set out-of-bounds cell!" */);
         this.setCellCore(row, col, value);
-        // Avoid reentrancy by raising change notifications after the op is queued.
-        for (const consumer of this.consumers.values()) {
-            consumer.cellsChanged(row, col, 1, 1, this);
-        }
     }
     setCells(rowStart, colStart, colCount, values) {
         const rowCount = Math.ceil(values.length / colCount);
@@ -155,23 +169,25 @@ class SharedMatrix extends shared_object_base_1.SharedObject {
                 r++;
             }
         }
-        // Avoid reentrancy by raising change notifications after the op is queued.
-        for (const consumer of this.consumers.values()) {
-            consumer.cellsChanged(rowStart, colStart, rowCount, colCount, this);
-        }
     }
     setCellCore(row, col, value, rowHandle = this.rows.getAllocatedHandle(row), colHandle = this.cols.getAllocatedHandle(col)) {
-        if (this.undo !== undefined) {
-            let oldValue = this.cells.getCell(rowHandle, colHandle);
-            if (oldValue === null) {
-                oldValue = undefined;
+        this.protectAgainstReentrancy(() => {
+            if (this.undo !== undefined) {
+                let oldValue = this.cells.getCell(rowHandle, colHandle);
+                if (oldValue === null) {
+                    oldValue = undefined;
+                }
+                this.undo.cellSet(rowHandle, colHandle, oldValue);
             }
-            this.undo.cellSet(rowHandle, colHandle, oldValue);
-        }
-        this.cells.setCell(rowHandle, colHandle, value);
-        if (this.isAttached()) {
-            this.sendSetCellOp(row, col, value, rowHandle, colHandle);
-        }
+            this.cells.setCell(rowHandle, colHandle, value);
+            if (this.isAttached()) {
+                this.sendSetCellOp(row, col, value, rowHandle, colHandle);
+            }
+            // Avoid reentrancy by raising change notifications after the op is queued.
+            for (const consumer of this.consumers.values()) {
+                consumer.cellsChanged(row, col, 1, 1, this);
+            }
+        });
     }
     sendSetCellOp(row, col, value, rowHandle, colHandle, localSeq = this.nextLocalSeq(), rowsRefSeq = this.rows.getCollabWindow().currentSeq, colsRefSeq = this.cols.getCollabWindow().currentSeq) {
         (0, core_utils_1.assert)(this.isAttached(), 0x1e2 /* "Caller must ensure 'isAttached()' before calling 'sendSetCellOp'." */);
@@ -180,6 +196,7 @@ class SharedMatrix extends shared_object_base_1.SharedObject {
             row,
             col,
             value,
+            fwwMode: this.userSwitchedSetCellPolicy || this.setCellLwwToFwwPolicySwitchOpSeqNumber > -1,
         };
         const metadata = {
             rowHandle,
@@ -187,10 +204,26 @@ class SharedMatrix extends shared_object_base_1.SharedObject {
             localSeq,
             rowsRefSeq,
             colsRefSeq,
+            referenceSeqNumber: this.runtime.deltaManager.lastSequenceNumber,
         };
         this.submitLocalMessage(op, metadata);
         this.pending.setCell(rowHandle, colHandle, localSeq);
     }
+    /**
+     * This makes sure that the code inside the callback is not reentrant. We need to do that because we raise notifications
+     * to the consumers telling about these changes and they can try to change the matrix while listening to those notifications
+     * which can make the shared matrix to be in bad state. For example, we are raising notification for a setCell changes and
+     * a consumer tries to delete that row/col on receiving that notification which can lead to this matrix trying to setCell in
+     * a deleted row/col.
+     * @param callback - code that needs to protected against reentrancy.
+     */
+    protectAgainstReentrancy(callback) {
+        (0, core_utils_1.assert)(this.reentrantCount === 0, 0x85d /* reentrant code */);
+        this.reentrantCount++;
+        callback();
+        this.reentrantCount--;
+        (0, core_utils_1.assert)(this.reentrantCount === 0, 0x85e /* reentrant code on exit */);
+    }
     submitVectorMessage(currentVector, oppositeVector, dimension, message) {
         // Ideally, we would have a single 'localSeq' counter that is shared between both PermutationVectors
         // and the SharedMatrix's cell data.  Instead, we externally advance each MergeTree's 'localSeq' counter
@@ -213,21 +246,21 @@ class SharedMatrix extends shared_object_base_1.SharedObject {
         this.submitVectorMessage(this.cols, this.rows, "cols" /* SnapshotPath.cols */, message);
     }
     insertCols(colStart, count) {
-        this.submitColMessage(this.cols.insert(colStart, count));
+        this.protectAgainstReentrancy(() => this.submitColMessage(this.cols.insert(colStart, count)));
     }
     removeCols(colStart, count) {
-        this.submitColMessage(this.cols.remove(colStart, count));
+        this.protectAgainstReentrancy(() => this.submitColMessage(this.cols.remove(colStart, count)));
     }
     submitRowMessage(message) {
         this.submitVectorMessage(this.rows, this.cols, "rows" /* SnapshotPath.rows */, message);
     }
     insertRows(rowStart, count) {
-        this.submitRowMessage(this.rows.insert(rowStart, count));
+        this.protectAgainstReentrancy(() => this.submitRowMessage(this.rows.insert(rowStart, count)));
     }
     removeRows(rowStart, count) {
-        this.submitRowMessage(this.rows.remove(rowStart, count));
+        this.protectAgainstReentrancy(() => this.submitRowMessage(this.rows.remove(rowStart, count)));
     }
-    /** @internal */ _undoRemoveRows(rowStart, spec) {
+    /***/ _undoRemoveRows(rowStart, spec) {
         const { op, inserted } = (0, permutationvector_1.reinsertSegmentIntoVector)(this.rows, rowStart, spec);
         this.submitRowMessage(op);
         // Generate setCell ops for each populated cell in the reinserted rows.
@@ -247,7 +280,7 @@ class SharedMatrix extends shared_object_base_1.SharedObject {
             consumer.cellsChanged(rowStart, /* colStart: */ 0, rowCount, this.colCount, this);
         }
     }
-    /** @internal */ _undoRemoveCols(colStart, spec) {
+    /***/ _undoRemoveCols(colStart, spec) {
         const { op, inserted } = (0, permutationvector_1.reinsertSegmentIntoVector)(this.cols, colStart, spec);
         this.submitColMessage(op);
         // Generate setCell ops for each populated cell in the reinserted cols.
@@ -271,7 +304,16 @@ class SharedMatrix extends shared_object_base_1.SharedObject {
         const builder = new runtime_utils_1.SummaryTreeBuilder();
         builder.addWithStats("rows" /* SnapshotPath.rows */, this.rows.summarize(this.runtime, this.handle, serializer));
         builder.addWithStats("cols" /* SnapshotPath.cols */, this.cols.summarize(this.runtime, this.handle, serializer));
-        builder.addBlob("cells" /* SnapshotPath.cells */, serializer.stringify([this.cells.snapshot(), this.pending.snapshot()], this.handle));
+        const artifactsToSummarize = [
+            this.cells.snapshot(),
+            this.pending.snapshot(),
+            this.setCellLwwToFwwPolicySwitchOpSeqNumber,
+        ];
+        // Only need to store it in the snapshot if we have switched the policy already.
+        if (this.setCellLwwToFwwPolicySwitchOpSeqNumber > -1) {
+            artifactsToSummarize.push(this.cellLastWriteTracker.snapshot());
+        }
+        builder.addBlob("cells" /* SnapshotPath.cells */, serializer.stringify(artifactsToSummarize, this.handle));
         return builder.getSummaryTree();
     }
     /**
@@ -340,16 +382,27 @@ class SharedMatrix extends shared_object_base_1.SharedObject {
             default: {
                 (0, core_utils_1.assert)(content.type === ops_1.MatrixOp.set, 0x020 /* "Unknown SharedMatrix 'op' type." */);
                 const setOp = content;
-                const { rowHandle, colHandle, localSeq, rowsRefSeq, colsRefSeq } = localOpMetadata;
-                // If there are more pending local writes to the same row/col handle, it is important
-                // to skip resubmitting this op since it is possible the row/col handle has been recycled
-                // and now refers to a different position than when this op was originally submitted.
-                if (this.isLatestPendingWrite(rowHandle, colHandle, localSeq)) {
-                    const row = this.rebasePosition(this.rows, setOp.row, rowsRefSeq, localSeq);
-                    const col = this.rebasePosition(this.cols, setOp.col, colsRefSeq, localSeq);
-                    if (row !== undefined && col !== undefined && row >= 0 && col >= 0) {
+                const { rowHandle, colHandle, localSeq, rowsRefSeq, colsRefSeq, referenceSeqNumber, } = localOpMetadata;
+                // If after rebasing the op, we get a valid row/col number, that means the row/col
+                // handles have not been recycled and we can safely use them.
+                const row = this.rebasePosition(this.rows, setOp.row, rowsRefSeq, localSeq);
+                const col = this.rebasePosition(this.cols, setOp.col, colsRefSeq, localSeq);
+                if (row !== undefined && col !== undefined && row >= 0 && col >= 0) {
+                    const lastCellModificationDetails = this.cellLastWriteTracker.getCell(rowHandle, colHandle);
+                    // If the mode is LWW, then send the op.
+                    // Otherwise if the current mode is FWW and if we generated this op, after seeing the
+                    // last set op, or it is the first set op for the cell, then regenerate the op,
+                    // otherwise raise conflict. We want to check the current mode here and not that
+                    // whether op was made in FWW or not.
+                    if (this.setCellLwwToFwwPolicySwitchOpSeqNumber === -1 ||
+                        lastCellModificationDetails === undefined ||
+                        referenceSeqNumber >= lastCellModificationDetails.seqNum) {
                         this.sendSetCellOp(row, col, setOp.value, rowHandle, colHandle, localSeq, rowsRefSeq, colsRefSeq);
                     }
+                    else if (this.pending.getCell(rowHandle, colHandle) !== undefined) {
+                        // Clear the pending changes if any as we are not sending the op.
+                        this.pending.setCell(rowHandle, colHandle, undefined);
+                    }
                 }
                 break;
             }
@@ -363,14 +416,32 @@ class SharedMatrix extends shared_object_base_1.SharedObject {
         try {
             await this.rows.load(this.runtime, new runtime_utils_1.ObjectStoragePartition(storage, "rows" /* SnapshotPath.rows */), this.serializer);
             await this.cols.load(this.runtime, new runtime_utils_1.ObjectStoragePartition(storage, "cols" /* SnapshotPath.cols */), this.serializer);
-            const [cellData, pendingCliSeqData] = await (0, serialization_1.deserializeBlob)(storage, "cells" /* SnapshotPath.cells */, this.serializer);
+            const [cellData, _pendingCliSeqData, setCellLwwToFwwPolicySwitchOpSeqNumber, cellLastWriteTracker,] = await (0, serialization_1.deserializeBlob)(storage, "cells" /* SnapshotPath.cells */, this.serializer);
             this.cells = sparsearray2d_1.SparseArray2D.load(cellData);
-            this.pending = sparsearray2d_1.SparseArray2D.load(pendingCliSeqData);
+            this.setCellLwwToFwwPolicySwitchOpSeqNumber =
+                setCellLwwToFwwPolicySwitchOpSeqNumber ?? -1;
+            if (cellLastWriteTracker !== undefined) {
+                this.cellLastWriteTracker = sparsearray2d_1.SparseArray2D.load(cellLastWriteTracker);
+            }
         }
         catch (error) {
             this.logger.sendErrorEvent({ eventName: "MatrixLoadFailed" }, error);
         }
     }
+    /**
+     * Tells whether the setCell op should be applied or not based on First Write Win policy. It assumes
+     * we are in FWW mode.
+     */
+    shouldSetCellBasedOnFWW(rowHandle, colHandle, message) {
+        (0, core_utils_1.assert)(this.setCellLwwToFwwPolicySwitchOpSeqNumber > -1, 0x85f /* should be in Fww mode when calling this method */);
+        (0, core_utils_1.assert)(message.clientId !== null, 0x860 /* clientId should not be null */);
+        const lastCellModificationDetails = this.cellLastWriteTracker.getCell(rowHandle, colHandle);
+        // If someone tried to Overwrite the cell value or first write on this cell or
+        // same client tried to modify the cell.
+        return (lastCellModificationDetails === undefined ||
+            lastCellModificationDetails.clientId === message.clientId ||
+            message.referenceSequenceNumber >= lastCellModificationDetails.seqNum);
+    }
     processCore(rawMessage, local, localOpMetadata) {
         const msg = (0, shared_object_base_1.parseHandles)(rawMessage, this.serializer);
         const contents = msg.contents;
@@ -383,13 +454,28 @@ class SharedMatrix extends shared_object_base_1.SharedObject {
                 break;
             default: {
                 (0, core_utils_1.assert)(contents.type === ops_1.MatrixOp.set, 0x021 /* "SharedMatrix message contents have unexpected type!" */);
-                const { row, col } = contents;
+                const { row, col, value, fwwMode } = contents;
+                const isPreviousSetCellPolicyModeFWW = this.setCellLwwToFwwPolicySwitchOpSeqNumber > -1;
+                // If this is the first op notifying us of the policy change, then set the policy change seq number.
+                if (this.setCellLwwToFwwPolicySwitchOpSeqNumber === -1 && fwwMode === true) {
+                    this.setCellLwwToFwwPolicySwitchOpSeqNumber = rawMessage.sequenceNumber;
+                }
+                (0, core_utils_1.assert)(rawMessage.clientId !== null, 0x861 /* clientId should not be null!! */);
                 if (local) {
                     // We are receiving the ACK for a local pending set operation.
                     const { rowHandle, colHandle, localSeq } = localOpMetadata;
-                    // If this is the most recent write to the cell by the local client, remove our
-                    // entry from 'pendingCliSeqs' to resume allowing remote writes.
-                    if (this.isLatestPendingWrite(rowHandle, colHandle, localSeq)) {
+                    const isLatestPendingOp = this.isLatestPendingWrite(rowHandle, colHandle, localSeq);
+                    // If policy is switched and cell should be modified too based on policy, then update the tracker.
+                    // If policy is not switched, then also update the tracker in case it is the latest.
+                    if ((this.setCellLwwToFwwPolicySwitchOpSeqNumber > -1 &&
+                        this.shouldSetCellBasedOnFWW(rowHandle, colHandle, rawMessage)) ||
+                        (this.setCellLwwToFwwPolicySwitchOpSeqNumber === -1 && isLatestPendingOp)) {
+                        this.cellLastWriteTracker.setCell(rowHandle, colHandle, {
+                            seqNum: rawMessage.sequenceNumber,
+                            clientId: rawMessage.clientId,
+                        });
+                    }
+                    if (isLatestPendingOp) {
                         this.pending.setCell(rowHandle, colHandle, undefined);
                     }
                 }
@@ -401,11 +487,39 @@ class SharedMatrix extends shared_object_base_1.SharedObject {
                             const rowHandle = this.rows.getAllocatedHandle(adjustedRow);
                             const colHandle = this.cols.getAllocatedHandle(adjustedCol);
                             (0, core_utils_1.assert)((0, handletable_1.isHandleValid)(rowHandle) && (0, handletable_1.isHandleValid)(colHandle), 0x022 /* "SharedMatrix row and/or col handles are invalid!" */);
-                            // If there is a pending (unACKed) local write to the same cell, skip the current op
-                            // since it "happened before" the pending write.
-                            if (this.pending.getCell(rowHandle, colHandle) === undefined) {
-                                const { value } = contents;
+                            if (this.setCellLwwToFwwPolicySwitchOpSeqNumber > -1) {
+                                // If someone tried to Overwrite the cell value or first write on this cell or
+                                // same client tried to modify the cell or if the previous mode was LWW, then we need to still
+                                // overwrite the cell and raise conflict if we have pending changes as our change is going to be lost.
+                                if (!isPreviousSetCellPolicyModeFWW ||
+                                    this.shouldSetCellBasedOnFWW(rowHandle, colHandle, rawMessage)) {
+                                    const previousValue = this.cells.getCell(rowHandle, colHandle);
+                                    this.cells.setCell(rowHandle, colHandle, value);
+                                    this.cellLastWriteTracker.setCell(rowHandle, colHandle, {
+                                        seqNum: rawMessage.sequenceNumber,
+                                        clientId: rawMessage.clientId,
+                                    });
+                                    for (const consumer of this.consumers.values()) {
+                                        consumer.cellsChanged(adjustedRow, adjustedCol, 1, 1, this);
+                                    }
+                                    // Check is there are any pending changes, which will be rejected. If so raise conflict.
+                                    if (this.pending.getCell(rowHandle, colHandle) !== undefined) {
+                                        // Don't reset the pending value yet, as there maybe more fww op from same client, so we want
+                                        // to raise conflict event for that op also.
+                                        this.emit("conflict", row, col, value, // Current value
+                                        previousValue, // Ignored local value
+                                        this);
+                                    }
+                                }
+                            }
+                            else if (this.pending.getCell(rowHandle, colHandle) === undefined) {
+                                // If there is a pending (unACKed) local write to the same cell, skip the current op
+                                // since it "happened before" the pending write.
                                 this.cells.setCell(rowHandle, colHandle, value);
+                                this.cellLastWriteTracker.setCell(rowHandle, colHandle, {
+                                    seqNum: rawMessage.sequenceNumber,
+                                    clientId: rawMessage.clientId,
+                                });
                                 for (const consumer of this.consumers.values()) {
                                     consumer.cellsChanged(adjustedRow, adjustedCol, 1, 1, this);
                                 }
@@ -416,6 +530,20 @@ class SharedMatrix extends shared_object_base_1.SharedObject {
             }
         }
     }
+    /**
+     * Api to switch Set Op policy from Last Writer Win to First Writer Win. It only switches from LWW to FWW
+     * and not from FWW to LWW. The next SetOp which is sent will communicate this policy to other clients.
+     */
+    switchSetCellPolicy() {
+        if (this.setCellLwwToFwwPolicySwitchOpSeqNumber === -1) {
+            if (this.isAttached()) {
+                this.userSwitchedSetCellPolicy = true;
+            }
+            else {
+                this.setCellLwwToFwwPolicySwitchOpSeqNumber = 0;
+            }
+        }
+    }
     /**
      * Returns true if the latest pending write to the cell indicated by the given row/col handles
      * matches the given 'localSeq'.
@@ -488,6 +616,7 @@ class SharedMatrix extends shared_object_base_1.SharedObject {
                 localSeq,
                 rowsRefSeq,
                 colsRefSeq,
+                referenceSeqNumber: this.runtime.deltaManager.lastSequenceNumber,
             };
             this.pending.setCell(rowHandle, colHandle, localSeq);
             return metadata;