Task Management - Handle Promises "Then" or "Catch" callback case.

chrome/browser/resources/google_now/utility.js

 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 'use strict';
 
 /**
  * @fileoverview Utility objects and functions for Google Now extension.
  * Most important entities here:
  * (1) 'wrapper' is a module used to add error handling and other services to
@@ skipping 201 matching lines @@
  * to the original callback provided by the extension.
  *
  * @typedef {{
  *   prologue: function (),
  *   epilogue: function ()
  * }}
  */
 var WrapperPlugin;
 
 /**
+ * Promise Metadata. Holds fields that are used in identifying a promise during
+ * task processing.
+ *
+ * @typedef {{
+ *     id: number,
+ *     isCatch: boolean
+ * }}
+ */
+var PromiseMetadata;
+
+/**
  * Wrapper for callbacks. Used to add error handling and other services to
  * callbacks for HTML and Chrome functions and events.
  */
 var wrapper = (function() {
   /**
    * Factory for wrapper plugins. If specified, it's used to generate an
    * instance of WrapperPlugin each time we wrap a callback (which corresponds
    * to addListener call for Chrome events, and to every API call that specifies
    * a callback). WrapperPlugin's lifetime ends when the callback for which it
    * was generated, exits. It's possible to have several instances of
    * WrapperPlugin at the same time.
    * An instance of WrapperPlugin can have state that can be shared by its
    * constructor, prologue() and epilogue(). Also WrapperPlugins can change
    * state of other objects, for example, to do refcounting.
-   * @type {?function(): WrapperPlugin}
+   * @type {?function(PromiseMetadata): WrapperPlugin}
    */
   var wrapperPluginFactory = null;
 
   /**
    * Registers a wrapper plugin factory.
-   * @param {function(): WrapperPlugin} factory Wrapper plugin factory.
+   * @param {function(PromiseMetadata): WrapperPlugin} factory
+   *     Wrapper plugin factory.
    */
   function registerWrapperPluginFactory(factory) {
     if (wrapperPluginFactory) {
       reportError(buildErrorWithMessageForServer(
           'registerWrapperPluginFactory: factory is already registered.'));
     }
 
     wrapperPluginFactory = factory;
   }
 
   /**
    * True if currently executed code runs in a callback or event handler that
    * was instrumented by wrapper.wrapCallback() call.
    * @type {boolean}
    */
   var isInWrappedCallback = false;
 
   /**
    * Required callbacks that are not yet called. Includes both task and non-task
    * callbacks. This is a map from unique callback id to the stack at the moment
    * when the callback was wrapped. This stack identifies the callback.
    * Used only for diagnostics.
    * @type {Object.<number, string>}
    */
   var pendingCallbacks = {};
 
   /**
+   * A map of promise IDs to an array of "then" callback IDs.
+   * @type {Object.<number, array.<number>>}
+   */
+  var pendingThenCallbacks = {};
+
+  /**
+   * A map of promise IDs to an array of "catch" callback IDs.
+   * @type {Object.<number, array.<number>>}
+   */
+  var pendingCatchCallbacks = {};
+
+  /**
    * Unique ID of the next callback.
    * @type {number}
    */
   var nextCallbackId = 0;
 
   /**
    * Gets diagnostic string with the status of the wrapper.
    * @return {string} Diagnostic string.
    */
   function debugGetStateString() {
     return 'pendingCallbacks @' + Date.now() + ' = ' +
         JSON.stringify(pendingCallbacks);
   }
 
   /**
    * Checks that we run in a wrapped callback.
    */
   function checkInWrappedCallback() {
     if (!isInWrappedCallback) {
       reportError(buildErrorWithMessageForServer(
           'Not in instrumented callback'));
     }
   }
 
   /**
    * Adds error processing to an API callback.
    * @param {Function} callback Callback to instrument.
    * @param {boolean=} opt_isEventListener True if the callback is a listener to
    *     a Chrome API event.
+   * @param {PromiseMetadata=} opt_promiseMetadata Set if wrapped from a
+   *     promise.
    * @return {Function} Instrumented callback.
    */
-  function wrapCallback(callback, opt_isEventListener) {
+  function wrapCallback(callback, opt_isEventListener, opt_promiseMetadata) {
     var callbackId = nextCallbackId++;
 
     if (!opt_isEventListener) {
       checkInWrappedCallback();
       pendingCallbacks[callbackId] = new Error().stack + ' @' + Date.now();
+      if (opt_promiseMetadata) {
+        var callbackIdMap = opt_promiseMetadata.isCatch ?
+            pendingCatchCallbacks :
+            pendingThenCallbacks;
+        callbackIdMap[opt_promiseMetadata.id] =
+            callbackIdMap[opt_promiseMetadata.id] || [];
+        callbackIdMap[opt_promiseMetadata.id].push(callbackId);
+      }
     }
-
     // wrapperPluginFactory may be null before task manager is built, and in
     // tests.
-    var wrapperPluginInstance = wrapperPluginFactory && wrapperPluginFactory();
+    var wrapperPluginInstance =
+        wrapperPluginFactory && wrapperPluginFactory(opt_promiseMetadata);
 
     return function() {
       // This is the wrapper for the callback.
       try {
         verify(!isInWrappedCallback, 'Re-entering instrumented callback');
         isInWrappedCallback = true;
 
-        if (!opt_isEventListener)
+        if (!opt_isEventListener) {
           delete pendingCallbacks[callbackId];
+          if (opt_promiseMetadata) {
+            var callbackIdsToRemove = opt_promiseMetadata.isCatch ?
+                pendingThenCallbacks[opt_promiseMetadata.id] :
+                pendingCatchCallbacks[opt_promiseMetadata.id];
+            if (callbackIdsToRemove !== undefined) {
+              callbackIdsToRemove.forEach(function(idToRemove) {
+                delete pendingCallbacks[idToRemove];
+              });
+            }
+          }
+        }
 
         if (wrapperPluginInstance)
           wrapperPluginInstance.prologue();
 
         // Call the original callback.
         callback.apply(null, arguments);
 
         if (wrapperPluginInstance)
           wrapperPluginInstance.epilogue();
 
@@ skipping 99 matching lines @@
 })();
 
 wrapper.instrumentChromeApiFunction('alarms.get', 1);
 wrapper.instrumentChromeApiFunction('alarms.onAlarm.addListener', 0);
 wrapper.instrumentChromeApiFunction('identity.getAuthToken', 1);
 wrapper.instrumentChromeApiFunction('identity.onSignInChanged.addListener', 0);
 wrapper.instrumentChromeApiFunction('identity.removeCachedAuthToken', 1);
 wrapper.instrumentChromeApiFunction('webstorePrivate.getBrowserLogin', 0);
 
 /**
+ * Unique ID of the next promise.
+ * @type {number}
+ */
+var nextPromiseId = 0;
+
+/**
  * Add task tracking support to Promise.then.
  * @override
  */
 Promise.prototype.then = function() {
   var originalThen = Promise.prototype.then;
   return function(callback) {
-    return originalThen.call(this, wrapper.wrapCallback(callback, false));
+    var promiseId = this.__promiseId;
+    if (promiseId === undefined) {
+      promiseId = nextPromiseId;
+      nextPromiseId++;
+    }
+    // "then" may return a new promise, getting rid of the ID!
+    // Set it before and after the call to keep the value.
+    this.__promiseId = promiseId;

[rgustafson, 2014/02/24 21:55:12]

Still kinda confused in general by setting the same id to the promise calling
then and the one resulting from then. Really we're tracking promise chains and
not individual promises, right? Chained thens would all end up with the same id?
Want to make sure I know what's going on here.

In this case, can't multiple thens succeed and then one fail and catch is called
which contradicts what is said farther down in the file about whenever then is
called, catch isn't?

[robliao, 2014/02/24 22:31:13]

You're right in the general case (and we'll need to handle this later once we
get promise chaining fully working).

In our specific case, our thens do not return promises.

This means that either all thens or all catches will execute.

Once our thens accept promises, then it is possible to have a varying number of
thens and catches in a single chain get called.

On 2014/02/24 21:55:12, rgustafson wrote:

[robliao, 2014/02/24 23:11:56]

Added a comment about this limitation.
On 2014/02/24 22:31:13, robliao wrote:

+    var promise = originalThen.call(
+        this, wrapper.wrapCallback(callback, false,
+            {id: this.__promiseId, isCatch: false}));
+    promise.__promiseId = promiseId;
+    return promise;
   }
 }();
 
 /**
  * Add task tracking support to Promise.catch.
  * @override
  */
 Promise.prototype.catch = function() {
   var originalCatch = Promise.prototype.catch;
   return function(callback) {
-    return originalCatch.call(this, wrapper.wrapCallback(callback, false));
+    var promiseId = this.__promiseId;
+    if (promiseId === undefined) {
+      promiseId = nextPromiseId;
+      nextPromiseId++;
+    }
+    // "catch" may return a new promise, getting rid of the ID!
+    // Set it before and after the call to keep the value.
+    this.__promiseId = promiseId;
+    var promise = originalCatch.call(
+        this, wrapper.wrapCallback(callback, false,
+            {id: this.__promiseId, isCatch: true}));
+    promise.__promiseId = promiseId;
+    return promise;
   }
 }();
 
 /**
+ * Promise Pending Callback Data. Counts outstanding "then" and "catch"
+ * callbacks;
+ *
+ * @typedef {{
+ *     thenCount: number,
+ *     catchCount: number
+ * }}
+ */
+var PromisePendingCallbackData;
+
+/**
  * Builds the object to manage tasks (mutually exclusive chains of events).
  * @param {function(string, string): boolean} areConflicting Function that
  *     checks if a new task can't be added to a task queue that contains an
  *     existing task.
  * @return {Object} Task manager interface.
  */
 function buildTaskManager(areConflicting) {
   /**
    * Queue of scheduled tasks. The first element, if present, corresponds to the
    * currently running task.
    * @type {Array.<Object.<string, function()>>}
    */
   var queue = [];
 
   /**
    * Count of unfinished callbacks of the current task.
    * @type {number}
    */
   var taskPendingCallbackCount = 0;
 
   /**
+   * Map of Promise ID to PromisePendingCallbackData to count the number of
+   * outstanding "then" and "catch" callbacks.
+   * @type {object.<number, PromisePendingCallbackData>}
+   */
+  var taskPromisePendingCallbackData = {};
+
+  /**
    * True if currently executed code is a part of a task.
    * @type {boolean}
    */
   var isInTask = false;
 
   /**
    * Starts the first queued task.
    */
   function startFirst() {
     verify(queue.length >= 1, 'startFirst: queue is empty');
@@ skipping 73 matching lines @@
         queue.length == 0,
         'Incomplete task when unloading event page,' +
         ' queue = ' + JSON.stringify(queue) + ', ' +
         wrapper.debugGetStateString());
   });
 
 
   /**
    * Wrapper plugin for tasks.
    * @constructor
+   * @param {PromiseMetadata=} opt_promiseMetadata Set if wrapped from a
+   *     promise.
    */
-  function TasksWrapperPlugin() {
+  function TasksWrapperPlugin(opt_promiseMetadata) {
     this.isTaskCallback = isInTask;
-    if (this.isTaskCallback)
+    if (this.isTaskCallback) {
       ++taskPendingCallbackCount;
+      if (opt_promiseMetadata !== undefined) {
+        this.promiseId = opt_promiseMetadata.id;
+        if (!taskPromisePendingCallbackData[this.promiseId]) {
+          taskPromisePendingCallbackData[this.promiseId] =
+              {thenCount: 0, catchCount: 0};
+        }
+        if (opt_promiseMetadata.isCatch) {
+          taskPromisePendingCallbackData[this.promiseId].catchCount++;
+          this.isCatch = true;
+        } else {
+          taskPromisePendingCallbackData[this.promiseId].thenCount++;
+          this.isCatch = false;
+        }
+      }
+    }
   }
 
   TasksWrapperPlugin.prototype = {
     /**
      * Plugin code to be executed before invoking the original callback.
      */
     prologue: function() {
       if (this.isTaskCallback) {
         verify(!isInTask, 'TasksWrapperPlugin.prologue: already in task');
         isInTask = true;
       }
     },
 
     /**
      * Plugin code to be executed after invoking the original callback.
      */
     epilogue: function() {
       if (this.isTaskCallback) {
         verify(isInTask, 'TasksWrapperPlugin.epilogue: not in task at exit');
         isInTask = false;
+        if (this.promiseId !== undefined) {
+          // Finishing up a promise callback. If a "then" calls back, then
+          // all "catch" callbacks will not call back and vice versa.
+          // Subtract the callbacks that will not call back.
+          if (this.isCatch) {
+            taskPendingCallbackCount -=
+                taskPromisePendingCallbackData[this.promiseId].thenCount;
+            taskPromisePendingCallbackData[this.promiseId].thenCount = 0;
+          } else {
+            taskPendingCallbackCount -=
+                taskPromisePendingCallbackData[this.promiseId].catchCount;
+            taskPromisePendingCallbackData[this.promiseId].catchCount = 0;
+          }
+        }
         if (--taskPendingCallbackCount == 0)
           finish();
       }
     }
   };
 
-  wrapper.registerWrapperPluginFactory(function() {
-    return new TasksWrapperPlugin();
-  });
+  wrapper.registerWrapperPluginFactory(
+      function(opt_promiseMetadata) {
+        return new TasksWrapperPlugin(opt_promiseMetadata);
+      });
 
   return {
     add: add
   };
 }
 
 /**
  * Builds an object to manage retrying activities with exponential backoff.
  * @param {string} name Name of this attempt manager.
  * @param {function()} attempt Activity that the manager retries until it
@@ skipping 203 matching lines @@
   // One hour is just an arbitrary amount of time chosen.
   chrome.alarms.create(alarmName, {periodInMinutes: 60});
 
   return {
     addListener: addListener,
     getAuthToken: getAuthToken,
     isSignedIn: isSignedIn,
     removeToken: removeToken
   };
 }