Add m-esr52 at 52.6.0

1 files changed, 333 insertions, 0 deletions

diff --git a/toolkit/components/perfmonitoring/nsIPerformanceStats.idl b/toolkit/components/perfmonitoring/nsIPerformanceStats.idl
new file mode 100644
index 000000000..2effd5403
--- /dev/null
+++ b/toolkit/components/perfmonitoring/nsIPerformanceStats.idl
@@ -0,0 +1,333 @@
+/* -*- indent-tabs-mode: nil; js-indent-level: 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/. */
+
+#include "nsISupports.idl"
+#include "nsIArray.idl"
+#include "nsIDOMWindow.idl"
+
+/**
+ * Mechanisms for querying the current process about performance
+ * information.
+ *
+ * JavaScript clients should rather use PerformanceStats.jsm.
+ */
+
+/**
+ * Identification details for a performance group.
+ *
+ * A performance group is a set of JavaScript compartments whose
+ * performance is observed as a single entity. Typical examples of
+ * performance groups: an add-on, a webpage without its frames, a
+ * webpage with all its frames, the entire JS runtime, ...
+ */
+[scriptable, builtinclass, uuid(994c56be-939a-4f20-8364-124f6422d86a)]
+interface nsIPerformanceGroupDetails: nsISupports {
+  /**
+   * An identifier unique to the component.
+   *
+   * This identifier is somewhat human-readable to aid with debugging,
+   * but clients should not rely upon the format.
+   */
+  readonly attribute AString groupId;
+
+  /**
+   * A somewhat human-readable name for the component.
+   */
+  readonly attribute AString name;
+
+  /**
+   * If the component is an add-on, the ID of the addon,
+   * otherwise an empty string.
+   */
+  readonly attribute AString addonId;
+
+  /**
+   * If the component is code executed in a window, the ID of the topmost
+   * outer window (i.e. the tab), otherwise 0.
+   */
+  readonly attribute uint64_t windowId;
+
+  /**
+   * `true` if this component is executed with system privileges
+   * (e.g. the platform itself or an add-on), `false` otherwise
+   * (e.g. webpages).
+   */
+  readonly attribute bool isSystem;
+
+  /**
+   * The process running this group.
+   */
+  readonly attribute unsigned long long processId;
+
+  /**
+   * `true` if the code is executed in a content process, `false` otherwise.
+   */
+  readonly attribute bool isContentProcess;
+};
+
+/**
+ * Snapshot of the performance of a component, e.g. an add-on, a web
+ * page, system built-ins, a module or the entire process itself.
+ *
+ * All values are monotonic and are updated only when
+ * `nsIPerformanceStatsService.isStopwatchActive` is `true`.
+ */
+[scriptable, builtinclass, uuid(8a635d4b-aa56-466b-9a7d-9f91ca9405ef)]
+interface nsIPerformanceStats: nsIPerformanceGroupDetails {
+  /**
+   * Total amount of time spent executing code in this group, in
+   * microseconds.
+   */
+  readonly attribute unsigned long long totalUserTime;
+  readonly attribute unsigned long long totalSystemTime;
+  readonly attribute unsigned long long totalCPOWTime;
+
+  /**
+   * Total number of times code execution entered this group,
+   * since process launch. This may be greater than the number
+   * of times we have entered the event loop.
+   */
+  readonly attribute unsigned long long ticks;
+
+  /**
+   * Jank indicator.
+   *
+   * durations[i] == number of times execution of this group
+   * lasted at lest 2^i ms.
+   */
+  void getDurations([optional] out unsigned long aCount,
+                    [retval, array, size_is(aCount)]out unsigned long long aNumberOfOccurrences);
+};
+
+/**
+ * A snapshot of the performance data of the process.
+ */
+[scriptable, builtinclass, uuid(13cc235b-739e-4690-b0e3-d89cbe036a93)]
+interface nsIPerformanceSnapshot: nsISupports {
+  /**
+   * Data on all individual components.
+   */
+  nsIArray getComponentsData();
+
+  /**
+   * Information on the process itself.
+   *
+   * This contains the total amount of time spent executing JS code,
+   * the total amount of time spent waiting for system calls while
+   * executing JS code, the total amount of time performing blocking
+   * inter-process calls, etc.
+   */
+  nsIPerformanceStats getProcessData();
+};
+
+/**
+ * A performance alert.
+ */
+[scriptable, builtinclass, uuid(a85706ab-d703-4687-8865-78cd771eab93)]
+interface nsIPerformanceAlert: nsISupports {
+ /**
+  * A slowdown was detected.
+  *
+  * See REASON_JANK_* for details on whether this slowdown was user-noticeable.
+  */
+  const unsigned long REASON_SLOWDOWN = 1;
+
+  /**
+   * This alert was triggered during a jank in animation.
+   *
+   * In the current implementation, we consider that there is a jank
+   * in animation if delivery of the vsync message to the main thread
+   * has been delayed too much (see
+   * nsIPerformanceStatsService.animationJankLevelThreshold).
+   *
+   * Note that this is a heuristic which may provide false positives,
+   * so clients of this API are expected to perform post-processing to
+   * filter out such false positives.
+   */
+  const unsigned long REASON_JANK_IN_ANIMATION = 2;
+
+  /**
+   * This alert was triggered during a jank in user input.
+   *
+   * In the current implementation, we consider that there is a jank
+   * in animation if a user input was received either immediately
+   * before executing the offending code (see
+   * nsIPerformanceStatsService.userInputDelayThreshold) or while
+   * executing the offending code.
+   *
+   * Note that this is a heuristic which may provide false positives,
+   * so clients of this API are expected to perform post-processing to
+   * filter out such false positives.
+   */
+  const unsigned long REASON_JANK_IN_INPUT = 4;
+
+  /**
+   * The reason for the alert, as a bitwise or of the various REASON_*
+   * constants.
+   */
+  readonly attribute unsigned long reason;
+
+  /**
+   * Longest interval spent executing code in this group
+   * since the latest alert, in microseconds.
+   *
+   * Note that the underlying algorithm is probabilistic and may
+   * provide false positives, so clients of this API are expected to
+   * perform post-processing to filter out such false positives. In
+   * particular, a high system load will increase the noise level on
+   * this measure.
+   */
+  readonly attribute unsigned long long highestJank;
+
+  /**
+   * Longest interval spent executing CPOW in this group
+   * since the latest alert, in microseconds.
+   *
+   * This measure is reliable and involves no heuristics. However,
+   * note that the duration of CPOWs is increased by high system
+   * loads.
+   */
+  readonly attribute unsigned long long highestCPOW;
+};
+
+
+/**
+ * An observer for slow performance alerts.
+ */
+[scriptable, function, uuid(b746a929-3fec-420b-8ed8-c35d71995e05)]
+interface nsIPerformanceObserver: nsISupports {
+  /**
+   * @param target The performance group that caused the jank.
+   * @param alert The performance cost that triggered the alert.
+   */
+  void observe(in nsIPerformanceGroupDetails target, in nsIPerformanceAlert alert);
+};
+
+
+/**
+ * A part of the system that may be observed for slow performance.
+ */
+[scriptable, builtinclass, uuid(b85720d0-e328-4342-9e46-8ca1acf8c70e)]
+interface nsIPerformanceObservable: nsISupports {
+  /**
+   * If a single group is being observed, information on this group.
+   */
+  readonly attribute nsIPerformanceGroupDetails target;
+
+  /**
+   * Add an observer that will be informed in case of jank.
+   *
+   * Set `jankAlertThreshold` to determine how much jank is needed
+   * to trigger alerts.
+   *
+   * If the same observer is added more than once, it will be
+   * triggered as many times as it has been added.
+   */
+  void addJankObserver(in nsIPerformanceObserver observer);
+
+  /**
+   * Remove an observer previously added with `addJankObserver`.
+   *
+   * Noop if the observer hasn't been added.
+   */
+  void removeJankObserver(in nsIPerformanceObserver observer);
+};
+
+
+[scriptable, uuid(505bc42e-be38-4a53-baba-92cb33690cde)]
+interface nsIPerformanceStatsService : nsISupports {
+  /**
+   * `true` if we should monitor CPOW, `false` otherwise.
+   */
+  [implicit_jscontext] attribute bool isMonitoringCPOW;
+
+  /**
+   * `true` if we should monitor jank, `false` otherwise.
+   */
+  [implicit_jscontext] attribute bool isMonitoringJank;
+
+  /**
+   * `true` if all compartments need to be monitored individually,
+   * `false` if only performance groups (i.e. entire add-ons, entire
+   * webpages, etc.) need to be monitored.
+   */
+  [implicit_jscontext] attribute bool isMonitoringPerCompartment;
+
+  /**
+   * Capture a snapshot of the performance data.
+   */
+  [implicit_jscontext] nsIPerformanceSnapshot getSnapshot();
+
+  /**
+   * The threshold, in microseconds, above which a performance group is
+   * considered "slow" and should raise performance alerts.
+   */
+  attribute unsigned long long jankAlertThreshold;
+
+  /**
+   * If a user is seeing an animation and we spend too long executing
+   * JS code while blocking refresh, this will be visible to the user.
+   *
+   * We assume that any jank during an animation and lasting more than
+   * 2^animationJankLevelThreshold ms will be visible.
+   */
+  attribute short animationJankLevelThreshold;
+
+  /**
+   * If a user performs an input (e.g. clicking, pressing a key, but
+   * *NOT* moving the mouse), and we spend too long executing JS code
+   * before displaying feedback, this will be visible to the user even
+   * if there is no ongoing animation.
+   *
+   * We assume that any jank during `userInputDelayThreshold` us after
+   * the user input will be visible.
+   */
+  attribute unsigned long long userInputDelayThreshold;
+
+  /**
+   * A buffering delay, in milliseconds, used by the service to
+   * regroup performance alerts, before observers are actually
+   * noticed. Higher delays let the system avoid redundant
+   * notifications for the same group, and are generally better for
+   * performance.
+   */
+  attribute unsigned long jankAlertBufferingDelay;
+
+  /**
+   * Get a nsIPerformanceObservable representing an add-on. This
+   * observable may then be used to (un)register for watching
+   * performance alerts for this add-on.
+   *
+   * Note that this method has no way of finding out whether an add-on with this
+   * id is installed on the system. Also note that this covers only the current
+   * process.
+   *
+   * Use special add-on name "*" to get an observable that may be used
+   * to (un)register for watching performance alerts of all add-ons at
+   * once.
+   */
+  nsIPerformanceObservable getObservableAddon(in AString addonId);
+
+  /**
+   * Get a nsIPerformanceObservable representing a DOM window. This
+   * observable may then be used to (un)register for watching
+   * performance alerts for this window.
+   *
+   * Note that this covers only the current process.
+   *
+   * Use special window id 0 to get an observable that may be used to
+   * (un)register for watching performance alerts of all windows at
+   * once.
+   */
+  nsIPerformanceObservable getObservableWindow(in unsigned long long windowId);
+};
+
+
+%{C++
+#define NS_TOOLKIT_PERFORMANCESTATSSERVICE_CID {0xfd7435d4, 0x9ec4, 0x4699, \
+      {0xad, 0xd4, 0x1b, 0xe8, 0x3d, 0xd6, 0x8e, 0xf3} }
+#define NS_TOOLKIT_PERFORMANCESTATSSERVICE_CONTRACTID "@mozilla.org/toolkit/performance-stats-service;1"
+%}