xpcom/threads/nsIThread.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 "nsISerialEventTarget.idl"
   8 #include "nsIThreadShutdown.idl"
   9
  10 %{C++
  11 #include "mozilla/AlreadyAddRefed.h"
  12
  13 namespace mozilla {
  14 class TimeStamp;
  15 class TimeDurationValueCalculator;
  16 template <typename T> class BaseTimeDuration;
  17 typedef BaseTimeDuration<TimeDurationValueCalculator> TimeDuration;
  18 enum class EventQueuePriority;
  19 }
  20 %}
  21
  22 [ptr] native PRThread(PRThread);
  23 native EventQueuePriority(mozilla::EventQueuePriority);
  24
  25 native nsIEventTargetPtr(nsIEventTarget*);
  26 native nsISerialEventTargetPtr(nsISerialEventTarget*);
  27 native TimeStamp(mozilla::TimeStamp);
  28 native TimeDuration(mozilla::TimeDuration);
  29
  30 /**
  31  * This interface provides a high-level abstraction for an operating system
  32  * thread.
  33  *
  34  * Threads have a built-in event queue, and a thread is an event target that
  35  * can receive nsIRunnable objects (events) to be processed on the thread.
  36  *
  37  * See nsIThreadManager for the API used to create and locate threads.
  38  */
  39 [builtinclass, scriptable, rust_sync, uuid(5801d193-29d1-4964-a6b7-70eb697ddf2b)]
  40 interface nsIThread : nsISerialEventTarget
  41 {
  42   /**
  43    * @returns
  44    *   The NSPR thread object corresponding to this nsIThread.
  45    */
  46   [noscript] readonly attribute PRThread PRThread;
  47
  48   /**
  49    * @returns
  50    *  Whether or not this thread may call into JS. Used in the profiler
  51    *  to avoid some unnecessary locking.
  52    */
  53   [noscript] attribute boolean CanInvokeJS;
  54
  55   /**
  56    * Thread QoS priorities. Currently only supported on MacOS.
  57    */
  58
  59   cenum QoSPriority : 32 {
  60     QOS_PRIORITY_NORMAL,
  61     QOS_PRIORITY_LOW
  62   };
  63
  64   /**
  65    * Shutdown the thread.  This method prevents further dispatch of events to
  66    * the thread, and it causes any pending events to run to completion before
  67    * the thread joins (see PR_JoinThread) with the current thread.  During this
  68    * method call, events for the current thread may be processed.
  69    *
  70    * This method MAY NOT be executed from the thread itself.  Instead, it is
  71    * meant to be executed from another thread (usually the thread that created
  72    * this thread or the main application thread).  When this function returns,
  73    * the thread will be shutdown, and it will no longer be possible to dispatch
  74    * events to the thread.
  75    *
  76    * @throws NS_ERROR_UNEXPECTED
  77    *   Indicates that this method was erroneously called when this thread was
  78    *   the current thread, that this thread was not created with a call to
  79    *   nsIThreadManager::NewThread, or if this method was called more than once
  80    *   on the thread object.
  81    */
  82   void shutdown();
  83
  84   /**
  85    * This method may be called to determine if there are any events ready to be
  86    * processed.  It may only be called when this thread is the current thread.
  87    *
  88    * Because events may be added to this thread by another thread, a "false"
  89    * result does not mean that this thread has no pending events.  It only
  90    * means that there were no pending events when this method was called.
  91    *
  92    * @returns
  93    *   A boolean value that if "true" indicates that this thread has one or
  94    *   more pending events.
  95    *
  96    * @throws NS_ERROR_UNEXPECTED
  97    *   Indicates that this method was erroneously called when this thread was
  98    *   not the current thread.
  99    */
 100   boolean hasPendingEvents();
 101
 102   /**
 103    * Similar to above, but checks only possible high priority queue.
 104    */
 105   boolean hasPendingHighPriorityEvents();
 106
 107   /**
 108    * Process the next event.  If there are no pending events, then this method
 109    * may wait -- depending on the value of the mayWait parameter -- until an
 110    * event is dispatched to this thread.  This method is re-entrant but may
 111    * only be called if this thread is the current thread.
 112    *
 113    * @param mayWait
 114    *   A boolean parameter that if "true" indicates that the method may block
 115    *   the calling thread to wait for a pending event.
 116    *
 117    * @returns
 118    *   A boolean value that if "true" indicates that an event was processed.
 119    *
 120    * @throws NS_ERROR_UNEXPECTED
 121    *   Indicates that this method was erroneously called when this thread was
 122    *   not the current thread.
 123    */
 124   boolean processNextEvent(in boolean mayWait);
 125
 126   /**
 127    * Shutdown the thread asynchronously.  This method immediately prevents
 128    * further dispatch of events to the thread, and it causes any pending events
 129    * to run to completion before this thread joins with the current thread.
 130    *
 131    * UNLIKE shutdown() this does not process events on the current thread.
 132    * Instead it merely ensures that the current thread continues running until
 133    * this thread has shut down.
 134    *
 135    * This method MAY NOT be executed from the thread itself.  Instead, it is
 136    * meant to be executed from another thread (usually the thread that created
 137    * this thread or the main application thread).  When this function returns,
 138    * the thread will continue running until it exhausts its event queue.
 139    *
 140    * @throws NS_ERROR_UNEXPECTED
 141    *   Indicates that this method was erroneously called when this thread was
 142    *   the current thread, that this thread was not created with a call to
 143    *   nsIThreadManager::NewNamedThread, or that this method was called more
 144    *   than once on the thread object.
 145    */
 146   void asyncShutdown();
 147
 148   /**
 149    * Like `asyncShutdown`, but also returns a nsIThreadShutdown instance to
 150    * allow observing and controlling the thread's async shutdown progress.
 151    */
 152   nsIThreadShutdown beginShutdown();
 153
 154   /**
 155    * Dispatch an event to a specified queue for the thread.  This function
 156    * may be called from any thread, and it may be called re-entrantly.
 157    * Most users should use the NS_Dispatch*() functions in nsThreadUtils instead
 158    * of calling this directly.
 159    *
 160    * @param event
 161    *   The alreadyAddRefed<> event to dispatch.
 162    *   NOTE that the event will be leaked if it fails to dispatch.
 163    * @param queue
 164    *   Which event priority queue this should be added to
 165    *
 166    * @throws NS_ERROR_INVALID_ARG
 167    *   Indicates that event is null.
 168    * @throws NS_ERROR_UNEXPECTED
 169    *   Indicates that the thread is shutting down and has finished processing
 170    * events, so this event would never run and has not been dispatched.
 171    */
 172   [noscript] void dispatchToQueue(in alreadyAddRefed_nsIRunnable event,
 173                                   in EventQueuePriority queue);
 174
 175   /**
 176    * This is set to the end of the last 50+ms event that was executed on
 177    * this thread (for MainThread only).  Otherwise returns a null TimeStamp.
 178    */
 179   [noscript] readonly attribute TimeStamp lastLongTaskEnd;
 180   [noscript] readonly attribute TimeStamp lastLongNonIdleTaskEnd;
 181
 182   /**
 183    * Get information on the timing of the currently-running event.
 184    *
 185    * @param delay
 186    *   The amount of time the current running event in the specified queue waited
 187    *   to run. Will return TimeDuration() if the queue is empty or has not run any
 188    *   new events since event delay monitoring started.  NOTE: delay will be
 189    *   TimeDuration() if this thread uses a PrioritizedEventQueue (i.e. MainThread)
 190    *   and the event priority is below Input.
 191    * @param start
 192    *   The time the currently running event began to run, or TimeStamp() if no
 193    *   event is running.
 194    */
 195   [noscript] void getRunningEventDelay(out TimeDuration delay, out TimeStamp start);
 196
 197   /**
 198    * Set information on the timing of the currently-running event.
 199    * Overrides the values returned by getRunningEventDelay
 200    *
 201    * @param delay
 202    *   Delay the running event spent in queues, or TimeDuration() if
 203    *   there's no running event.
 204    * @param start
 205    *   The time the currently running event began to run, or TimeStamp() if no
 206    *   event is running.
 207    */
 208   [noscript] void setRunningEventDelay(in TimeDuration delay, in TimeStamp start);
 209
 210   [noscript] void setNameForWakeupTelemetry(in ACString name);
 211
 212   /**
 213    * Set the QoS priority of threads where this may be available. Currently
 214    * restricted to MacOS. Must be on the thread to call this method.
 215    *
 216    * @param aPriority
 217    *   The specified priority we will adjust to. Can be low (background) or
 218    *   normal (default / user-interactive)
 219    */
 220   [noscript] void setThreadQoS(in nsIThread_QoSPriority aPriority);
 221
 222 };