mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-12-25 17:43:44 +00:00
211 lines
6.9 KiB
C++
211 lines
6.9 KiB
C++
/* -*- 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
|