@fluidframework/container-runtime 1.4.0-121020 → 2.0.0-dev-rc.1.0.0.224419

package/lib/gc/garbageCollection.d.mts

@@ -0,0 +1,224 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { IRequest } from "@fluidframework/core-interfaces";
+import { IGarbageCollectionDetailsBase, ISummarizeResult, ITelemetryContext } from "@fluidframework/runtime-definitions";
+import { ITelemetryLoggerExt } from "@fluidframework/telemetry-utils";
+import { RuntimeHeaderData } from "../containerRuntime.mjs";
+import { ContainerRuntimeGCMessage } from "../messageTypes.mjs";
+import { IRefreshSummaryResult } from "../summary/index.mjs";
+import { IGarbageCollector, IGarbageCollectorCreateParams, IGCStats, IGCMetadata } from "./gcDefinitions.mjs";
+/**
+ * The garbage collector for the container runtime. It consolidates the garbage collection functionality and maintains
+ * its state across summaries.
+ *
+ * Node - represented as nodeId, it's a node on the GC graph
+ *
+ * Outbound Route - a path from one node to another node, think `nodeA` -\> `nodeB`
+ *
+ * Graph - all nodes with their respective routes
+ *
+ * ```
+ *			 GC Graph
+ *
+ *			   Node
+ *		NodeId = "datastore1"
+ *		   /			 \\
+ *	OutboundRoute   OutboundRoute
+ *		 /				 \\
+ *	   Node			   Node
+ *  NodeId = "dds1"	 NodeId = "dds2"
+ * ```
+ */
+export declare class GarbageCollector implements IGarbageCollector {
+    static create(createParams: IGarbageCollectorCreateParams): IGarbageCollector;
+    private readonly mc;
+    private readonly configs;
+    get shouldRunGC(): boolean;
+    private gcDataFromLastRun;
+    private readonly newReferencesSinceLastRun;
+    private tombstones;
+    private deletedNodes;
+    private readonly baseSnapshotDataP;
+    private readonly initializeGCStateFromBaseSnapshotP;
+    private readonly baseGCDetailsP;
+    private readonly unreferencedNodesState;
+    private sessionExpiryTimer;
+    private completedRuns;
+    private readonly runtime;
+    private readonly isSummarizerClient;
+    private readonly summaryStateTracker;
+    private readonly telemetryTracker;
+    /** If false, loading or using a Tombstoned object should merely log, not fail */
+    get tombstoneEnforcementAllowed(): boolean;
+    /** If true, throw an error when a tombstone data store is retrieved */
+    get throwOnTombstoneLoad(): boolean;
+    /** If true, throw an error when a tombstone data store is used */
+    get throwOnTombstoneUsage(): boolean;
+    /** For a given node path, returns the node's package path. */
+    private readonly getNodePackagePath;
+    /** Returns the timestamp of the last summary generated for this container. */
+    private readonly getLastSummaryTimestampMs;
+    private readonly submitMessage;
+    get summaryStateNeedsReset(): boolean;
+    /** Returns the count of data stores whose GC state updated since the last summary. */
+    get updatedDSCountSinceLastSummary(): number;
+    protected constructor(createParams: IGarbageCollectorCreateParams);
+    /**
+     * Called during container initialization. Initializes the tombstone and deleted nodes state from the base snapshot.
+     * Also, initializes the GC state including unreferenced nodes tracking if a current reference timestamp exists.
+     * Note that if there is any GC state in the base snapshot, then there will definitely be a reference timestamp
+     * to work with - The GC state would have been generated using a timestamp which is part of the snapshot.
+     */
+    initializeBaseState(): Promise<void>;
+    /**
+     * Initialize the GC state if not already initialized. If GC state is already initialized, update the unreferenced
+     * state tracking as per the current reference timestamp.
+     */
+    private initializeOrUpdateGCState;
+    /**
+     * Called when the connection state of the runtime changes, i.e., it connects or disconnects. GC subscribes to this
+     * to initialize or update the unreference state tracking.
+     * @param connected - Whether the runtime connected / disconnected.
+     * @param clientId - The clientId of this runtime.
+     */
+    setConnectionState(connected: boolean, clientId?: string | undefined): void;
+    /**
+     * Returns a the GC details generated from the base summary. This is used to initialize the GC state of the nodes
+     * in the container.
+     */
+    getBaseGCDetails(): Promise<IGarbageCollectionDetailsBase>;
+    /**
+     * Runs garbage collection and updates the reference / used state of the nodes in the container.
+     * @returns stats of the GC run or undefined if GC did not run.
+     */
+    collectGarbage(options: {
+        /** Logger to use for logging GC events */
+        logger?: ITelemetryLoggerExt;
+        /** True to run GC sweep phase after the mark phase */
+        runSweep?: boolean;
+        /** True to generate full GC data */
+        fullGC?: boolean;
+    }, telemetryContext?: ITelemetryContext): Promise<IGCStats | undefined>;
+    /**
+     * Runs garbage collection. It does the following:
+     *
+     * 1. It generates / analyzes the runtime's reference graph.
+     *
+     * 2. Generates mark phase stats.
+     *
+     * 3. Runs Mark phase.
+     *
+     * 4. Runs Sweep phase.
+     *
+     * 5. Generates sweep phase stats.
+     */
+    private runGC;
+    /**
+     * Runs the GC Mark phase. It does the following:
+     *
+     * 1. Marks all referenced nodes in this run by clearing tracking for them.
+     *
+     * 2. Marks unreferenced nodes in this run by starting tracking for them.
+     *
+     * 3. Calls the runtime to update nodes that were marked referenced.
+     *
+     * @param gcResult - The result of the GC run on the gcData.
+     * @param allReferencedNodeIds - Nodes referenced in this GC run + referenced between previous and current GC run.
+     * @param currentReferenceTimestampMs - The timestamp to be used for unreferenced nodes' timestamp.
+     * @returns The sets of tombstone-ready and sweep-ready nodes, i.e., nodes that ready to be tombstoned or deleted.
+     */
+    private runMarkPhase;
+    /**
+     * Runs the GC Sweep phase. It does the following:
+     *
+     * 1. Marks tombstone-ready nodes as tombstones.
+     *
+     * 2. Sends a sweep op to delete nodes that are sweep-ready. Once the op is ack'd, these nodes will be deleted.
+     *
+     * @param gcResult - The result of the GC run on the gcData.
+     * @param tombstoneReadyNodes - List of nodes that are tombstone-ready.
+     * @param sweepReadyNodes - List of nodes that are sweep-ready.
+     */
+    private runSweepPhase;
+    /**
+     * Since GC runs periodically, the GC data that is generated only tells us the state of the world at that point in
+     * time. There can be nodes that were referenced in between two runs and their unreferenced state needs to be
+     * updated. For example, in the following scenarios not updating the unreferenced timestamp can lead to deletion of
+     * these objects while there can be in-memory referenced to it:
+     * 1. A node transitions from `unreferenced -> referenced -> unreferenced` between two runs. When the reference is
+     * added, the object may have been accessed and in-memory reference to it added.
+     * 2. A reference is added from one unreferenced node to one or more unreferenced nodes. Even though the node[s] were
+     * unreferenced, they could have been accessed and in-memory reference to them added.
+     *
+     * This function identifies nodes that were referenced since the last run.
+     * If these nodes are currently unreferenced, they will be assigned new unreferenced state by the current run.
+     *
+     * @returns A list of all nodes referenced from the last local summary until now.
+     */
+    private findAllNodesReferencedBetweenGCs;
+    /**
+     * Summarizes the GC data and returns it as a summary tree.
+     * We current write the entire GC state in a single blob. This can be modified later to write multiple
+     * blobs. All the blob keys should start with `gcBlobPrefix`.
+     */
+    summarize(fullTree: boolean, trackState: boolean, telemetryContext?: ITelemetryContext): ISummarizeResult | undefined;
+    getMetadata(): IGCMetadata;
+    /**
+     * Called to refresh the latest summary state. This happens when either a pending summary is acked.
+     */
+    refreshLatestSummary(result: IRefreshSummaryResult): Promise<void>;
+    /**
+     * Process a GC message.
+     * @param message - The GC message from the container runtime.
+     * @param local - Whether it was send by this client.
+     */
+    processMessage(message: ContainerRuntimeGCMessage, local: boolean): void;
+    /**
+     * Delete nodes that are sweep-ready. Call the runtime to delete these nodes and clear the unreferenced state
+     * tracking for nodes that are actually deleted by the runtime.
+     * @param sweepReadyNodeIds - The ids of nodes that are ready to be deleted.
+     */
+    private deleteSweepReadyNodes;
+    /**
+     * Called when a node with the given id is updated. If the node is inactive or tombstoned, this will log an error
+     * or throw an error if failing on incorrect usage is configured.
+     * @param nodePath - The path of the node that changed.
+     * @param reason - Whether the node was loaded or changed.
+     * @param timestampMs - The timestamp when the node changed.
+     * @param packagePath - The package path of the node. This may not be available if the node hasn't been loaded yet.
+     * @param request - The original request for loads to preserve it in telemetry.
+     * @param requestHeaders - If the node was loaded via request path, the headers in the request.
+     */
+    nodeUpdated(nodePath: string, reason: "Loaded" | "Changed", timestampMs?: number, packagePath?: readonly string[], request?: IRequest, headerData?: RuntimeHeaderData): void;
+    /**
+     * Called when an outbound reference is added to a node. This is used to identify all nodes that have been
+     * referenced between summaries so that their unreferenced timestamp can be reset.
+     *
+     * @param fromNodePath - The node from which the reference is added.
+     * @param toNodePath - The node to which the reference is added.
+     */
+    addedOutboundReference(fromNodePath: string, toNodePath: string): void;
+    /**
+     * Returns whether a node with the given path has been deleted or not. This can be used by the runtime to identify
+     * cases where objects are used after they are deleted and throw / log errors accordingly.
+     */
+    isNodeDeleted(nodePath: string): boolean;
+    dispose(): void;
+    /**
+     * Generates the stats of a garbage collection mark phase run.
+     * @param gcResult - The result of the current GC run.
+     * @returns the stats of the mark phase run.
+     */
+    private getMarkPhaseStats;
+    /**
+     * Generates the stats of a garbage collection sweep phase run.
+     * @param deletedNodes - The nodes that have been deleted until this run.
+     * @param sweepReadyNodes - The nodes that are sweep-ready in this GC run.
+     * @param markPhaseStats - The stats of the mark phase run.
+     * @returns the stats of the sweep phase run.
+     */
+    private getSweepPhaseStats;
+}
+//# sourceMappingURL=garbageCollection.d.ts.map

package/lib/gc/garbageCollection.d.mts.map

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