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