Add a basic implementation of CachingLocator.

Author: ericsnowcurrently

src/client/pythonEnvironments/collection/cachingLocator.ts

@@ -0,0 +1,118 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import '../../common/extensions';
+import { createDeferred } from '../../common/utils/async';
+import { PythonEnvInfo } from '../base/info';
+import {
+    ILocator,
+    IPythonEnvsIterator,
+    PythonLocatorQuery,
+} from '../base/locator';
+import { getEnvs, getQueryFilter } from '../base/locatorUtils';
+import { PythonEnvsWatcher } from '../base/watcher';
+
+interface IEnvsCache {
+    initialize(): Promise<void>;
+    listAll(): Promise<PythonEnvInfo[] | undefined>;
+    getEnv(env: Partial<PythonEnvInfo>): Promise<PythonEnvInfo | undefined>;
+    setAll(envs: PythonEnvInfo[]): Promise<void>;
+    flush(): Promise<void>;
+}
+
+export class CachingLocator extends PythonEnvsWatcher implements ILocator {
+    private readonly initializing = createDeferred<void>();
+
+    constructor(
+        private readonly cache: IEnvsCache,
+        private readonly locator: ILocator,
+    ) {
+        super();
+        locator.onChanged((event) => {
+            this.refresh()
+                .then(() => this.fire(event))
+                .ignoreErrors();
+        });
+    }
+
+    public async initialize(): Promise<void> {
+        await this.cache.initialize();
+        const envs = await this.cache.listAll();
+        if (envs !== undefined) {
+            this.initializing.resolve();
+            await this.refresh();
+        } else {
+            // There is nothing in the cache, so we must wait for the
+            // initial refresh to finish before allowing iteration.
+            await this.refresh();
+            this.initializing.resolve();
+        }
+    }
+
+    public iterEnvs(query?: PythonLocatorQuery): IPythonEnvsIterator {
+        return this.iterFromCache(query);
+    }
+
+    public async resolveEnv(env: string | PythonEnvInfo): Promise<PythonEnvInfo | undefined> {
+        // If necessary we could be more aggressive about invalidating
+        // the cached value.
+        const envForKey = typeof env === 'string'
+            ? { executable: { filename: env, sysPrefix: '', ctime: -1, mtime: -1 }}
+            : env;
+        const cached = await this.cache.getEnv(envForKey);
+        if (cached !== undefined) {
+            return cached;
+        }
+        // Fall back to the underlying locator.
+        const envs = await this.cache.listAll();
+        const resolved = await this.locator.resolveEnv(env);
+        if (resolved !== undefined) {
+            envs!.push(resolved);
+            await this.update(envs!);
+        }
+        return resolved;
+    }
+
+    private async* iterFromCache(query?: PythonLocatorQuery): IPythonEnvsIterator {
+        // XXX For now we wait for the initial refresh to finish...
+        await this.initializing.promise;
+
+        const envs = await this.cache.listAll();
+        if (envs === undefined) {
+            throw Error('this should be unreachable');
+        }
+        if (await this.needsRefresh(envs)) {
+            // Refresh in the background.
+            this.refresh().ignoreErrors();
+        }
+        if (query !== undefined) {
+            const filter = getQueryFilter(query);
+            yield* envs.filter(filter);
+        } else {
+            yield* envs;
+        }
+    }
+
+    // eslint-disable-next-line class-methods-use-this,@typescript-eslint/no-unused-vars
+    private async needsRefresh(_envs: PythonEnvInfo[]): Promise<boolean> {
+        // XXX
+        // For now we never refresh.  Options:
+        // * every X minutes (via `initialize()`
+        // * if at least X minutes have elapsed
+        // * if some "stale" check on any known env fails
+        return false;
+    }
+
+    private async refresh(): Promise<void> {
+        const iterator = this.locator.iterEnvs();
+        const envs = await getEnvs(iterator);
+        await this.update(envs);
+    }
+
+    private async update(envs: PythonEnvInfo[]): Promise<void> {
+        // If necessary, we could skip if there are no changes.
+        await this.cache.setAll(envs);
+        await this.cache.flush();
+        this.fire({}); // Emit an "onCHanged" event.
+    }
+}