services/common/async.js

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   3  * You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #ifndef MERGED_COMPARTMENT
   6
   7 this.EXPORTED_SYMBOLS = ["Async"];
   8
   9 const {classes: Cc, interfaces: Ci, results: Cr, utils: Cu} = Components;
  10
  11 #endif
  12
  13 // Constants for makeSyncCallback, waitForSyncCallback.
  14 const CB_READY = {};
  15 const CB_COMPLETE = {};
  16 const CB_FAIL = {};
  17
  18 const REASON_ERROR = Ci.mozIStorageStatementCallback.REASON_ERROR;
  19
  20 Cu.import("resource://gre/modules/Services.jsm");
  21
  22 /*
  23  * Helpers for various async operations.
  24  */
  25 this.Async = {
  26
  27   /**
  28    * Execute an arbitrary number of asynchronous functions one after the
  29    * other, passing the callback arguments on to the next one.  All functions
  30    * must take a callback function as their last argument.  The 'this' object
  31    * will be whatever chain()'s is.
  32    *
  33    * @usage this._chain = Async.chain;
  34    *        this._chain(this.foo, this.bar, this.baz)(args, for, foo)
  35    *
  36    * This is equivalent to:
  37    *
  38    *   let self = this;
  39    *   self.foo(args, for, foo, function (bars, args) {
  40    *     self.bar(bars, args, function (baz, params) {
  41    *       self.baz(baz, params);
  42    *     });
  43    *   });
  44    */
  45   chain: function chain() {
  46     let funcs = Array.slice(arguments);
  47     let thisObj = this;
  48     return function callback() {
  49       if (funcs.length) {
  50         let args = Array.slice(arguments).concat(callback);
  51         let f = funcs.shift();
  52         f.apply(thisObj, args);
  53       }
  54     };
  55   },
  56
  57   /**
  58    * Helpers for making asynchronous calls within a synchronous API possible.
  59    *
  60    * If you value your sanity, do not look closely at the following functions.
  61    */
  62
  63   /**
  64    * Create a sync callback that remembers state, in particular whether it has
  65    * been called.
  66    * The returned callback can be called directly passing an optional arg which
  67    * will be returned by waitForSyncCallback().  The callback also has a
  68    * .throw() method, which takes an error object and will cause
  69    * waitForSyncCallback to fail with the error object thrown as an exception
  70    * (but note that the .throw method *does not* itself throw - it just causes
  71    * the wait function to throw).
  72    */
  73   makeSyncCallback: function makeSyncCallback() {
  74     // The main callback remembers the value it was passed, and that it got data.
  75     let onComplete = function onComplete(data) {
  76       onComplete.state = CB_COMPLETE;
  77       onComplete.value = data;
  78     };
  79
  80     // Initialize private callback data in preparation for being called.
  81     onComplete.state = CB_READY;
  82     onComplete.value = null;
  83
  84     // Allow an alternate callback to trigger an exception to be thrown.
  85     onComplete.throw = function onComplete_throw(data) {
  86       onComplete.state = CB_FAIL;
  87       onComplete.value = data;
  88     };
  89
  90     return onComplete;
  91   },
  92
  93   /**
  94    * Wait for a sync callback to finish.
  95    */
  96   waitForSyncCallback: function waitForSyncCallback(callback) {
  97     // Grab the current thread so we can make it give up priority.
  98     let thread = Cc["@mozilla.org/thread-manager;1"].getService().currentThread;
  99
 100     // Keep waiting until our callback is triggered (unless the app is quitting).
 101     while (Async.checkAppReady() && callback.state == CB_READY) {
 102       thread.processNextEvent(true);
 103     }
 104
 105     // Reset the state of the callback to prepare for another call.
 106     let state = callback.state;
 107     callback.state = CB_READY;
 108
 109     // Throw the value the callback decided to fail with.
 110     if (state == CB_FAIL) {
 111       throw callback.value;
 112     }
 113
 114     // Return the value passed to the callback.
 115     return callback.value;
 116   },
 117
 118   /**
 119    * Check if the app is still ready (not quitting).
 120    */
 121   checkAppReady: function checkAppReady() {
 122     // Watch for app-quit notification to stop any sync calls
 123     Services.obs.addObserver(function onQuitApplication() {
 124       Services.obs.removeObserver(onQuitApplication, "quit-application");
 125       Async.checkAppReady = function() {
 126         throw Components.Exception("App. Quitting", Cr.NS_ERROR_ABORT);
 127       };
 128     }, "quit-application", false);
 129     // In the common case, checkAppReady just returns true
 130     return (Async.checkAppReady = function() { return true; })();
 131   },
 132
 133   /**
 134    * Return the two things you need to make an asynchronous call synchronous
 135    * by spinning the event loop.
 136    */
 137   makeSpinningCallback: function makeSpinningCallback() {
 138     let cb = Async.makeSyncCallback();
 139     function callback(error, ret) {
 140       if (error)
 141         cb.throw(error);
 142       else
 143         cb(ret);
 144     }
 145     callback.wait = function() Async.waitForSyncCallback(cb);
 146     return callback;
 147   },
 148
 149   // Prototype for mozIStorageCallback, used in querySpinningly.
 150   // This allows us to define the handle* functions just once rather
 151   // than on every querySpinningly invocation.
 152   _storageCallbackPrototype: {
 153     results: null,
 154
 155     // These are set by queryAsync.
 156     names: null,
 157     syncCb: null,
 158
 159     handleResult: function handleResult(results) {
 160       if (!this.names) {
 161         return;
 162       }
 163       if (!this.results) {
 164         this.results = [];
 165       }
 166       let row;
 167       while ((row = results.getNextRow()) != null) {
 168         let item = {};
 169         for each (let name in this.names) {
 170           item[name] = row.getResultByName(name);
 171         }
 172         this.results.push(item);
 173       }
 174     },
 175     handleError: function handleError(error) {
 176       this.syncCb.throw(error);
 177     },
 178     handleCompletion: function handleCompletion(reason) {
 179
 180       // If we got an error, handleError will also have been called, so don't
 181       // call the callback! We never cancel statements, so we don't need to
 182       // address that quandary.
 183       if (reason == REASON_ERROR)
 184         return;
 185
 186       // If we were called with column names but didn't find any results,
 187       // the calling code probably still expects an array as a return value.
 188       if (this.names && !this.results) {
 189         this.results = [];
 190       }
 191       this.syncCb(this.results);
 192     }
 193   },
 194
 195   querySpinningly: function querySpinningly(query, names) {
 196     // 'Synchronously' asyncExecute, fetching all results by name.
 197     let storageCallback = {names: names,
 198                            syncCb: Async.makeSyncCallback()};
 199     storageCallback.__proto__ = Async._storageCallbackPrototype;
 200     query.executeAsync(storageCallback);
 201     return Async.waitForSyncCallback(storageCallback.syncCb);
 202   },
 203 };