@fluidframework/merge-tree 1.2.1 → 2.0.0-internal.1.0.0

package/lib/partialLengths.d.ts

@@ -3,48 +3,163 @@
  * Licensed under the MIT License.
  */
 import { RedBlackTree } from "./collections";
-import { CollaborationWindow, IMergeBlock, MergeTree } from "./mergeTree";
+import { CollaborationWindow, IMergeBlock } from "./mergeTreeNodes";
 interface IOverlapClient {
     clientId: number;
     seglen: number;
 }
+/**
+ * Tracks length information for a part of a MergeTree (block) at a given time (seq).
+ * These objects are associated with internal nodes (i.e. blocks).
+ */
 export interface PartialSequenceLength {
+    /**
+     * Sequence number
+     */
     seq: number;
+    /**
+     * The length of the associated block.
+     */
     len: number;
+    /**
+     * The delta between the current length of the associated block and its length at the previous seq number.
+     */
     seglen: number;
+    /**
+     * clientId for the client that submitted the op with sequence number `seq`.
+     */
     clientId?: number;
+    /**
+     * This field maps each client to the size of the intersection between segments deleted at this seq
+     * and segments concurrently deleted by that client.
+     *
+     * For example, this PartialSequenceLength:
+     * ```typescript
+     * {
+     *     seq: 5,
+     *     len: 100,
+     *     seglen: -10,
+     *     clientId: 0,
+     *     overlapRemoveClients: <RedBlack tree with key-values expressed by>{
+     *         1: { clientId: 1, seglen: -5 },
+     *         3: { clientId: 3, seglen: -10 }
+     *     }
+     * }
+     * ```
+     *
+     * corresponds to an op submitted by client 0 which:
+     * - reduces the length of this block by 10 (it may have deleted a single segment of length 10,
+     *     several segments totalling length 10, or even delete and add content for a total reduction of 10 length)
+     * - was concurrent to an op submitted by client 1 that also removed some of the same segments,
+     *     whose length totalled 5
+     * - was concurrent to an op submitted by client 3 that removed some of the same segments,
+     *     whose length totalled 10
+     */
     overlapRemoveClients?: RedBlackTree<number, IOverlapClient>;
 }
 /**
- * Keep track of partial sums of segment lengths for all sequence numbers
- * in the current collaboration window (if any).  Only used during active
- * collaboration.
+ * Keeps track of partial sums of segment lengths for all sequence numbers in the current collaboration window.
+ * Only used during active collaboration.
+ *
+ * This class is associated with an internal node (block) of a MergeTree. It efficiently answers queries of the form
+ * "What is the length of `block` from the perspective of some particular seq and clientId?".
+ *
+ * It also supports incremental updating of state for newly-sequenced ops that don't affect the structure of the
+ * MergeTree.
+ *
+ * To answer these queries, it pre-builds several lists which track the length of the block at a per-sequence-number
+ * level. These lists are:
+ *
+ * 1. (`partialLengths`): Stores the total length of the block.
+ * 2. (`clientSeqNumbers[clientId]`): Stores only the total lengths of segments submitted by `clientId`. [see footnote]
+ *
+ * The reason both lists are necessary is that resolving the length of the block from the perspective of
+ * (clientId, refSeq) requires including both of the following types of segments:
+ * 1. Segments sequenced before `refSeq`
+ * 2. Segments submitted by `clientId`
+ *
+ * This is possible with the above bookkeeping, using:
+ *
+ * (length of the block at the minimum sequence number)
+ * + (partialLengths total length at refSeq)
+ * + (clientSeqNumbers total length at most recent op)
+ * - (clientSeqNumbers total length at refSeq)
+ *
+ * where the subtraction avoids double-counting segments submitted by clientId sequenced within the collab window.
+ *
+ * This algorithm scales roughly linearly with number of editing clients and the size of the collab window.
+ * (certain unlikely sequences of operations may introduce log factors on those variables)
+ *
+ * Note: there is some slight complication with clientSeqNumbers resulting from the possibility of different clients
+ * concurrently removing the same segment. See the field's documentation for more details.
  */
 export declare class PartialSequenceLengths {
+    /**
+     * The minimumSequenceNumber as defined by the collab window used in the last call to `update`,
+     * or if no such calls have been made, the one used on construction.
+    */
     minSeq: number;
     static options: {
         verify: boolean;
         zamboni: boolean;
     };
-    static combine(mergeTree: MergeTree, block: IMergeBlock, collabWindow: CollaborationWindow, recur?: boolean): PartialSequenceLengths;
     /**
      * Combine the partial lengths of block's children
-     * @param block - an interior node; it is assumed that each interior node child of this block
-     * has its partials up to date
-     * @param collabWindow - segment window of the segment tree containing textSegmentBlock
+     * @param block - an interior node. If `recur` is false, it is assumed that each interior node child of this block
+     * has its partials up to date.
+     * @param collabWindow - segment window of the segment tree containing `block`.
+     * @param recur - whether to recursively compute partial lengths for internal children of `block`.
+     * This incurs more work, but gives correct bookkeeping in the case that a descendant in the merge tree has been
+     * modified without bubbling up the resulting partial length change to this block's partials.
+     */
+    static combine(block: IMergeBlock, collabWindow: CollaborationWindow, recur?: boolean): PartialSequenceLengths;
+    /**
+     * @returns a PartialSequenceLengths structure which tracks only lengths of leaf children of the provided
+     * IMergeBlock.
      */
-    private static combineBranch;
     private static fromLeaves;
     private static getOverlapClients;
     private static accumulateRemoveClientOverlap;
+    /**
+     * Inserts length information about the insertion of `segment` into `combinedPartialLengths.partialLengths`.
+     * Does not update the clientSeqNumbers field to account for this segment.
+     * If `removalInfo` is defined, this operation updates the bookkeeping to account for the removal of this
+     * segment at the removedSeq instead.
+     */
     private static insertSegment;
     private static addSeq;
-    minLength: number;
-    segmentCount: number;
-    partialLengths: PartialSequenceLength[];
-    clientSeqNumbers: PartialSequenceLength[][];
-    constructor(minSeq: number);
-    update(mergeTree: MergeTree, node: IMergeBlock, seq: number, clientId: number, collabWindow: CollaborationWindow): void;
+    /**
+     * Length of the block this PartialSequenceLength corresponds to when viewed at `minSeq`.
+     */
+    private minLength;
+    /**
+     * Total number of segments in the subtree rooted at the block this PartialSequenceLength corresponds to.
+     */
+    private segmentCount;
+    /**
+     * List of PartialSequenceLength objects--ordered by increasing seq--giving length information about
+     * the block associated with this PartialSequenceLengths object.
+     *
+     * `partialLengths[i].len` contains the length of this block considering only sequenced segments with
+     * `sequenceNumber <= partialLengths[i].seq`.
+     */
+    private readonly partialLengths;
+    /**
+     * clientSeqNumbers[clientId] is a list of partial lengths for sequenced ops which either:
+     * - were submitted by `clientId`.
+     * - deleted a range containing segments that were concurrently deleted by `clientId`
+     *
+     * The second case is referred to as the "overlapping delete" case. It is necessary to avoid double-counting
+     * the removal of those segments in queries including clientId.
+     */
+    private readonly clientSeqNumbers;
+    constructor(
+    /**
+     * The minimumSequenceNumber as defined by the collab window used in the last call to `update`,
+     * or if no such calls have been made, the one used on construction.
+    */
+    minSeq: number);
+    update(node: IMergeBlock, seq: number, clientId: number, collabWindow: CollaborationWindow): void;
     getPartialLength(refSeq: number, clientId: number): number;
     toString(glc?: (id: number) => string, indentCount?: number): string;
     private zamboni;

package/lib/partialLengths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"partialLengths.d.ts","sourceRoot":"","sources":["../src/partialLengths.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,OAAO,EACH,mBAAmB,EAEnB,WAAW,EAGX,SAAS,EAEZ,MAAM,aAAa,CAAC;AAErB,UAAU,cAAc;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAClB;AA2BD,MAAM,WAAW,qBAAqB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oBAAoB,CAAC,EAAE,YAAY,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAC/D;AAED;;;;GAIG;AACH,qBAAa,sBAAsB;IAyUZ,MAAM,EAAE,MAAM;IAxUjC,OAAc,OAAO;;;MAGnB;WAEY,OAAO,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,mBAAmB,EAAE,KAAK,UAAQ;IAIhH;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IAqI5B,OAAO,CAAC,MAAM,CAAC,UAAU;IAoDzB,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAQhC,OAAO,CAAC,MAAM,CAAC,6BAA6B;IAmB5C,OAAO,CAAC,MAAM,CAAC,aAAa;IA6D5B,OAAO,CAAC,MAAM,CAAC,MAAM;IAmCd,SAAS,SAAK;IACd,YAAY,SAAK;IACjB,cAAc,EAAE,qBAAqB,EAAE,CAAM;IAC7C,gBAAgB,EAAE,qBAAqB,EAAE,EAAE,CAAM;gBAErC,MAAM,EAAE,MAAM;IAM1B,MAAM,CACT,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,mBAAmB;IAkD9B,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;IAgCjD,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,EAAE,WAAW,SAAI;IA2B7D,OAAO,CAAC,OAAO;IA8Bf,OAAO,CAAC,kBAAkB;IAa1B,OAAO,CAAC,6BAA6B;IAWrC,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,SAAS;IAUjB,OAAO,CAAC,oBAAoB;IAqD5B,OAAO,CAAC,MAAM;CAqBjB"}
+{"version":3,"file":"partialLengths.d.ts","sourceRoot":"","sources":["../src/partialLengths.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAY,YAAY,EAAE,MAAM,eAAe,CAAC;AAEvD,OAAO,EACH,mBAAmB,EAEnB,WAAW,EAId,MAAM,kBAAkB,CAAC;AAE1B,UAAU,cAAc;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAClB;AA2BD;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IAClC;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,oBAAoB,CAAC,EAAE,YAAY,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAC/D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,sBAAsB;IAkT3B;;;MAGE;IACK,MAAM,EAAE,MAAM;IArTzB,OAAc,OAAO;;;MAGnB;IAEF;;;;;;;;OAQG;WACW,OAAO,CAAC,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,mBAAmB,EAAE,KAAK,UAAQ;IA4E1F;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,UAAU;IAmDzB,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAQhC,OAAO,CAAC,MAAM,CAAC,6BAA6B;IAmB5C;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IAiE5B,OAAO,CAAC,MAAM,CAAC,MAAM;IAgCrB;;OAEG;IACH,OAAO,CAAC,SAAS,CAAK;IAEtB;;OAEG;IACH,OAAO,CAAC,YAAY,CAAK;IAEzB;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA+B;IAE9D;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAiC;;IAG9D;;;MAGE;IACK,MAAM,EAAE,MAAM;IAMlB,MAAM,CACT,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,mBAAmB;IAkD9B,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;IAkCjD,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,EAAE,WAAW,SAAI;IA2B7D,OAAO,CAAC,OAAO;IA+Bf,OAAO,CAAC,kBAAkB;IAa1B,OAAO,CAAC,6BAA6B;IAWrC,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,SAAS;IAUjB,OAAO,CAAC,oBAAoB;IAqD5B,OAAO,CAAC,MAAM;CAqBjB"}