DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (b8141448e0ba)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155
/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim:set ts=2 sw=2 sts=2 et cindent: */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

[ptr] native PRThread(PRThread);

interface nsIEventTarget;
interface nsIRunnable;
interface nsIThread;

[scriptable, function, uuid(039a227d-0cb7-44a5-a8f9-dbb7071979f2)]
interface nsINestedEventLoopCondition : nsISupports
{
  /**
   * Returns true if the current nested event loop should stop spinning.
   */
  bool isDone();
};

/**
 * An interface for creating and locating nsIThread instances.
 */
[scriptable, uuid(1be89eca-e2f7-453b-8d38-c11ba247f6f3)]
interface nsIThreadManager : nsISupports
{
  /**
   * Default number of bytes reserved for a thread's stack, if no stack size
   * is specified in newThread().
   *
   * Defaults can be a little overzealous for many platforms.
   *
   * On Linux and OS X, for instance, the default thread stack size is whatever
   * getrlimit(RLIMIT_STACK) returns, which is often set at 8MB. Or, on Linux,
   * if the stack size is unlimited, we fall back to 2MB. This causes particular
   * problems on Linux, which allocates 2MB huge VM pages, and will often
   * immediately allocate them for any stacks which are 2MB or larger.
   *
   * The default on Windows is 1MB, which is a little more reasonable. But the
   * vast majority of our threads don't need anywhere near that much space.
   *
   * ASan and TSan builds, however, often need a bit more, so give them a the
   * platform default.
   */
%{C++
#if defined(MOZ_ASAN) || defined(MOZ_TSAN)
  static constexpr uint32_t DEFAULT_STACK_SIZE = 0;
#else
  static constexpr uint32_t DEFAULT_STACK_SIZE = 256 * 1024;
#endif

  static const uint32_t kThreadPoolStackSize = DEFAULT_STACK_SIZE;
%}

  /**
   * Create a new thread (a global, user PRThread).
   *
   * @param creationFlags
   *   Reserved for future use.  Pass 0.
   * @param stackSize
   *   Number of bytes to reserve for the thread's stack. 0 means use platform
   *   default.
   *
   * @returns
   *   The newly created nsIThread object.
   */
  nsIThread newThread(in unsigned long creationFlags, [optional] in unsigned long stackSize);

  /**
   * Create a new thread (a global, user PRThread) with the specified name.
   *
   * @param name
   *   The name of the thread. Passing an empty name is equivalent to
   *   calling newThread(0, stackSize), i.e. the thread will not be named.
   * @param stackSize
   *   Number of bytes to reserve for the thread's stack. 0 means use platform
   *   default.
   *
   * @returns
   *   The newly created nsIThread object.
   */
  [noscript] nsIThread newNamedThread(in ACString name, [optional] in unsigned long stackSize);

  /**
   * Get the main thread.
   */
  readonly attribute nsIThread mainThread;

  /**
   * Get the current thread.  If the calling thread does not already have a
   * nsIThread associated with it, then a new nsIThread will be created and
   * associated with the current PRThread.
   */
  readonly attribute nsIThread currentThread;

  /**
   * This queues a runnable to the main thread. It's a shortcut for JS callers
   * to be used instead of
   *   .mainThread.dispatch(runnable, Ci.nsIEventTarget.DISPATCH_NORMAL);
   * or
   *   .currentThread.dispatch(runnable, Ci.nsIEventTarget.DISPATCH_NORMAL);
   * C++ callers should instead use NS_DispatchToMainThread.
   */
  void dispatchToMainThread(in nsIRunnable event, [optional] in uint32_t priority);

  /**
   * This queues a runnable to the main thread's idle queue.
   *
   * @param event
   *   The event to dispatch.
   * @param timeout
   *   The time in milliseconds until this event should be moved from the idle
   *   queue to the regular queue if it hasn't been executed by then.  If not
   *   passed or a zero value is specified, the event will never be moved to
   *   the regular queue.
   */
  void idleDispatchToMainThread(in nsIRunnable event,
                                [optional] in uint32_t timeout);

  /**
   * Enter a nested event loop on the current thread, waiting on, and
   * processing events until condition.isDone() returns true.
   *
   * If condition.isDone() throws, this function will throw as well.
   *
   * C++ code should not use this function, instead preferring
   * mozilla::SpinEventLoopUntil.
   */
  void spinEventLoopUntil(in nsINestedEventLoopCondition condition);

  /**
   * Similar to the previous method, but the spinning of the event loop
   * terminates when the shutting down starts.
   *
   * C++ code should not use this function, instead preferring
   * mozilla::SpinEventLoopUntil.
   */
  void spinEventLoopUntilOrShutdown(in nsINestedEventLoopCondition condition);

  /**
   * Spin the current thread's event loop until there are no more pending
   * events.  This could be done with spinEventLoopUntil, but that would
   * require access to the current thread from JavaScript, which we are
   * moving away from.
   */
  void spinEventLoopUntilEmpty();

  /**
   * Return the SchedulerEventTarget for the SystemGroup.
   */
  readonly attribute nsIEventTarget systemGroupEventTarget;
};