xpcom/threads/nsIThreadManager.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 "nsISupports.idl"
   8
   9 [ptr] native PRThread(PRThread);
  10       native ThreadCreationOptions(nsIThreadManager::ThreadCreationOptions);
  11
  12 interface nsIEventTarget;
  13 interface nsIRunnable;
  14 interface nsIThread;
  15
  16 [scriptable, function, uuid(039a227d-0cb7-44a5-a8f9-dbb7071979f2)]
  17 interface nsINestedEventLoopCondition : nsISupports
  18 {
  19   /**
  20    * Returns true if the current nested event loop should stop spinning.
  21    */
  22   bool isDone();
  23 };
  24
  25 /**
  26  * An interface for creating and locating nsIThread instances.
  27  */
  28 [scriptable, uuid(1be89eca-e2f7-453b-8d38-c11ba247f6f3)]
  29 interface nsIThreadManager : nsISupports
  30 {
  31   /**
  32    * Default number of bytes reserved for a thread's stack, if no stack size
  33    * is specified in newThread().
  34    *
  35    * Defaults can be a little overzealous for many platforms.
  36    *
  37    * On Linux and OS X, for instance, the default thread stack size is whatever
  38    * getrlimit(RLIMIT_STACK) returns, which is often set at 8MB. Or, on Linux,
  39    * if the stack size is unlimited, we fall back to 2MB. This causes particular
  40    * problems on Linux, which allocates 2MB huge VM pages, and will often
  41    * immediately allocate them for any stacks which are 2MB or larger.
  42    *
  43    * The default on Windows is 1MB, which is a little more reasonable. But the
  44    * vast majority of our threads don't need anywhere near that much space.
  45    *
  46    * ASan, TSan and non-opt builds, however, often need a bit more, so give
  47    * them the platform default.
  48    */
  49 %{C++
  50 #if defined(MOZ_ASAN) || defined(MOZ_TSAN) || !defined(__OPTIMIZE__)
  51   static constexpr uint32_t DEFAULT_STACK_SIZE = 0;
  52 #else
  53   static constexpr uint32_t DEFAULT_STACK_SIZE = 256 * 1024;
  54 #endif
  55
  56   static const uint32_t kThreadPoolStackSize = DEFAULT_STACK_SIZE;
  57
  58   struct ThreadCreationOptions {
  59     // The size in bytes to reserve for the thread's stack. A value of `0` means
  60     // to use the platform default.
  61     uint32_t stackSize = nsIThreadManager::DEFAULT_STACK_SIZE;
  62
  63     // If set to `true`, any attempts to dispatch runnables to this thread
  64     // without `DISPATCH_IGNORE_BLOCK_DISPATCH` will fail.
  65     //
  66     // This is intended to be used for threads which are expected to generally
  67     // only service a single runnable (other than thread lifecycle runnables),
  68     // and perform their own event dispatching internaly, such as thread pool
  69     // threads or the timer thread.
  70     bool blockDispatch = false;
  71
  72     // (Windows-only) Whether the thread should have a MessageLoop capable of
  73     // processing native UI events. Defaults to false.
  74     bool isUiThread = false;
  75   };
  76 %}
  77
  78   /**
  79    * Create a new thread (a global, user PRThread) with the specified name.
  80    *
  81    * @param name
  82    *   The name of the thread. If it is empty the thread will not be named.
  83    * @param options
  84    *   Configuration options for the newly created thread.
  85    *
  86    * @returns
  87    *   The newly created nsIThread object.
  88    */
  89   [noscript] nsIThread newNamedThread(in ACString name, in ThreadCreationOptions options);
  90
  91   /**
  92    * Get the main thread.
  93    */
  94   readonly attribute nsIThread mainThread;
  95
  96   /**
  97    * Get the current thread.  If the calling thread does not already have a
  98    * nsIThread associated with it, then a new nsIThread will be created and
  99    * associated with the current PRThread.
 100    */
 101   readonly attribute nsIThread currentThread;
 102
 103   /**
 104    * This queues a runnable to the main thread. It's a shortcut for JS callers
 105    * to be used instead of
 106    *   .mainThread.dispatch(runnable, Ci.nsIEventTarget.DISPATCH_NORMAL);
 107    * or
 108    *   .currentThread.dispatch(runnable, Ci.nsIEventTarget.DISPATCH_NORMAL);
 109    * C++ callers should instead use NS_DispatchToMainThread.
 110    */
 111   [optional_argc]
 112   void dispatchToMainThread(in nsIRunnable event, [optional] in uint32_t priority);
 113
 114   /**
 115    * Similar to dispatchToMainThread, but wraps the event with extra
 116    * runnable that allocates nsAutoMicroTask.
 117    */
 118   [optional_argc]
 119   void dispatchToMainThreadWithMicroTask(in nsIRunnable event, [optional] in uint32_t priority);
 120
 121   /**
 122    * This queues a runnable to the main thread's idle queue.
 123    *
 124    * @param event
 125    *   The event to dispatch.
 126    * @param timeout
 127    *   The time in milliseconds until this event should be moved from the idle
 128    *   queue to the regular queue if it hasn't been executed by then.  If not
 129    *   passed or a zero value is specified, the event will never be moved to
 130    *   the regular queue.
 131    */
 132   void idleDispatchToMainThread(in nsIRunnable event,
 133                                 [optional] in uint32_t timeout);
 134
 135   /*
 136    * A helper method to dispatch a task through nsIDirectTaskDispatcher to the
 137    * current thread.
 138    */
 139   void dispatchDirectTaskToCurrentThread(in nsIRunnable event);
 140
 141   /**
 142    * Enter a nested event loop on the current thread, waiting on, and
 143    * processing events until condition.isDone() returns true.
 144    *
 145    * If condition.isDone() throws, this function will throw as well.
 146    *
 147    * C++ code should not use this function, instead preferring
 148    * mozilla::SpinEventLoopUntil.
 149    */
 150   void spinEventLoopUntil(in ACString aVeryGoodReasonToDoThis, in nsINestedEventLoopCondition condition);
 151
 152   /**
 153    * Similar to the previous method, but the spinning of the event loop
 154    * terminates when the quit application shutting down starts.
 155    *
 156    * C++ code should not use this function, instead preferring
 157    * mozilla::SpinEventLoopUntil.
 158    */
 159   void spinEventLoopUntilOrQuit(in ACString aVeryGoodReasonToDoThis, in nsINestedEventLoopCondition condition);
 160
 161   /**
 162    * Spin the current thread's event loop until there are no more pending
 163    * events.  This could be done with spinEventLoopUntil, but that would
 164    * require access to the current thread from JavaScript, which we are
 165    * moving away from.
 166    */
 167   void spinEventLoopUntilEmpty();
 168
 169   /**
 170    * Return the EventTarget for the main thread.
 171    */
 172   readonly attribute nsIEventTarget mainThreadEventTarget;
 173 };