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