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