The Tor Browser: services/common/async.js@b8a032363ba2 (annotated)

services/common/async.js@b8a032363ba2 (annotated)

services/common/async.js

Thu, 22 Jan 2015 13:21:57 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Thu, 22 Jan 2015 13:21:57 +0100
branch: TOR_BUG_9701
changeset 15: b8a032363ba2
permissions: -rw-r--r--

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

 /* 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/. */
 #ifndef MERGED_COMPARTMENT
 this.EXPORTED_SYMBOLS = ["Async"];
 const {classes: Cc, interfaces: Ci, results: Cr, utils: Cu} = Components;
 #endif
 // Constants for makeSyncCallback, waitForSyncCallback.
 const CB_READY = {};
 const CB_COMPLETE = {};
 const CB_FAIL = {};
 const REASON_ERROR = Ci.mozIStorageStatementCallback.REASON_ERROR;
 Cu.import("resource://gre/modules/Services.jsm");
 /*
  * Helpers for various async operations.
  */
 this.Async = {
   /**
    * Execute an arbitrary number of asynchronous functions one after the
    * other, passing the callback arguments on to the next one.  All functions
    * must take a callback function as their last argument.  The 'this' object
    * will be whatever chain()'s is.
    *
    * @usage this._chain = Async.chain;
    *        this._chain(this.foo, this.bar, this.baz)(args, for, foo)
    *
    * This is equivalent to:
    *
    *   let self = this;
    *   self.foo(args, for, foo, function (bars, args) {
    *     self.bar(bars, args, function (baz, params) {
    *       self.baz(baz, params);
    *     });
    *   });
    */
   chain: function chain() {
     let funcs = Array.slice(arguments);
     let thisObj = this;
     return function callback() {
       if (funcs.length) {
         let args = Array.slice(arguments).concat(callback);
         let f = funcs.shift();
         f.apply(thisObj, args);
       }
     };
   },
   /**
    * Helpers for making asynchronous calls within a synchronous API possible.
    *
    * If you value your sanity, do not look closely at the following functions.
    */
   /**
    * Create a sync callback that remembers state, in particular whether it has
    * been called.
    */
   makeSyncCallback: function makeSyncCallback() {
     // The main callback remembers the value it was passed, and that it got data.
     let onComplete = function onComplete(data) {
       onComplete.state = CB_COMPLETE;
       onComplete.value = data;
     };
     // Initialize private callback data in preparation for being called.
     onComplete.state = CB_READY;
     onComplete.value = null;
     // Allow an alternate callback to trigger an exception to be thrown.
     onComplete.throw = function onComplete_throw(data) {
       onComplete.state = CB_FAIL;
       onComplete.value = data;
       // Cause the caller to get an exception and stop execution.
       throw data;
     };
     return onComplete;
   },
   /**
    * Wait for a sync callback to finish.
    */
   waitForSyncCallback: function waitForSyncCallback(callback) {
     // Grab the current thread so we can make it give up priority.
     let thread = Cc["@mozilla.org/thread-manager;1"].getService().currentThread;
     // Keep waiting until our callback is triggered (unless the app is quitting).
     while (Async.checkAppReady() && callback.state == CB_READY) {
       thread.processNextEvent(true);
     }
     // Reset the state of the callback to prepare for another call.
     let state = callback.state;
     callback.state = CB_READY;
     // Throw the value the callback decided to fail with.
     if (state == CB_FAIL) {
       throw callback.value;
     }
     // Return the value passed to the callback.
     return callback.value;
   },
   /**
    * Check if the app is still ready (not quitting).
    */
   checkAppReady: function checkAppReady() {
     // Watch for app-quit notification to stop any sync calls
     Services.obs.addObserver(function onQuitApplication() {
       Services.obs.removeObserver(onQuitApplication, "quit-application");
       Async.checkAppReady = function() {
         throw Components.Exception("App. Quitting", Cr.NS_ERROR_ABORT);
       };
     }, "quit-application", false);
     // In the common case, checkAppReady just returns true
     return (Async.checkAppReady = function() { return true; })();
   },
   /**
    * Return the two things you need to make an asynchronous call synchronous
    * by spinning the event loop.
    */
   makeSpinningCallback: function makeSpinningCallback() {
     let cb = Async.makeSyncCallback();
     function callback(error, ret) {
       if (error)
         cb.throw(error);
       cb(ret);
     }
     callback.wait = function() Async.waitForSyncCallback(cb);
     return callback;
   },
   // Prototype for mozIStorageCallback, used in querySpinningly.
   // This allows us to define the handle* functions just once rather
   // than on every querySpinningly invocation.
   _storageCallbackPrototype: {
     results: null,
     // These are set by queryAsync.
     names: null,
     syncCb: null,
     handleResult: function handleResult(results) {
       if (!this.names) {
         return;
       }
       if (!this.results) {
         this.results = [];
       }
       let row;
       while ((row = results.getNextRow()) != null) {
         let item = {};
         for each (let name in this.names) {
           item[name] = row.getResultByName(name);
         }
         this.results.push(item);
       }
     },
     handleError: function handleError(error) {
       this.syncCb.throw(error);
     },
     handleCompletion: function handleCompletion(reason) {
       // If we got an error, handleError will also have been called, so don't
       // call the callback! We never cancel statements, so we don't need to
       // address that quandary.
       if (reason == REASON_ERROR)
         return;
       // If we were called with column names but didn't find any results,
       // the calling code probably still expects an array as a return value.
       if (this.names && !this.results) {
         this.results = [];
       }
       this.syncCb(this.results);
     }
   },
   querySpinningly: function querySpinningly(query, names) {
     // 'Synchronously' asyncExecute, fetching all results by name.
     let storageCallback = {names: names,
                            syncCb: Async.makeSyncCallback()};
     storageCallback.__proto__ = Async._storageCallbackPrototype;
     query.executeAsync(storageCallback);
     return Async.waitForSyncCallback(storageCallback.syncCb);
   },
 };