The Tor Browser: toolkit/modules/AsyncShutdown.jsm@6474c204b198 (annotated)

toolkit/modules/AsyncShutdown.jsm@6474c204b198 (annotated)

toolkit/modules/AsyncShutdown.jsm

Wed, 31 Dec 2014 06:09:35 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Wed, 31 Dec 2014 06:09:35 +0100
changeset 0: 6474c204b198
permissions: -rw-r--r--

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

 /* This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
  * You can obtain one at http://mozilla.org/MPL/2.0/. */
 /**
  * Managing safe shutdown of asynchronous services.
  *
  * Firefox shutdown is composed of phases that take place
  * sequentially. Typically, each shutdown phase removes some
  * capabilities from the application. For instance, at the end of
  * phase profileBeforeChange, no service is permitted to write to the
  * profile directory (with the exception of Telemetry). Consequently,
  * if any service has requested I/O to the profile directory before or
  * during phase profileBeforeChange, the system must be informed that
  * these requests need to be completed before the end of phase
  * profileBeforeChange. Failing to inform the system of this
  * requirement can (and has been known to) cause data loss.
  *
  * Example: At some point during shutdown, the Add-On Manager needs to
  * ensure that all add-ons have safely written their data to disk,
  * before writing its own data. Since the data is saved to the
  * profile, this must be completed during phase profileBeforeChange.
  *
  * AsyncShutdown.profileBeforeChange.addBlocker(
  *   "Add-on manager: shutting down",
  *   function condition() {
  *     // Do things.
  *     // Perform I/O that must take place during phase profile-before-change
  *     return promise;
  *   }
  * });
  *
  * In this example, function |condition| will be called at some point
  * during phase profileBeforeChange and phase profileBeforeChange
  * itself is guaranteed to not terminate until |promise| is either
  * resolved or rejected.
  */
 "use strict";
 const Cu = Components.utils;
 const Cc = Components.classes;
 const Ci = Components.interfaces;
 Cu.import("resource://gre/modules/XPCOMUtils.jsm", this);
 Cu.import("resource://gre/modules/Services.jsm", this);
 XPCOMUtils.defineLazyModuleGetter(this, "Promise",
   "resource://gre/modules/Promise.jsm");
 XPCOMUtils.defineLazyServiceGetter(this, "gDebug",
   "@mozilla.org/xpcom/debug;1", "nsIDebug");
 Object.defineProperty(this, "gCrashReporter", {
   get: function() {
     delete this.gCrashReporter;
     try {
       let reporter = Cc["@mozilla.org/xre/app-info;1"].
             getService(Ci.nsICrashReporter);
       return this.gCrashReporter = reporter;
     } catch (ex) {
       return this.gCrashReporter = null;
     }
   },
   configurable: true
 });
 // Display timeout warnings after 10 seconds
 const DELAY_WARNING_MS = 10 * 1000;
 // Crash the process if shutdown is really too long
 // (allowing for sleep).
 const PREF_DELAY_CRASH_MS = "toolkit.asyncshutdown.crash_timeout";
 let DELAY_CRASH_MS = 60 * 1000; // One minute
 try {
   DELAY_CRASH_MS = Services.prefs.getIntPref(PREF_DELAY_CRASH_MS);
 } catch (ex) {
   // Ignore errors
 }
 Services.prefs.addObserver(PREF_DELAY_CRASH_MS, function() {
   DELAY_CRASH_MS = Services.prefs.getIntPref(PREF_DELAY_CRASH_MS);
 }, false);
 /**
  * Display a warning.
  *
  * As this code is generally used during shutdown, there are chances
  * that the UX will not be available to display warnings on the
  * console. We therefore use dump() rather than Cu.reportError().
  */
 function log(msg, prefix = "", error = null) {
   dump(prefix + msg + "\n");
   if (error) {
     dump(prefix + error + "\n");
     if (typeof error == "object" && "stack" in error) {
       dump(prefix + error.stack + "\n");
     }
   }
 }
 function warn(msg, error = null) {
   return log(msg, "WARNING: ", error);
 }
 function err(msg, error = null) {
   return log(msg, "ERROR: ", error);
 }
 // Utility function designed to get the current state of execution
 // of a blocker.
 // We are a little paranoid here to ensure that in case of evaluation
 // error we do not block the AsyncShutdown.
 function safeGetState(state) {
   if (!state) {
     return "(none)";
   }
   let data, string;
   try {
     // Evaluate state(), normalize the result into something that we can
     // safely stringify or upload.
     string = JSON.stringify(state());
     data = JSON.parse(string);
     // Simplify the rest of the code by ensuring that we can simply
     // concatenate the result to a message.
     if (data && typeof data == "object") {
       data.toString = function() {
         return string;
       };
     }
     return data;
   } catch (ex) {
     if (string) {
       return string;
     }
     try {
       return "Error getting state: " + ex + " at " + ex.stack;
     } catch (ex2) {
       return "Error getting state but could not display error";
     }
   }
 }
 /**
  * Countdown for a given duration, skipping beats if the computer is too busy,
  * sleeping or otherwise unavailable.
  *
  * @param {number} delay An approximate delay to wait in milliseconds (rounded
  * up to the closest second).
  *
  * @return Deferred
  */
 function looseTimer(delay) {
   let DELAY_BEAT = 1000;
   let timer = Cc["@mozilla.org/timer;1"].createInstance(Ci.nsITimer);
   let beats = Math.ceil(delay / DELAY_BEAT);
   let deferred = Promise.defer();
   timer.initWithCallback(function() {
     if (beats <= 0) {
       deferred.resolve();
     }
     --beats;
   }, DELAY_BEAT, Ci.nsITimer.TYPE_REPEATING_PRECISE_CAN_SKIP);
   // Ensure that the timer is both canceled once we are done with it
   // and not garbage-collected until then.
   deferred.promise.then(() => timer.cancel(), () => timer.cancel());
   return deferred;
 }
 this.EXPORTED_SYMBOLS = ["AsyncShutdown"];
 /**
  * {string} topic -> phase
  */
 let gPhases = new Map();
 this.AsyncShutdown = {
   /**
    * Access function getPhase. For testing purposes only.
    */
   get _getPhase() {
     let accepted = false;
     try {
       accepted = Services.prefs.getBoolPref("toolkit.asyncshutdown.testing");
     } catch (ex) {
       // Ignore errors
     }
     if (accepted) {
       return getPhase;
     }
     return undefined;
   }
 };
 /**
  * Register a new phase.
  *
  * @param {string} topic The notification topic for this Phase.
  * @see {https://developer.mozilla.org/en-US/docs/Observer_Notifications}
  */
 function getPhase(topic) {
   let phase = gPhases.get(topic);
   if (phase) {
     return phase;
   }
   let spinner = new Spinner(topic);
   phase = Object.freeze({
     /**
      * Register a blocker for the completion of a phase.
      *
      * @param {string} name The human-readable name of the blocker. Used
      * for debugging/error reporting. Please make sure that the name
      * respects the following model: "Some Service: some action in progress" -
      * for instance "OS.File: flushing all pending I/O";
      * @param {function|promise|*} condition A condition blocking the
      * completion of the phase. Generally, this is a function
      * returning a promise. This function is evaluated during the
      * phase and the phase is guaranteed to not terminate until the
      * resulting promise is either resolved or rejected. If
      * |condition| is not a function but another value |v|, it behaves
      * as if it were a function returning |v|.
      * @param {function*} state Optionally, a function returning
      * information about the current state of the blocker as an
      * object. Used for providing more details when logging errors or
      * crashing.
      *
      * Examples:
      * AsyncShutdown.profileBeforeChange.addBlocker("Module: just a promise",
      *      promise); // profileBeforeChange will not complete until
      *                // promise is resolved or rejected
      *
      * AsyncShutdown.profileBeforeChange.addBlocker("Module: a callback",
      *     function callback() {
      *       // ...
      *       // Execute this code during profileBeforeChange
      *       return promise;
      *       // profileBeforeChange will not complete until promise
      *       // is resolved or rejected
      * });
      *
      * AsyncShutdown.profileBeforeChange.addBlocker("Module: trivial callback",
      *     function callback() {
      *       // ...
      *       // Execute this code during profileBeforeChange
      *       // No specific guarantee about completion of profileBeforeChange
      * });
      *
      */
     addBlocker: function(name, condition, state = null) {
       if (typeof name != "string") {
         throw new TypeError("Expected a human-readable name as first argument");
       }
       if (state && typeof state != "function") {
         throw new TypeError("Expected nothing or a function as third argument");
       }
       spinner.addBlocker({name: name, condition: condition, state: state});
     }
   });
   gPhases.set(topic, phase);
   return phase;
 }
 /**
  * Utility class used to spin the event loop until all blockers for a
  * Phase are satisfied.
  *
  * @param {string} topic The xpcom notification for that phase.
  */
 function Spinner(topic) {
   this._topic = topic;
   this._conditions = new Set(); // set to |null| once it is too late to register
   Services.obs.addObserver(this, topic, false);
 }
 Spinner.prototype = {
   /**
    * Register a new condition for this phase.
    *
    * @param {object} condition A Condition that must be fulfilled before
    * we complete this Phase.
    * Must contain fields:
    * - {string} name The human-readable name of the condition. Used
    * for debugging/error reporting.
    * - {function} action An action that needs to be completed
    * before we proceed to the next runstate. If |action| returns a promise,
    * we wait until the promise is resolved/rejected before proceeding
    * to the next runstate.
    */
   addBlocker: function(condition) {
     if (!this._conditions) {
       throw new Error("Phase " + this._topic +
                       " has already begun, it is too late to register" +
                       " completion condition '" + condition.name + "'.");
     }
     this._conditions.add(condition);
   },
   observe: function() {
     let topic = this._topic;
     Services.obs.removeObserver(this, topic);
     let conditions = this._conditions;
     this._conditions = null; // Too late to register
     if (conditions.size == 0) {
       // No need to spin anything
       return;
     }
     // The promises for which we are waiting.
     let allPromises = [];
     // Information to determine and report to the user which conditions
     // are not satisfied yet.
     let allMonitors = [];
     for (let {condition, name, state} of conditions) {
       // Gather all completion conditions
       try {
         if (typeof condition == "function") {
           // Normalize |condition| to the result of the function.
           try {
             condition = condition(topic);
           } catch (ex) {
             condition = Promise.reject(ex);
           }
         }
         // Normalize to a promise. Of course, if |condition| was not a
         // promise in the first place (in particular if the above
         // function returned |undefined| or failed), that new promise
         // isn't going to be terribly interesting, but it will behave
         // as a promise.
         condition = Promise.resolve(condition);
         // If the promise takes too long to be resolved/rejected,
         // we need to notify the user.
         //
         // If it takes way too long, we need to crash.
         let timer = Cc["@mozilla.org/timer;1"].createInstance(Ci.nsITimer);
         timer.initWithCallback(function() {
           let msg = "A phase completion condition is" +
             " taking too long to complete." +
             " Condition: " + monitor.name +
             " Phase: " + topic +
             " State: " + safeGetState(state);
           warn(msg);
         }, DELAY_WARNING_MS, Ci.nsITimer.TYPE_ONE_SHOT);
         let monitor = {
           isFrozen: true,
           name: name,
           state: state
         };
         condition = condition.then(function onSuccess() {
             timer.cancel(); // As a side-effect, this prevents |timer| from
                             // being garbage-collected too early.
             monitor.isFrozen = false;
           }, function onError(error) {
             timer.cancel();
             let msg = "A completion condition encountered an error" +
                 " while we were spinning the event loop." +
                 " Condition: " + name +
                 " Phase: " + topic +
                 " State: " + safeGetState(state);
             warn(msg, error);
             monitor.isFrozen = false;
         });
         allMonitors.push(monitor);
         allPromises.push(condition);
       } catch (error) {
           let msg = "A completion condition encountered an error" +
                 " while we were initializing the phase." +
                 " Condition: " + name +
                 " Phase: " + topic +
                 " State: " + safeGetState(state);
           warn(msg, error);
       }
     }
     conditions = null;
     let promise = Promise.all(allPromises);
     allPromises = null;
     promise = promise.then(null, function onError(error) {
       // I don't think that this can happen.
       // However, let's be overcautious with async/shutdown error reporting.
       let msg = "An uncaught error appeared while completing the phase." +
             " Phase: " + topic;
       warn(msg, error);
     });
     let satisfied = false; // |true| once we have satisfied all conditions
     // If after DELAY_CRASH_MS (approximately one minute, adjusted to take
     // into account sleep and otherwise busy computer) we have not finished
     // this shutdown phase, we assume that the shutdown is somehow frozen,
     // presumably deadlocked. At this stage, the only thing we can do to
     // avoid leaving the user's computer in an unstable (and battery-sucking)
     // situation is report the issue and crash.
     let timeToCrash = looseTimer(DELAY_CRASH_MS);
     timeToCrash.promise.then(
       function onTimeout() {
         // Report the problem as best as we can, then crash.
         let frozen = [];
         let states = [];
         for (let {name, isFrozen, state} of allMonitors) {
           if (isFrozen) {
             frozen.push({name: name, state: safeGetState(state)});
           }
         }
         let msg = "At least one completion condition failed to complete" +
               " within a reasonable amount of time. Causing a crash to" +
               " ensure that we do not leave the user with an unresponsive" +
               " process draining resources." +
               " Conditions: " + JSON.stringify(frozen) +
               " Phase: " + topic;
         err(msg);
         if (gCrashReporter && gCrashReporter.enabled) {
           let data = {
             phase: topic,
             conditions: frozen
           };
           gCrashReporter.annotateCrashReport("AsyncShutdownTimeout",
             JSON.stringify(data));
         } else {
           warn("No crash reporter available");
         }
         let error = new Error();
         gDebug.abort(error.fileName, error.lineNumber + 1);
       },
       function onSatisfied() {
         // The promise has been rejected, which means that we have satisfied
         // all completion conditions.
       });
     promise = promise.then(function() {
       satisfied = true;
       timeToCrash.reject();
     }/* No error is possible here*/);
     // Now, spin the event loop
     let thread = Services.tm.mainThread;
     while(!satisfied) {
       thread.processNextEvent(true);
     }
   }
 };
 // List of well-known runstates
 // Ideally, runstates should be registered from the component that decides
 // when they start/stop. For compatibility with existing startup/shutdown
 // mechanisms, we register a few runstates here.
 this.AsyncShutdown.profileChangeTeardown = getPhase("profile-change-teardown");
 this.AsyncShutdown.profileBeforeChange = getPhase("profile-before-change");
 this.AsyncShutdown.sendTelemetry = getPhase("profile-before-change2");
 this.AsyncShutdown.webWorkersShutdown = getPhase("web-workers-shutdown");
 Object.freeze(this.AsyncShutdown);

The Tor Browser / annotate

toolkit/modules/AsyncShutdown.jsm@6474c204b198 (annotated)

toolkit/modules/AsyncShutdown.jsm