@fluidframework/tree 2.4.0-297385 → 2.4.0-299374

package/lib/core/tree/anchorSet.d.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 import { type Listenable } from "../../events/index.js";
-import { type Brand, type BrandedKey, type BrandedMapSubset, type Opaque } from "../../util/index.js";
+import { type Brand, type BrandedKey, type BrandedMapSubset, type Opaque, ReferenceCountedBase } from "../../util/index.js";
 import type { FieldKey } from "../schema-stored/index.js";
 import type { UpPath } from "./pathTree.js";
 import type { DeltaVisitor } from "./visitDelta.js";
@@ -185,6 +185,12 @@ export interface AnchorNode extends UpPath<AnchorNode>, Listenable<AnchorEvents>
      *
      */
     child(key: FieldKey, index: number): UpPath<AnchorNode>;
+    /**
+     * Gets the child AnchorNode if already exists.
+     *
+     * Does NOT add a ref, so the returned AnchorNode must be used with care.
+     */
+    childIfAnchored(key: FieldKey, index: number): AnchorNode | undefined;
     /**
      * Gets a child AnchorNode (creating it if needed), and an Anchor owning a ref to it.
      * Caller is responsible for freeing the returned Anchor, and must not use the AnchorNode after that.
@@ -276,8 +282,10 @@ export declare class AnchorSet implements Listenable<AnchorSetRootEvents>, Ancho
     private trackInner;
     /**
      * Finds a path node if it already exists.
+     *
+     * Does not add a ref!
      */
-    private find;
+    find(path: UpPath): PathNode | undefined;
     /**
      * Returns an equivalent path making as much of it with PathNodes as possible.
      * This allows future operations (like find, track, locate) on this path (and derived ones) to be faster.
@@ -364,4 +372,153 @@ export declare class AnchorSet implements Listenable<AnchorSetRootEvents>, Ancho
      */
     acquireVisitor(): AnnouncedVisitor & DeltaVisitor;
 }
