Add a basic implementation of CachingLocator.

Author: ericsnowcurrently

src/client/pythonEnvironments/collection/cachingLocator.ts

@@ -0,0 +1,180 @@
+// 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,
+    PythonEnvUpdatedEvent,
+    PythonLocatorQuery,
+} from '../base/locator';
+import { PythonEnvsWatcher } from '../base/watcher';
+
+type PythonEnvID = string;
+
+function getEnvID(env: PythonEnvInfo | string): PythonEnvID {
+    if (typeof env === 'string') {
+        return env;
+    }
+    return env.executable.filename;
+}
+
+function isSameEnv(env1: PythonEnvInfo, env2: PythonEnvInfo): boolean {
+    return getEnvID(env1) === getEnvID(env2);
+}
+
+function getQueryFilter(query: PythonLocatorQuery): (env: PythonEnvInfo) => boolean {
+    return (env) => {
+        if (query.kinds !== undefined) {
+            if (!query.kinds.includes(env.kind)) {
+                return false;
+            }
+        }
+        if (query.searchLocations !== undefined) {
+            if (env.searchLocation !== undefined) {
+                // XXX Are URLs comparable like this?
+                if (!query.searchLocations.includes(env.searchLocation)) {
+                    return false;
+                }
+            }
+        }
+        return true;
+    };
+}
+
+async function getEnvs(iterator: IPythonEnvsIterator): Promise<PythonEnvInfo[]> {
+    const envs: PythonEnvInfo[] = [];
+
+    const updatesDone = createDeferred<void>();
+    if (iterator.onUpdated === undefined) {
+        updatesDone.resolve();
+    } else {
+        iterator.onUpdated((event: PythonEnvUpdatedEvent | null) => {
+            if (event === null) {
+                updatesDone.resolve();
+                return;
+            }
+            const oldEnv = envs.find((e) => isSameEnv(e, event.old));
+            if (oldEnv === undefined) {
+                // XXX log or fail
+            } else {
+                envs[envs.indexOf(oldEnv)] = event.new;
+            }
+        });
+    }
+
+    let result = await iterator.next();
+    while (!result.done) {
+        envs.push(result.value);
+        // eslint-disable-next-line no-await-in-loop
+        result = await iterator.next();
+    }
+
+    await updatesDone.promise;
+    return envs;
+}
+
+interface IEnvsCache {
+    initialize(): Promise<void>;
+    listAll(): Promise<PythonEnvInfo[] | undefined>;
+    getEnv(id: PythonEnvID): 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 envID = getEnvID(env);
+        const cached = await this.cache.getEnv(envID);
+        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.
+    }
+}