Add CachingLocator. (microsoft#14020)

Note that we factored out the BackgroundRequestLooper class to keep CachingLocator focused, especially as it was important to deal with one "refresh" at a time.

Author: ericsnowcurrently

src/client/common/utils/backgroundLoop.ts

@@ -0,0 +1,247 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { createDeferred } from './async';
+
+type RequestID = number;
+type RunFunc = () => Promise<void>;
+type NotifyFunc = () => void;
+
+/**
+ * This helps avoid running duplicate expensive operations.
+ *
+ * The key aspect is that already running or queue requests can be
+ * re-used instead of creating a duplicate request.
+ */
+export class BackgroundRequestLooper {
+    private readonly opts: {
+        runDefault: RunFunc;
+    };
+
+    private started = false;
+
+    private stopped = false;
+
+    private readonly done = createDeferred<void>();
+
+    private readonly loopRunning = createDeferred<void>();
+
+    private waitUntilReady = createDeferred<void>();
+
+    private running: RequestID | undefined;
+
+    // For now we don't worry about a max queue size.
+    private readonly queue: RequestID[] = [];
+
+    private readonly requests: Record<RequestID, [RunFunc, Promise<void>, NotifyFunc]> = {};
+
+    private lastID: number | undefined;
+
+    constructor(
+        opts: {
+            runDefault?: RunFunc | null;
+        } = {}
+    ) {
+        this.opts = {
+            runDefault:
+                opts.runDefault ??
+                (async () => {
+                    throw Error('no default operation provided');
+                })
+        };
+    }
+
+    /**
+     * Start the request execution loop.
+     *
+     * Currently it does not support being re-started.
+     */
+    public start(): void {
+        if (this.stopped) {
+            throw Error('already stopped');
+        }
+        if (this.started) {
+            return;
+        }
+        this.started = true;
+
+        this.runLoop().ignoreErrors();
+    }
+
+    /**
+     * Stop the loop (assuming it was already started.)
+     *
+     * @returns - a promise that resolves once the loop has stopped.
+     */
+    public stop(): Promise<void> {
+        if (this.stopped) {
+            return this.loopRunning.promise;
+        }
+        if (!this.started) {
+            throw Error('not started yet');
+        }
+        this.stopped = true;
+
+        this.done.resolve();
+
+        // It is conceivable that a separate "waitUntilStopped"
+        // operation would be useful.  If it turned out to be desirable
+        // then at the point we could add such a method separately.
+        // It would do nothing more than `await this.loopRunning`.
+        // Currently there is no need for a separate method since
+        // returning the promise here is sufficient.
+        return this.loopRunning.promise;
+    }
+
+    /**
+     * Return the most recent active request, if any.
+     *
+     * If there are no pending requests then this is the currently
+     * running one (if one is running).
+     *
+     * @returns - the ID of the request and its completion promise;
+     *            if there are no active requests then you get `undefined`
+     */
+    public getLastRequest(): [RequestID, Promise<void>] | undefined {
+        let reqID: RequestID;
+        if (this.queue.length > 0) {
+            reqID = this.queue[this.queue.length - 1];
+        } else if (this.running !== undefined) {
+            reqID = this.running;
+        } else {
+            return undefined;
+        }
+        // The req cannot be undefined since every queued ID has a request.
+        const [, promise] = this.requests[reqID];
+        if (reqID === undefined) {
+            // The queue must be empty.
+            return undefined;
+        }
+        return [reqID, promise];
+    }
+
+    /**
+     * Return the request that is waiting to run next, if any.
+     *
+     * The request is the next one that will be run.  This implies that
+     * there is one already running.
+     *
+     * @returns - the ID of the request and its completion promise;
+     *            if there are no pending requests then you get `undefined`
+     */
+    public getNextRequest(): [RequestID, Promise<void>] | undefined {
+        if (this.queue.length === 0) {
+            return undefined;
+        }
+        const reqID = this.queue[0];
+        // The req cannot be undefined since every queued ID has a request.
+        const [, promise] = this.requests[reqID]!;
+        return [reqID, promise];
+    }
+
+    /**
+     * Request that a function be run.
+     *
+     * If one is already running then the new request is added to the
+     * end of the queue.  Otherwise it is run immediately.
+     *
+     * @returns - the ID of the new request and its completion promise;
+     *            the promise resolves once the request has completed
+     */
+    public addRequest(run?: RunFunc): [RequestID, Promise<void>] {
+        const reqID = this.getNextID();
+        // This is the only method that adds requests to the queue
+        // and `getNextID()` keeps us from having collisions here.
+        // So we are guaranteed that there are no matching requests
+        // in the queue.
+        const running = createDeferred<void>();
+        this.requests[reqID] = [
+            // [RunFunc, "done" promise, NotifyFunc]
+            run ?? this.opts.runDefault,
+            running.promise,
+            () => running.resolve()
+        ];
+        this.queue.push(reqID);
+        if (this.queue.length === 1) {
+            // `waitUntilReady` will get replaced with a new deferred
+            // in the loop once the existing one gets used.
+            // We let the queue clear out before triggering the loop
+            // again.
+            this.waitUntilReady.resolve();
+        }
+        return [reqID, running.promise];
+    }
+
+    /**
+     * This is the actual loop where the queue is managed and waiting happens.
+     */
+    private async runLoop(): Promise<void> {
+        const getWinner = () => {
+            const promises = [
+                // These are the competing operations.
+                // Note that the losers keep running in the background.
+                this.done.promise.then(() => 0),
+                this.waitUntilReady.promise.then(() => 1)
+            ];
+            return Promise.race(promises);
+        };
+
+        let winner = await getWinner();
+        while (!this.done.completed) {
+            if (winner === 1) {
+                this.waitUntilReady = createDeferred<void>();
+                await this.flush();
+            } else {
+                // This should not be reachable.
+                throw Error(`unsupported winner ${winner}`);
+            }
+            winner = await getWinner();
+        }
+        this.loopRunning.resolve();
+    }
+
+    /**
+     * Run all pending requests, in queue order.
+     *
+     * Each request's completion promise resolves once that request
+     * finishes.
+     */
+    private async flush(): Promise<void> {
+        if (this.running !== undefined) {
+            // We must be flushing the queue already.
+            return;
+        }
+        // Run every request in the queue.
+        while (this.queue.length > 0) {
+            const reqID = this.queue[0];
+            this.running = reqID;
+            // We pop the request off the queue here so it doesn't show
+            // up as both running and pending.
+            this.queue.shift();
+            const [run, , notify] = this.requests[reqID];
+
+            await run();
+
+            // We leave the request until right before `notify()`
+            // for the sake of any calls to `getLastRequest()`.
+            delete this.requests[reqID];
+            notify();
+        }
+        this.running = undefined;
+    }
+
+    /**
+     * Provide the request ID to use next.
+     */
+    private getNextID(): RequestID {
+        // For now there is no way to queue up a request with
+        // an ID that did not originate here.  So we don't need
+        // to worry about collisions.
+        if (this.lastID === undefined) {
+            this.lastID = 1;
+        } else {
+            this.lastID += 1;
+        }
+        return this.lastID;
+    }
+}

src/client/pythonEnvironments/base/envsCache.ts

@@ -2,7 +2,6 @@
 // Licensed under the MIT License.
 
 import { cloneDeep } from 'lodash';
-import { getGlobalPersistentStore, IPersistentStore } from '../common/externalDependencies';
 import { PythonEnvInfo } from './info';
 import { areSameEnv } from './info/env';
 
@@ -13,7 +12,7 @@ export interface IEnvsCache {
     /**
      * Initialization logic to be done outside of the constructor, for example reading from persistent storage.
      */
-    initialize(): void;
+    initialize(): Promise<void>;
 
     /**
      * Return all environment info currently in memory for this session.
@@ -30,7 +29,7 @@ export interface IEnvsCache {
     setAllEnvs(envs: PythonEnvInfo[]): void;
 
     /**
-     * If the cache has been initialized, return environmnent info objects that match a query object.
+     * If the cache has been initialized, return environment info objects that match a query object.
      * If none of the environments in the cache match the query data, return an empty array.
      * If the in-memory cache has not been initialized prior to calling `filterEnvs`, return `undefined`.
      *
@@ -40,14 +39,19 @@ export interface IEnvsCache {
      * @return The environment info objects matching the `env` param,
      * or `undefined` if the in-memory cache is not initialized.
      */
-    filterEnvs(env: PythonEnvInfo | string): PythonEnvInfo[] | undefined;
+    filterEnvs(query: Partial<PythonEnvInfo>): PythonEnvInfo[] | undefined;
 
     /**
      * Writes the content of the in-memory cache to persistent storage.
      */
     flush(): Promise<void>;
 }
 
+export interface IPersistentStorage {
+    load(): Promise<PythonEnvInfo[] | undefined>;
+    store(envs: PythonEnvInfo[]): Promise<void>;
+}
+
 type CompleteEnvInfoFunction = (envInfo: PythonEnvInfo) => boolean;
 
 /**
@@ -58,18 +62,23 @@ export class PythonEnvInfoCache implements IEnvsCache {
 
     private envsList: PythonEnvInfo[] | undefined;
 
-    private persistentStorage: IPersistentStore<PythonEnvInfo[]> | undefined;
+    private persistentStorage: IPersistentStorage | undefined;
 
-    constructor(private readonly isComplete: CompleteEnvInfoFunction) {}
+    constructor(
+        private readonly isComplete: CompleteEnvInfoFunction,
+        private readonly getPersistentStorage?: () => IPersistentStorage,
+    ) {}
 
-    public initialize(): void {
+    public async initialize(): Promise<void> {
         if (this.initialized) {
             return;
         }
 
         this.initialized = true;
-        this.persistentStorage = getGlobalPersistentStore<PythonEnvInfo[]>('PYTHON_ENV_INFO_CACHE');
-        this.envsList = this.persistentStorage?.get();
+        if (this.getPersistentStorage !== undefined) {
+            this.persistentStorage = this.getPersistentStorage();
+            this.envsList = await this.persistentStorage.load();
+        }
     }
 
     public getAllEnvs(): PythonEnvInfo[] | undefined {
@@ -80,21 +89,19 @@ export class PythonEnvInfoCache implements IEnvsCache {
         this.envsList = cloneDeep(envs);
     }
 
-    public filterEnvs(env: PythonEnvInfo | string): PythonEnvInfo[] | undefined {
-        const result = this.envsList?.filter((info) => areSameEnv(info, env));
-
-        if (result) {
-            return cloneDeep(result);
+    public filterEnvs(query: Partial<PythonEnvInfo>): PythonEnvInfo[] | undefined {
+        if (this.envsList === undefined) {
+            return undefined;
         }
-
-        return undefined;
+        const result = this.envsList.filter((info) => areSameEnv(info, query));
+        return cloneDeep(result);
     }
 
     public async flush(): Promise<void> {
         const completeEnvs = this.envsList?.filter(this.isComplete);
 
         if (completeEnvs?.length) {
-            await this.persistentStorage?.set(completeEnvs);
+            await this.persistentStorage?.store(completeEnvs);
         }
     }
 }