+/**
+ * Indicates the status of a `NodePath`.
+ */
+declare enum Status {
+    /**
+     * Indicates the `NodePath` is being maintained and corresponds to a valid
+     * (i.e., not removed) node in the document.
+     */
+    Alive = 0,
+    /**
+     * Indicates the `NodePath` is not being maintained by the `AnchorSet`.
+     * The `NodePath` may or may not correspond to a valid node in the document.
+     *
+     * Accessing such a node is invalid.
+     * Nodes in this state are retained to detect use-after-free bugs.
+     */
+    Disposed = 1,
+    /**
+     * Indicates the `NodePath` corresponds to a removed node in the document.
+     * Such `NodePath`s are not maintained by the `AnchorSet` (other than updating
+     * their status to `Disposed` when appropriate).
+     *
+     * Accessing such a node is invalid.
+     * Nodes in this state are retained to detect use-after-free bugs.
+     */
+    Dangling = 2
+}
+/**
+ * Tree of anchors.
+ *
+ * Contains both child and parent pointers, which are kept in sync.
+ *
+ * Each anchor is equivalent to a path through the tree.
+ * This tree structure stores a collection of these paths, but deduplicating the common prefixes of the tree
+ * prefix-tree style.
+ *
+ * These anchors are used instead of just holding onto the node objects in forests for several reasons:
+ *
+ * - Update policy might be more complex than just tracking a node object in the forest.
+ *
+ * - Not all forests will have node objects: some may use compressed binary formats with no objects to reference.
+ *
+ * - Anchors are needed even when not using forests, and for nodes that are outside the currently loaded part of the
+ * forest.
+ *
+ * - Forest in general do not need to support up pointers, but they are needed for anchors.
+ *
+ * Thus this can be thought of as a sparse copy of the subset of trees which are used as anchors,
+ * plus the parent paths for them.
+ *
+ * ReferenceCountedBase tracks the number of references to this from external sources (`Anchors` via `AnchorSet`.).
+ * Kept alive as if any of the follow are true:
+ * 1. there are children.
+ * 2. refcount is non-zero.
+ * 3. events are registered.
+ */
+declare class PathNode extends ReferenceCountedBase implements UpPath<PathNode>, AnchorNode {
+    readonly anchorSet: AnchorSet;
+    parentField: FieldKey;
+    parentIndex: number;
+    /**
+     * The parent of this `PathNode` (an up pointer in the `PathNode` tree).
+     * If the status of this node is `Alive`, then there must be a corresponding down pointer from the
+     * `parentPath` node to this node.
+     * When undefined, this node is the {@link AnchorSet.root} for `this.anchorSet` and thus has no parent.
+     *
+     * When updating the tree, `AnchorSet` may transiently leave the up and down pointers inconsistent
+     * (updating down pointers first), but must ensure they are consistent before the editing operation returns
+     * to non-`AnchorSet` code.
+     * This consistency guarantee only applies to nodes that are `Alive`.
+     */
+    parentPath: PathNode | undefined;
+    status: Status;
+    /**
+     * Event emitter for this anchor.
+     */
+    readonly events: Listenable<AnchorEvents> & import("../../events/emitter.js").IEmitter<AnchorEvents> & import("../../events/emitter.js").HasListeners<AnchorEvents>;
+    /**
+     * PathNode arrays are kept sorted the PathNode's parentIndex for efficient search.
+     * Users of this field must take care to maintain invariants (correct parent pointers, not empty child arrays etc.)
+     *
+     * Performance Note:
+     * Large child lists could be updated more efficiently here using a data-structure optimized
+     * for efficient prefix sum updates, such as a Fenwick tree or Finger tree.
+     * This would be complicated by the need for parent pointers (including indexes),
+     * but is possible to do.
+     */
+    readonly children: Map<FieldKey, PathNode[]>;
+    readonly slots: BrandedMapSubset<AnchorSlot<any>>;
+    /**
+     * Construct a PathNode with refcount 1.
+     * @param anchorSet - used to determine if this PathNode is already part of a specific anchorSet
+     * to early out UpPath walking.
+     */
+    constructor(anchorSet: AnchorSet, parentField: FieldKey, parentIndex: number, 
+    /**
+     * The parent of this `PathNode` (an up pointer in the `PathNode` tree).
+     * If the status of this node is `Alive`, then there must be a corresponding down pointer from the
+     * `parentPath` node to this node.
+     * When undefined, this node is the {@link AnchorSet.root} for `this.anchorSet` and thus has no parent.
+     *
+     * When updating the tree, `AnchorSet` may transiently leave the up and down pointers inconsistent
+     * (updating down pointers first), but must ensure they are consistent before the editing operation returns
+     * to non-`AnchorSet` code.
+     * This consistency guarantee only applies to nodes that are `Alive`.
+     */
+    parentPath: PathNode | undefined);
+    on<K extends keyof AnchorEvents>(eventName: K, listener: AnchorEvents[K]): () => void;
+    child(key: FieldKey, index: number): UpPath<AnchorNode>;
+    getOrCreateChildRef(key: FieldKey, index: number): [Anchor, AnchorNode];
+    /**
+     * @returns true iff this PathNode is the special root node that sits above all the detached fields.
+     * In this case, the fields are detached sequences.
+     * Note that the special root node should never appear in an UpPath
+     * since UpPaths represent this root as `undefined`.
+     */
+    private isRoot;
+    get parent(): PathNode | undefined;
+    addRef(count?: number): void;
+    removeRef(count?: number): void;
+    protected onUnreferenced(): void;
+    /**
+     * Gets a child, adding a ref to it.
+     * Creates child (with 1 ref) if needed.
+     */
+    getOrCreateChild(key: FieldKey, index: number): PathNode;
+    childIfAnchored(key: FieldKey, index: number): PathNode | undefined;
+    /**
+     * Removes reference from this to `child`.
+     * Since PathNodes are doubly linked,
+     * the caller must ensure that the reference from child to parent is also removed (or the child is no longer used).
+     */
+    removeChild(child: PathNode): void;
+    /**
+     * Call this after directly editing the child array for a field to be empty.
+     * Handles cleaning up unneeded data
+     * (like the field in the map, and possibly this entire PathNode and its parents if they are no longer needed.)
+     */
+    afterEmptyField(key: FieldKey): void;
+    /**
+     * If node is no longer needed (has no references, no children and no events):
+     * removes this from parent if alive, and sets this to disposed.
+     * Must only be called when .
+     *
+     * Allowed when dangling (but not when disposed).
+     */
+    private considerDispose;
+}
+export {};
 //# sourceMappingURL=anchorSet.d.ts.map

package/lib/core/tree/anchorSet.d.ts.map

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

package/lib/core/tree/anchorSet.js

