devtools/platform/nsIJSInspector.idl

   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
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #include "nsISupports.idl"
   6
   7 /**
   8  * Utilities for running nested event loops, asking them to return, and
   9  * keeping track of which ones are still running.
  10  */
  11 [scriptable, uuid(6758d0d7-e96a-4c5c-bca8-3bcbe5a15943)]
  12 interface nsIJSInspector : nsISupports
  13 {
  14   /**
  15    * Process the current thread's event queue, calling event handlers until
  16    * a call to exitNestedEventLoop, below, asks us to return.
  17    *
  18    * The name 'enterNestedEventLoop' may be misleading if read too literally.
  19    * This method loops calling event handlers until one asks it to stop, and
  20    * then returns. So by that point, the nested event loop has been not only
  21    * entered, but also run and exited.
  22    *
  23    * When enterNestedEventLoop calls an event handler, that handler may itself
  24    * call enterNestedEventLoop, and so on, so that there may be arbitrarily
  25    * many such calls on the stack at the same time.
  26    *
  27    * We say an enterNestedEventLoop call is "running" if it has not yet been
  28    * asked to return, or "stopped" if it has been asked to return once it has
  29    * finished processing the current event.
  30    *
  31    * @param requestor   A token of the caller's choice to identify this event
  32    *                    loop.
  33    *
  34    * @return depth      The number of running enterNestedEventLoop calls
  35    *                    remaining, now that this one has returned.
  36    *
  37    *                    (Note that not all calls still on the stack are
  38    *                    necessary running; exitNestedEventLoop can ask any
  39    *                    number of enterNestedEventLoop calls to return.)
  40    */
  41   unsigned long enterNestedEventLoop(in jsval requestor);
  42
  43   /**
  44    * Stop the youngest running enterNestedEventLoop call, asking it to return
  45    * once it has finished processing the current event.
  46    *
  47    * The name 'exitNestedEventLoop' may be misleading if read too literally.
  48    * The affected event loop does not return immediately when this method is
  49    * called. Rather, this method simply returns to its caller; the affected
  50    * loop's current event handler is allowed to run to completion; and then
  51    * that loop returns without processing any more events.
  52    *
  53    * This method ignores loops that have already been stopped, and operates on
  54    * the youngest loop that is still running. Each call to this method stops
  55    * another running loop.
  56    *
  57    * @return depth      The number of running enterNestedEventLoop calls
  58    *                    remaining, now that one has been stopped.
  59    *
  60    * @throws NS_ERROR_FAILURE if there are no running enterNestedEventLoop calls.
  61    */
  62   unsigned long exitNestedEventLoop();
  63
  64   /**
  65     * The number of running enterNestedEventLoop calls on the stack.
  66     * This count does not include stopped enterNestedEventLoop calls.
  67     */
  68   readonly attribute unsigned long eventLoopNestLevel;
  69
  70   /**
  71    * The |requestor| value that was passed to the youngest running
  72    * enterNestedEventLoop call.
  73    */
  74   readonly attribute jsval lastNestRequestor;
  75 };