Rename withTimeout() to waitForResultWithTimeLimit()

The name withTimeout() gives the impression that it would limit the
execution of the promise to the given time bound. But that is not the
case: it is only the _waiting_ that is limited, and the promise would
keep running beyond the time bound.

This commit renames withTimeout() to waitForResultWithTimeLimit() so
that developers are more likely to understand the actual behavior of
this function.

Author: cklin

lib/analyze-action.js

@@ -10,7 +10,11 @@ import { type CodeQL } from "./codeql";
 import { type Config } from "./config-utils";
 import { getCommitOid, getFileOidsUnderPath } from "./git-utils";
 import { Logger, withGroupAsync } from "./logging";
-import { isInTestMode, tryGetFolderBytes, withTimeout } from "./util";
+import {
+  isInTestMode,
+  tryGetFolderBytes,
+  waitForResultWithTimeLimit,
+} from "./util";
 
 export enum OverlayDatabaseMode {
   Overlay = "overlay",
@@ -268,7 +272,7 @@ export async function uploadOverlayBaseDatabaseToCache(
   );
 
   try {
-    const cacheId = await withTimeout(
+    const cacheId = await waitForResultWithTimeLimit(
       MAX_CACHE_OPERATION_MS,
       actionsCache.saveCache([dbLocation], cacheSaveKey),
       () => {},
@@ -346,7 +350,7 @@ export async function downloadOverlayBaseDatabaseFromCache(
   let databaseDownloadDurationMs = 0;
   try {
     const databaseDownloadStart = performance.now();
-    const foundKey = await withTimeout(
+    const foundKey = await waitForResultWithTimeLimit(
       MAX_CACHE_OPERATION_MS,
       actionsCache.restoreCache([dbLocation], cacheRestoreKeyPrefix),
       () => {

lib/init-action.js

@@ -16,7 +16,7 @@ import {
   getErrorMessage,
   isHTTPError,
   tryGetFolderBytes,
-  withTimeout,
+  waitForResultWithTimeLimit,
 } from "./util";
 
 // This constant should be bumped if we make a breaking change
@@ -96,7 +96,7 @@ export async function downloadTrapCaches(
     logger.info(
       `Looking in Actions cache for TRAP cache with key ${preferredKey}`,
     );
-    const found = await withTimeout(
+    const found = await waitForResultWithTimeLimit(
       MAX_CACHE_OPERATION_MS,
       actionsCache.restoreCache([cacheDir], preferredKey, [
         // Fall back to any cache with the right key prefix
@@ -156,7 +156,7 @@ export async function uploadTrapCaches(
       process.env.GITHUB_SHA || "unknown",
     );
     logger.info(`Uploading TRAP cache to Actions cache with key ${key}`);
-    await withTimeout(
+    await waitForResultWithTimeLimit(
       MAX_CACHE_OPERATION_MS,
       actionsCache.saveCache([cacheDir], key),
       () => {

src/overlay-database-utils.ts

@@ -297,43 +297,51 @@ test("listFolder", async (t) => {
 const longTime = 999_999;
 const shortTime = 10;
 
-test("withTimeout on long task", async (t) => {
+test("waitForResultWithTimeLimit on long task", async (t) => {
   let longTaskTimedOut = false;
   const longTask = new Promise((resolve) => {
     const timer = setTimeout(() => {
       resolve(42);
     }, longTime);
     t.teardown(() => clearTimeout(timer));
   });
-  const result = await util.withTimeout(shortTime, longTask, () => {
-    longTaskTimedOut = true;
-  });
+  const result = await util.waitForResultWithTimeLimit(
+    shortTime,
+    longTask,
+    () => {
+      longTaskTimedOut = true;
+    },
+  );
   t.deepEqual(longTaskTimedOut, true);
   t.deepEqual(result, undefined);
 });
 
-test("withTimeout on short task", async (t) => {
+test("waitForResultWithTimeLimit on short task", async (t) => {
   let shortTaskTimedOut = false;
   const shortTask = new Promise((resolve) => {
     setTimeout(() => {
       resolve(99);
     }, shortTime);
   });
-  const result = await util.withTimeout(longTime, shortTask, () => {
-    shortTaskTimedOut = true;
-  });
+  const result = await util.waitForResultWithTimeLimit(
+    longTime,
+    shortTask,
+    () => {
+      shortTaskTimedOut = true;
+    },
+  );
   t.deepEqual(shortTaskTimedOut, false);
   t.deepEqual(result, 99);
 });
 
-test("withTimeout doesn't call callback if promise resolves", async (t) => {
+test("waitForResultWithTimeLimit doesn't call callback if promise resolves", async (t) => {
   let shortTaskTimedOut = false;
   const shortTask = new Promise((resolve) => {
     setTimeout(() => {
       resolve(99);
     }, shortTime);
   });
-  const result = await util.withTimeout(100, shortTask, () => {
+  const result = await util.waitForResultWithTimeLimit(100, shortTask, () => {
     shortTaskTimedOut = true;
   });
   await new Promise((r) => setTimeout(r, 200));

src/trap-caching.ts

@@ -864,7 +864,7 @@ let hadTimeout = false;
  * @param onTimeout A callback to call if the promise times out.
  * @returns The result of the promise, or undefined if the promise times out.
  */
-export async function withTimeout<T>(
+export async function waitForResultWithTimeLimit<T>(
   timeoutMs: number,
   promise: Promise<T>,
   onTimeout: () => void,
@@ -894,7 +894,7 @@ export async function withTimeout<T>(
  * Check if the global hadTimeout variable has been set, and if so then
  * exit the process to ensure any background tasks that are still running
  * are killed. This should be called at the end of execution if the
- * `withTimeout` function has been used.
+ * `waitForResultWithTimeLimit` function has been used.
  */
 export async function checkForTimeout() {
   if (hadTimeout === true) {