@@ -157,6 +157,8 @@ export class AnchorSet {
     }
     /**
      * Finds a path node if it already exists.
+     *
+     * Does not add a ref!
      */
     find(path) {
         if (path instanceof PathNode) {
@@ -166,7 +168,7 @@ export class AnchorSet {
         }
         const parent = path.parent ?? this.root;
         const parentPath = this.find(parent);
-        return parentPath?.tryGetChild(path.parentField, path.parentIndex);
+        return parentPath?.childIfAnchored(path.parentField, path.parentIndex);
     }
     /**
      * Returns an equivalent path making as much of it with PathNodes as possible.
@@ -193,7 +195,7 @@ export class AnchorSet {
         while ((wrapWith = stack.pop()) !== undefined) {
             if (path === undefined || path instanceof PathNode) {
                 // If path already has an anchor, get an anchor for it's child if there is one:
-                const child = (path ?? this.root).tryGetChild(wrapWith.parentField, wrapWith.parentIndex);
+                const child = (path ?? this.root).childIfAnchored(wrapWith.parentField, wrapWith.parentIndex);
                 if (child !== undefined) {
                     path = child;
                     continue;
@@ -833,7 +835,11 @@ class PathNode extends ReferenceCountedBase {
     }
     child(key, index) {
         // Fast path: if child exists, return it.
-        return (this.tryGetChild(key, index) ?? { parent: this, parentField: key, parentIndex: index });
+        return (this.childIfAnchored(key, index) ?? {
+            parent: this,
+            parentField: key,
+            parentIndex: index,
+        });
     }
     getOrCreateChildRef(key, index) {
         const anchor = this.anchorSet.track(this.child(key, index));
@@ -882,8 +888,7 @@ class PathNode extends ReferenceCountedBase {
             field = [];
             this.children.set(key, field);
         }
-        // TODO: should do more optimized search (ex: binary search).
-        let child = field.find((c) => c.parentIndex === index);
+        let child = binaryFind(field, index);
         if (child === undefined) {
             child = new PathNode(this.anchorSet, key, index, this);
             field.push(child);
@@ -895,15 +900,10 @@ class PathNode extends ReferenceCountedBase {
         }
         return child;
     }
-    /**
-     * Gets a child if it exists.
-     * Does NOT add a ref.
-     */
-    tryGetChild(key, index) {
+    childIfAnchored(key, index) {
         assert(this.status === Status.Alive, 0x40d /* PathNode must be alive */);
         const field = this.children.get(key);
-        // TODO: should do more optimized search (ex: binary search or better) using index.
-        return field?.find((c) => c.parentIndex === index);
+        return field === undefined ? undefined : binaryFind(field, index);
     }
     /**
      * Removes reference from this to `child`.
@@ -950,4 +950,46 @@ class PathNode extends ReferenceCountedBase {
         }
     }
 }
+/**
+ * Find a child PathNode by index using a binary search.
+ * @param sorted - array of PathNode's sorted by parentIndex.
+ * @param index - index being looked for.
+ * @returns child with the requested parentIndex, or undefined.
+ * @privateRemarks
+ * This function is very commonly used with small arrays (length 0 or one for all non sequence fields),
+ * and is currently a hot path due to how flex tree leaves to excessive cursor to anchor and anchor to cursor translations,
+ * both of which walk paths down the AnchorSet.
+ * Additionally current usages tends to fully populate the anchor tree leading the correct array index to be the requested parent index.
+ * This makes the performance of this performance both important in small cases and easy to overly tune to the current usage patterns.
+ * This lead to not implementing a general purpose reusable binary search.
+ * Once this function is not so heavily overused due to inefficient patterns in flex-tree,
+ * replacing it with a standard binary search is likely fine.
+ * Until then, care and benchmarking should be used when messing with this function.
+ */
+function binaryFind(sorted, index) {
+    // Try guessing the list is not sparse as a starter:
+    const guess = sorted[index];
+    if (guess !== undefined && guess.parentIndex === index) {
+        return guess;
+    }
+    // inclusive
+    let min = 0;
+    // exclusive
+    let max = sorted.length;
+    while (min !== max) {
+        const mid = Math.floor((min + max) / 2);
+        const item = sorted[mid];
+        const found = item.parentIndex;
+        if (found === index) {
+            return item; // Found the target, return it.
+        }
+        else if (found > index) {
+            max = mid; // Continue search on lower half.
+        }
+        else {
+            min = mid + 1; // Continue search on left half.
+        }
+    }
+    return undefined; // If we reach here, target is not in array (or array was not sorted)
+}
 //# sourceMappingURL=anchorSet.js.map