/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim:set ts=2 sw=2 sts=2 et cindent: */
/* 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"

webidl FrameLoader;
webidl Element;

/**
 * When a content process hangs, Gecko notifies "process-hang-report" observers
 * and passes an nsIHangReport for the subject parameter. There is at most one
 * nsIHangReport associated with a given content process. As long as the content
 * process stays stuck, the "process-hang-report" observer will continue to be
 * notified at regular intervals (approximately once per second). The content
 * process will continue to run uninhibitedly during this time.
 */

[scriptable, uuid(5fcffbb9-be62-49b1-b8a1-36e820787a74)]
interface nsIHangReport : nsISupports
{
  const unsigned long SLOW_SCRIPT = 1;
  const unsigned long PLUGIN_HANG = 2;

  // The type of hang being reported: SLOW_SCRIPT or PLUGIN_HANG.
  readonly attribute unsigned long hangType;

  // For SLOW_SCRIPT reports, these fields contain information about the
  // slow script.
  // Only valid for SLOW_SCRIPT reports.
  readonly attribute Element scriptBrowser;
  readonly attribute ACString scriptFileName;
  // Duration of the hang so far.
  readonly attribute double hangDuration;
  readonly attribute AString addonId;

  // For PLUGIN_HANGs, this field contains information about the plugin.
  // Only valid for PLUGIN_HANG reports.
  readonly attribute ACString pluginName;

  // The child id of the process in which the hang happened.
  readonly attribute unsigned long long childID;

  // Called by front end code when user ignores or cancels
  // the notification.
  void userCanceled();

  // Terminate the slow script if it is still running.
  // Only valid for SLOW_SCRIPT reports.
  void terminateScript();

  // Terminate all scripts on the global that triggered the slow script
  // warning.
  // Only valid for SLOW_SCRIPT reports.
  void terminateGlobal();

  // Terminate the plugin if it is still hung.
  // Only valid for PLUGIN_HANG reports.
  void terminatePlugin();

  // Ask the content process to start up the slow script debugger.
  // Only valid for SLOW_SCRIPT reports.
  void beginStartingDebugger();

  // Inform the content process that the slow script debugger has finished
  // spinning up. The content process will run a nested event loop until this
  // method is called.
  // Only valid for SLOW_SCRIPT reports.
  void endStartingDebugger();

  // Inquire whether the report is for a content process loaded by the given
  // frameloader.
  bool isReportForBrowser(in FrameLoader aFrameLoader);
};