ext/Sync.js

 * Version: MPL 1.1/GPL 2.0/LGPL 2.1

 *

 * The contents of this file are subject to the Mozilla Public License Version

 * 1.1 (the "License"); you may not use this file except in compliance with

 * the License. You may obtain a copy of the License at

 * http://www.mozilla.org/MPL/

 *

 * Software distributed under the License is distributed on an "AS IS" basis,

 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License

 * for the specific language governing rights and limitations under the

 * License.

 *

 * The Original Code is Weave.

 *

 * The Initial Developer of the Original Code is Mozilla.

 * Portions created by the Initial Developer are Copyright (C) 2009

 * the Initial Developer. All Rights Reserved.

 *

 * Contributor(s):

 *   Edward Lee <edilee@mozilla.com>

 *   Dan Mills <thunder@mozilla.com>

 *   Myk Melez <myk@mozilla.org>

 *

 * Alternatively, the contents of this file may be used under the terms of

 * either the GNU General Public License Version 2 or later (the "GPL"), or

 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),

 * in which case the provisions of the GPL or the LGPL are applicable instead

 * of those above. If you wish to allow use of your version of this file only

 * under the terms of either the GPL or the LGPL, and not to allow others to

 * use your version of this file under the terms of the MPL, indicate your

 * decision by deleting the provisions above and replace them with the notice

 * and other provisions required by the GPL or the LGPL. If you do not delete

 * the provisions above, a recipient may use your version of this file under

 * the terms of any one of the MPL, the GPL or the LGPL.

 *

 * ***** END LICENSE BLOCK ***** */

// Define some constants to specify various sync. callback states

// Share a secret only for functions in this file to prevent outside access

/**

 * Check if the app is ready (not quitting)

 */

  // Watch for app-quit notification to stop any sync. calls

      // Now that the app is quitting, make checkAppReady throw

      };

    }

  // In the common case, checkAppReady just returns true

};

/**

 * Create a callback that remembers state like whether it's been called

 */

  // Initialize private callback data to prepare to be called

  };

  // The main callback remembers the value it's passed and that it got data

  };

  // Only allow access to the private data if the secret matches

  // Allow an alternate callback to trigger an exception to be thrown

    // Cause the caller to get an exception and stop execution

  };

}

/**

 * Make a synchronous version of the function object that will be called with

 * the provided thisArg.

 *

 * @param func {Function}

 *        The asynchronous function to make a synchronous function

 * @param thisArg {Object} [optional]

 *        The object that the function accesses with "this"

 * @param callback {Function} [optional] [internal]

 *        The callback that will trigger the end of the async. call

 * @usage let ret = Sync(asyncFunc, obj)(arg1, arg2);

 * @usage let ret = Sync(ignoreThisFunc)(arg1, arg2);

 * @usage let sync = Sync(async); let ret = sync(arg1, arg2);

 */

    // Grab the current thread so we can make it give up priority

    // Save the original arguments into an array

    // We need to create a callback and insert it if we weren't given one

      // Create a new callback for this invocation instance and pass it in

    }

    // Call the async function bound to thisArg with the passed args

    // Keep waiting until our callback is triggered unless the app is quitting

    // Reset the state of the callback to prepare for another call

    // Throw the value the callback decided to fail with

    // Return the value passed to the callback

  };

}

/**

 * Make a synchronous version of an async. function and the callback to trigger

 * the end of the async. call.

 *

 * @param func {Function}

 *        The asynchronous function to make a synchronous function

 * @param thisArg {Object} [optional]

 *        The object that the function accesses with "this"

 * @usage let [sync, cb] = Sync.withCb(async); let ret = sync(arg1, arg2, cb);

 */

};

/**

 * Set a timer, simulating the API for the window.setTimeout call.

 * This only simulates the API for the version of the call that accepts

 * a function as its first argument and no additional parameters,

 * and it doesn't return the timeout ID.

 *

 * @param func {Function}

 *        the function to call after the delay

 * @param delay {Number}

 *        the number of milliseconds to wait

 */

      // This line actually just keeps a reference to timer (prevent GC)

      // Call the function so that "this" is global

    }

  }

}

}

/**

 * Sleep the specified number of milliseconds, pausing execution of the caller

 * without halting the current thread.

 * For example, the following code pauses 1000ms between dumps:

 *

 *   dump("Wait for it...\n");

 *   Sync.sleep(1000);

 *   dump("Wait for it...\n");

 *   Sync.sleep(1000);

 *   dump("What are you waiting for?!\n");

 *

 * @param milliseconds {Number}

 *        The number of milliseconds to sleep

 */