The Tor Browser: comparison xpcom/threads/BackgroundHangMonitor.h

--1:000000000000
+:fca2416ad483
+/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
+/* 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 mozilla_BackgroundHangMonitor_h
+#define mozilla_BackgroundHangMonitor_h
+#include "mozilla/RefPtr.h"
+#include "mozilla/Monitor.h"
+#include <stdint.h>
+namespace mozilla {
+namespace Telemetry {
+class ThreadHangStats;
+};
+// Disabled for Beta/Release builds because of bug 965392.
+// Disabled for debug builds because of bug 979069.
+#if !defined(RELEASE_BUILD) && !defined(DEBUG)
+// Undefine to disable background hang monitor
+#define MOZ_ENABLE_BACKGROUND_HANG_MONITOR
+#endif
+class BackgroundHangThread;
+/**
+* The background hang monitor is responsible for detecting and reporting
+* hangs in background (non-main) threads. A thread registers itself using
+* the BackgroundHangMonitor object and periodically calls its methods to
+* inform the hang monitor of the thread's activity. Each thread is given
+* a thread name, a timeout, and a maximum timeout. If one of the thread's
+* tasks runs for longer than the timeout duration but shorter than the
+* maximum timeout, a (transient) hang is reported. On the other hand, if
+* a task runs for longer than the maximum timeout duration or never
+* finishes (e.g. in a deadlock), a permahang is reported.
+*
+* Tasks are defined arbitrarily, but are typically represented by events
+* in an event loop -- processing one event is equivalent to running one
+* task. To ensure responsiveness, tasks in a thread often have a target
+* running time. This is a good starting point for determining the timeout
+* and maximum timeout values. For example, the Compositor thread has a
+* responsiveness goal of 60Hz or 17ms, so a starting timeout could be
+* 100ms. Considering some platforms (e.g. Android) can terminate the app
+* when a critical thread hangs for longer than a few seconds, a good
+* starting maximum timeout is 4 or 5 seconds.
+*
+* A thread registers itself through the BackgroundHangMonitor constructor.
+* Multiple BackgroundHangMonitor objects can be used in one thread. The
+* constructor without arguments can be used when it is known that the thread
+* already has a BackgroundHangMonitor registered. When all instances of
+* BackgroundHangMonitor are destroyed, the thread is unregistered.
+*
+* The thread then uses two methods to inform BackgroundHangMonitor of the
+* thread's activity:
+*
+*  > BackgroundHangMonitor::NotifyActivity should be called *before*
+*    starting a task. The task run time is determined by the interval
+*    between this call and the next NotifyActivity call.
+*
+*  > BackgroundHangMonitor::NotifyWait should be called *before* the
+*    thread enters a wait state (e.g. to wait for a new event). This
+*    prevents a waiting thread from being detected as hanging. The wait
+*    state is automatically cleared at the next NotifyActivity call.
+*
+* The following example shows hang monitoring in a simple event loop:
+*
+*  void thread_main()
+*  {
+*    mozilla::BackgroundHangMonitor hangMonitor("example1", 100, 1000);
+*    while (!exiting) {
+*      hangMonitor.NotifyActivity();
+*      process_next_event();
+*      hangMonitor.NotifyWait();
+*      wait_for_next_event();
+*    }
+*  }
+*
+* The following example shows reentrancy in nested event loops:
+*
+*  void thread_main()
+*  {
+*    mozilla::BackgroundHangMonitor hangMonitor("example2", 100, 1000);
+*    while (!exiting) {
+*      hangMonitor.NotifyActivity();
+*      process_next_event();
+*      hangMonitor.NotifyWait();
+*      wait_for_next_event();
+*    }
+*  }
+*
+*  void process_next_event()
+*  {
+*    mozilla::BackgroundHangMonitor hangMonitor();
+*    if (is_sync_event) {
+*      while (!finished_event) {
+*        hangMonitor.NotifyActivity();
+*        process_next_event();
+*        hangMonitor.NotifyWait();
+*        wait_for_next_event();
+*      }
+*    } else {
+*      process_nonsync_event();
+*    }
+*  }
+*
+*/
+class BackgroundHangMonitor
+{
+private:
+RefPtr<BackgroundHangThread> mThread;
+public:
+static const uint32_t kNoTimeout = 0;
+/**
+* ThreadHangStatsIterator is used to iterate through the ThreadHangStats
+* associated with each active monitored thread. Because of an internal
+* lock while this object is alive, a thread must use only one instance
+* of this class at a time and must iterate through the list as fast as
+* possible. The following example shows using the iterator:
+*
+* {
+*   // Scope the iter variable so it's destroyed as soon as we're done
+*   BackgroundHangMonitor::ThreadHangStatsIterator iter;
+*   for (ThreadHangStats* histogram = iter.GetNext();
+*        histogram; histogram = iter.GetNext()) {
+*     // Process histogram
+*   }
+* }
+*/
+class ThreadHangStatsIterator : public MonitorAutoLock
+{
+private:
+BackgroundHangThread* mThread;
+ThreadHangStatsIterator(const ThreadHangStatsIterator&);
+ThreadHangStatsIterator& operator=(const ThreadHangStatsIterator&);
+public:
+/**
+* Create an ThreadHangStatsIterator instance and take the internal lock.
+* Internal lock is released on destruction.
+*/
+ThreadHangStatsIterator();
+/**
+* Get the next item in the list; the first call returns the first item.
+* Returns nullptr at the end of the list.
+*/
+Telemetry::ThreadHangStats* GetNext();
+};
+/**
+* Enable hang monitoring.
+* Must return before using BackgroundHangMonitor.
+*/
+static void Startup();
+/**
+* Disable hang monitoring.
+* Can be called without destroying all BackgroundHangMonitors first.
+*/
+static void Shutdown();
+/**
+* Start monitoring hangs for the current thread.
+*
+* @param aName Name to identify the thread with
+* @param aTimeoutMs Amount of time in milliseconds without
+*  activity before registering a hang
+* @param aMaxTimeoutMs Amount of time in milliseconds without
+*  activity before registering a permanent hang
+*/
+BackgroundHangMonitor(const char* aName,
+uint32_t aTimeoutMs,
+uint32_t aMaxTimeoutMs);
+/**
+* Monitor hangs using an existing monitor
+* associated with the current thread.
+*/
+BackgroundHangMonitor();
+/**
+* Destroys the hang monitor; hang monitoring for a thread stops
+* when all monitors associated with the thread are destroyed.
+*/
+~BackgroundHangMonitor();
+/**
+* Notify the hang monitor of pending current thread activity.
+* Call this method before starting an "activity" or after
+* exiting from a wait state.
+*/
+void NotifyActivity();
+/**
+* Notify the hang monitor of current thread wait.
+* Call this method before entering a wait state; call
+* NotifyActivity when subsequently exiting the wait state.
+*/
+void NotifyWait();
+};
+} // namespace mozilla
+#endif // mozilla_BackgroundHangMonitor_h

The Tor Browser / file comparison

comparison: xpcom/threads/BackgroundHangMonitor.h

xpcom/threads/BackgroundHangMonitor.h