summaryrefslogtreecommitdiffstats
path: root/xpcom/threads/SpinEventLoopUntil.h
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--xpcom/threads/SpinEventLoopUntil.h191
1 files changed, 191 insertions, 0 deletions
diff --git a/xpcom/threads/SpinEventLoopUntil.h b/xpcom/threads/SpinEventLoopUntil.h
new file mode 100644
index 0000000000..a281177268
--- /dev/null
+++ b/xpcom/threads/SpinEventLoopUntil.h
@@ -0,0 +1,191 @@
+/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
+/* vim: set ts=8 sts=2 et sw=2 tw=80: */
+/* 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/. */
+
+#ifndef xpcom_threads_SpinEventLoopUntil_h__
+#define xpcom_threads_SpinEventLoopUntil_h__
+
+#include "MainThreadUtils.h"
+#include "mozilla/Maybe.h"
+#include "mozilla/ProfilerLabels.h"
+#include "mozilla/ProfilerMarkers.h"
+#include "mozilla/StaticMutex.h"
+#include "nsString.h"
+#include "nsThreadUtils.h"
+#include "xpcpublic.h"
+
+class nsIThread;
+
+// A wrapper for nested event loops.
+//
+// This function is intended to make code more obvious (do you remember
+// what NS_ProcessNextEvent(nullptr, true) means?) and slightly more
+// efficient, as people often pass nullptr or NS_GetCurrentThread to
+// NS_ProcessNextEvent, which results in needless querying of the current
+// thread every time through the loop.
+//
+// You should use this function in preference to NS_ProcessNextEvent inside
+// a loop unless one of the following is true:
+//
+// * You need to pass `false` to NS_ProcessNextEvent; or
+// * You need to do unusual things around the call to NS_ProcessNextEvent,
+// such as unlocking mutexes that you are holding.
+//
+// If you *do* need to call NS_ProcessNextEvent manually, please do call
+// NS_GetCurrentThread() outside of your loop and pass the returned pointer
+// into NS_ProcessNextEvent for a tiny efficiency win.
+namespace mozilla {
+
+// You should normally not need to deal with this template parameter. If
+// you enjoy esoteric event loop details, read on.
+//
+// If you specify that NS_ProcessNextEvent wait for an event, it is possible
+// for NS_ProcessNextEvent to return false, i.e. to indicate that an event
+// was not processed. This can only happen when the thread has been shut
+// down by another thread, but is still attempting to process events outside
+// of a nested event loop.
+//
+// This behavior is admittedly strange. The scenario it deals with is the
+// following:
+//
+// * The current thread has been shut down by some owner thread.
+// * The current thread is spinning an event loop waiting for some condition
+// to become true.
+// * Said condition is actually being fulfilled by another thread, so there
+// are timing issues in play.
+//
+// Thus, there is a small window where the current thread's event loop
+// spinning can check the condition, find it false, and call
+// NS_ProcessNextEvent to wait for another event. But we don't actually
+// want it to wait indefinitely, because there might not be any other events
+// in the event loop, and the current thread can't accept dispatched events
+// because it's being shut down. Thus, actually blocking would hang the
+// thread, which is bad. The solution, then, is to detect such a scenario
+// and not actually block inside NS_ProcessNextEvent.
+//
+// But this is a problem, because we want to return the status of
+// NS_ProcessNextEvent to the caller of SpinEventLoopUntil if possible. In
+// the above scenario, however, we'd stop spinning prematurely and cause
+// all sorts of havoc. We therefore have this template parameter to
+// control whether errors are ignored or passed out to the caller of
+// SpinEventLoopUntil. The latter is the default; if you find yourself
+// wanting to use the former, you should think long and hard before doing
+// so, and write a comment like this defending your choice.
+
+enum class ProcessFailureBehavior {
+ IgnoreAndContinue,
+ ReportToCaller,
+};
+
+// SpinEventLoopUntil is a dangerous operation that can result in hangs.
+// In particular during shutdown we want to know if we are hanging
+// inside a nested event loop on the main thread.
+// This is a helper annotation class to keep track of this.
+struct MOZ_STACK_CLASS AutoNestedEventLoopAnnotation {
+ explicit AutoNestedEventLoopAnnotation(const nsACString& aEntry)
+ : mPrev(nullptr) {
+ if (NS_IsMainThread()) {
+ StaticMutexAutoLock lock(sStackMutex);
+ mPrev = sCurrent;
+ sCurrent = this;
+ if (mPrev) {
+ mStack = mPrev->mStack + "|"_ns + aEntry;
+ } else {
+ mStack = aEntry;
+ }
+ AnnotateXPCOMSpinEventLoopStack(mStack);
+ }
+ }
+
+ ~AutoNestedEventLoopAnnotation() {
+ if (NS_IsMainThread()) {
+ StaticMutexAutoLock lock(sStackMutex);
+ MOZ_ASSERT(sCurrent == this);
+ sCurrent = mPrev;
+ if (mPrev) {
+ AnnotateXPCOMSpinEventLoopStack(mPrev->mStack);
+ } else {
+ AnnotateXPCOMSpinEventLoopStack(""_ns);
+ }
+ }
+ }
+
+ static void CopyCurrentStack(nsCString& aNestedSpinStack) {
+ // We need to copy this behind a mutex as the
+ // memory for our instances is stack-bound and
+ // can go away at any time.
+ StaticMutexAutoLock lock(sStackMutex);
+ if (sCurrent) {
+ aNestedSpinStack = sCurrent->mStack;
+ } else {
+ aNestedSpinStack = "(no nested event loop active)"_ns;
+ }
+ }
+
+ private:
+ AutoNestedEventLoopAnnotation(const AutoNestedEventLoopAnnotation&) = delete;
+ AutoNestedEventLoopAnnotation& operator=(
+ const AutoNestedEventLoopAnnotation&) = delete;
+
+ // The declarations of these statics live in nsThreadManager.cpp.
+ static AutoNestedEventLoopAnnotation* sCurrent MOZ_GUARDED_BY(sStackMutex);
+ static StaticMutex sStackMutex;
+
+ // We need this to avoid the inclusion of nsExceptionHandler.h here
+ // which can include windows.h which disturbs some dom/media/gtest.
+ // The implementation lives in nsThreadManager.cpp.
+ static void AnnotateXPCOMSpinEventLoopStack(const nsACString& aStack);
+
+ AutoNestedEventLoopAnnotation* mPrev MOZ_GUARDED_BY(sStackMutex);
+ nsCString mStack MOZ_GUARDED_BY(sStackMutex);
+};
+
+// Please see the above notes for the Behavior template parameter.
+//
+// aVeryGoodReasonToDoThis is usually a literal string unique to each
+// caller that can be recognized in the XPCOMSpinEventLoopStack
+// annotation.
+// aPredicate is the condition we wait for.
+// aThread can be used to specify a thread, see the above introduction.
+// It defaults to the current thread.
+template <
+ ProcessFailureBehavior Behavior = ProcessFailureBehavior::ReportToCaller,
+ typename Pred>
+bool SpinEventLoopUntil(const nsACString& aVeryGoodReasonToDoThis,
+ Pred&& aPredicate, nsIThread* aThread = nullptr) {
+ // Prepare the annotations
+ AutoNestedEventLoopAnnotation annotation(aVeryGoodReasonToDoThis);
+ AUTO_PROFILER_LABEL_DYNAMIC_NSCSTRING_NONSENSITIVE(
+ "SpinEventLoopUntil", OTHER, aVeryGoodReasonToDoThis);
+ AUTO_PROFILER_MARKER_TEXT("SpinEventLoop", OTHER, MarkerStack::Capture(),
+ aVeryGoodReasonToDoThis);
+
+ nsIThread* thread = aThread ? aThread : NS_GetCurrentThread();
+
+ // From a latency perspective, spinning the event loop is like leaving script
+ // and returning to the event loop. Tell the watchdog we stopped running
+ // script (until we return).
+ mozilla::Maybe<xpc::AutoScriptActivity> asa;
+ if (NS_IsMainThread()) {
+ asa.emplace(false);
+ }
+
+ while (!aPredicate()) {
+ bool didSomething = NS_ProcessNextEvent(thread, true);
+
+ if (Behavior == ProcessFailureBehavior::IgnoreAndContinue) {
+ // Don't care what happened, continue on.
+ continue;
+ } else if (!didSomething) {
+ return false;
+ }
+ }
+
+ return true;
+}
+
+} // namespace mozilla
+
+#endif // xpcom_threads_SpinEventLoopUntil_h__