xpcom/threads/nsIThreadInternal.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim:set ts=2 sw=2 sts=2 et cindent: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #include "nsIThread.idl"
   8
   9 interface nsIRunnable;
  10 interface nsIThreadObserver;
  11
  12 /**
  13  * The XPCOM thread object implements this interface, which allows a consumer
  14  * to observe dispatch activity on the thread.
  15  */
  16 [scriptable, uuid(b24c5af3-43c2-4d17-be14-94d6648a305f)]
  17 interface nsIThreadInternal : nsIThread
  18 {
  19   /**
  20    * Get/set the current thread observer (may be null).  This attribute may be
  21    * read from any thread, but must only be set on the thread corresponding to
  22    * this thread object.  The observer will be released on the thread
  23    * corresponding to this thread object after all other events have been
  24    * processed during a call to Shutdown.
  25    */
  26   attribute nsIThreadObserver observer;
  27
  28   /**
  29    * The current recursion depth, 0 when no events are running, 1 when a single
  30    * event is running, and higher when nested events are running. Must only be
  31    * called on the target thread.
  32    */
  33   readonly attribute unsigned long recursionDepth;
  34
  35   /**
  36    * Add an observer that will *only* receive onProcessNextEvent,
  37    * beforeProcessNextEvent. and afterProcessNextEvent callbacks. Always called
  38    * on the target thread, and the implementation does not have to be
  39    * threadsafe. Order of callbacks is not guaranteed (i.e.
  40    * afterProcessNextEvent may be called first depending on whether or not the
  41    * observer is added in a nested loop). Holds a strong ref.
  42    */
  43   void addObserver(in nsIThreadObserver observer);
  44
  45   /**
  46    * Remove an observer added via the addObserver call. Once removed the
  47    * observer will never be called again by the thread.
  48    */
  49   void removeObserver(in nsIThreadObserver observer);
  50
  51   /**
  52    * This method causes any events currently enqueued on the thread to be
  53    * suppressed until PopEventQueue is called, and any event dispatched to this
  54    * thread's nsIEventTarget will queue as well. Calls to PushEventQueue may be
  55    * nested and must each be paired with a call to PopEventQueue in order to
  56    * restore the original state of the thread. The returned nsIEventTarget may
  57    * be used to push events onto the nested queue. Dispatching will be disabled
  58    * once the event queue is popped. The thread will only ever process pending
  59    * events for the innermost event queue. Must only be called on the target
  60    * thread.
  61    */
  62   [noscript] nsIEventTarget pushEventQueue();
  63
  64   /**
  65    * Revert a call to PushEventQueue. When an event queue is popped, any events
  66    * remaining in the queue are appended to the elder queue. This also causes
  67    * the nsIEventTarget returned from PushEventQueue to stop dispatching events.
  68    * Must only be called on the target thread, and with the innermost event
  69    * queue.
  70    */
  71   [noscript] void popEventQueue(in nsIEventTarget aInnermostTarget);
  72 };
  73
  74 /**
  75  * This interface provides the observer with hooks to implement a layered
  76  * event queue.  For example, it is possible to overlay processing events
  77  * for a GUI toolkit on top of the events for a thread:
  78  *
  79  *   var NativeQueue;
  80  *   Observer = {
  81  *     onDispatchedEvent(thread) {
  82  *       NativeQueue.signal();
  83  *     }
  84  *     onProcessNextEvent(thread, mayWait, recursionDepth) {
  85  *       if (NativeQueue.hasNextEvent())
  86  *         NativeQueue.processNextEvent();
  87  *       while (mayWait && !thread.hasPendingEvent()) {
  88  *         NativeQueue.wait();
  89  *         NativeQueue.processNextEvent();
  90  *       }
  91  *     }
  92  *   };
  93  *
  94  * NOTE: The implementation of this interface must be threadsafe.
  95  *
  96  * NOTE: It is valid to change the thread's observer during a call to an
  97  *       observer method.
  98  *
  99  * NOTE: Will be split into two interfaces soon: one for onProcessNextEvent and
 100  *       afterProcessNextEvent, then another that inherits the first and adds
 101  *       onDispatchedEvent.
 102  */
 103 [scriptable, uuid(09b424c3-26b0-4128-9039-d66f85b02c63)]
 104 interface nsIThreadObserver : nsISupports
 105 {
 106   /**
 107    * This method is called after an event has been dispatched to the thread.
 108    * This method may be called from any thread.
 109    *
 110    * @param thread
 111    *   The thread where the event is being dispatched.
 112    */
 113   void onDispatchedEvent(in nsIThreadInternal thread);
 114
 115   /**
 116    * This method is called when nsIThread::ProcessNextEvent is called.  It does
 117    * not guarantee that an event is actually going to be processed.  This method
 118    * is only called on the target thread.
 119    *
 120    * @param thread
 121    *   The thread being asked to process another event.
 122    * @param mayWait
 123    *   Indicates whether or not the method is allowed to block the calling
 124    *   thread.  For example, this parameter is false during thread shutdown.
 125    * @param recursionDepth
 126    *   Indicates the number of calls to ProcessNextEvent on the call stack in
 127    *   addition to the current call.
 128    */
 129   void onProcessNextEvent(in nsIThreadInternal thread, in boolean mayWait,
 130                           in unsigned long recursionDepth);
 131
 132   /**
 133    * This method is called (from nsIThread::ProcessNextEvent) after an event
 134    * is processed.  It does not guarantee that an event was actually processed
 135    * (depends on the value of |eventWasProcessed|.  This method is only called
 136    * on the target thread.
 137    *
 138    * @param thread
 139    *   The thread that processed another event.
 140    * @param recursionDepth
 141    *   Indicates the number of calls to ProcessNextEvent on the call stack in
 142    *   addition to the current call.
 143    * @param eventWasProcessed
 144    *   Indicates whether an event was actually processed. May be false if the
 145    *   |mayWait| flag was false when calling nsIThread::ProcessNextEvent().
 146    */
 147   void afterProcessNextEvent(in nsIThreadInternal thread,
 148                              in unsigned long recursionDepth,
 149                              in bool eventWasProcessed);
 150 };