// Copyright 2016 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Use the <code>chrome.processes</code> API to interact with the browser's
// processes.
namespace processes {
  // The types of the browser processes.
  enum ProcessType {
    browser,
    renderer,
    extension,
    notification,
    plugin,
    worker,
    nacl,
    service_worker,
    utility,
    gpu,
    other
  };

  // An object that represents a Chrome task running on a process. Several tasks
  // can share the same process.
  dictionary TaskInfo {
    // The title of the task.
    DOMString title;
    // Optional tab ID, if this task represents a tab running on a renderer
    // process.
    long? tabId;
  };

  // The Cache object contains information about the size and utilization of a
  // cache used by the browser.
  dictionary Cache {
    // The size of the cache, in bytes.
    double size;
    // The part of the cache that is utilized, in bytes.
    double liveSize;
  };

  // An object containing information about one of the browser's processes.
  dictionary Process {
    // Unique ID of the process provided by the browser.
    long id;
    // The ID of the process, as provided by the OS.
    long osProcessId;
    // The type of process.
    ProcessType type;
    // The profile which the process is associated with.
    DOMString profile;
    // The debugging port for Native Client processes. Zero for other process
    // types and for NaCl processes that do not have debugging enabled.
    long naclDebugPort;
    // Array of TaskInfos representing the tasks running on this process.
    TaskInfo[] tasks;
    // The most recent measurement of the process’s CPU usage, expressed as the
    // percentage of a single CPU core used in total, by all of the process’s
    // threads. This gives a value from zero to CpuInfo.numOfProcessors*100,
    // which can exceed 100% in multi-threaded processes.
    // Only available when receiving the object as part of a callback from
    // onUpdated or onUpdatedWithMemory.
    double? cpu;
    // The most recent measurement of the process network usage, in bytes per
    // second. Only available when receiving the object as part of a callback
    // from onUpdated or onUpdatedWithMemory.
    double? network;
    // The most recent measurement of the process private memory usage, in
    // bytes. Only available when receiving the object as part of a callback
    // from onUpdatedWithMemory or getProcessInfo with the includeMemory flag.
    double? privateMemory;
    // The most recent measurement of the process JavaScript allocated memory,
    // in bytes. Only available when receiving the object as part of a callback
    // from onUpdated or onUpdatedWithMemory.
    double? jsMemoryAllocated;
    // The most recent measurement of the process JavaScript memory used, in
    // bytes. Only available when receiving the object as part of a callback
    // from onUpdated or onUpdatedWithMemory.
    double? jsMemoryUsed;
    // The most recent measurement of the process’s SQLite memory usage, in
    // bytes. Only available when receiving the object as part of a callback
    // from onUpdated or onUpdatedWithMemory.
    double? sqliteMemory;
    // The most recent information about the image cache for the process. Only
    // available when receiving the object as part of a callback from onUpdated
    // or onUpdatedWithMemory.
    Cache? imageCache;
    // The most recent information about the script cache for the process. Only
    // available when receiving the object as part of a callback from onUpdated
    // or onUpdatedWithMemory.
    Cache? scriptCache;
    // The most recent information about the CSS cache for the process. Only
    // available when receiving the object as part of a callback from onUpdated
    // or onUpdatedWithMemory.
    Cache? cssCache;
  };

  // A callback to report the status of the termination.
  // |didTerminate|: True if terminating the process was successful, and false
  // otherwise.
  callback TerminateCallback = void(boolean didTerminate);

  // A callback to return the ID of the renderer process of a tab.
  // |processId|: Process ID of the tab's renderer process.
  callback GetProcessIdForTabCallback = void(long processId);

  // A callback called when the processes information is collected.
  // |processes|: A dictionary of $(ref:Process) objects for each requested
  // process that is a live child process of the current browser process,
  // indexed by process ID. Metrics requiring aggregation over time will not be
  // populated in each Process object.
  callback GetProcessInfoCallback = void(object processes);

  interface Functions {
    // Returns the ID of the renderer process for the specified tab.
    // |tabId|: The ID of the tab for which the renderer process ID is to be
    // returned.
    static void getProcessIdForTab(long tabId,
                                   GetProcessIdForTabCallback callback);

    // Terminates the specified renderer process. Equivalent to visiting
    // about:crash, but without changing the tab's URL.
    // |processId|: The ID of the process to be terminated.
    static void terminate(long processId, optional TerminateCallback callback);

    // Retrieves the process information for each process ID specified.
    // |processIds|: The list of process IDs or single process ID for which
    // to return the process information. An empty list indicates all processes
    // are requested.
    // |includeMemory|: True if detailed memory usage is required. Note,
    // collecting memory usage information incurs extra CPU usage and should
    // only be queried for when needed.
    static void getProcessInfo((long or long[]) processIds,
                               boolean includeMemory,
                               GetProcessInfoCallback callback);
  };

  interface Events {
    // Fired each time the Task Manager updates its process statistics,
    // providing the dictionary of updated Process objects, indexed by process
    // ID.
    // |processes|: A dictionary of updated $(ref:Process) objects for each live
    // process in the browser, indexed by process ID.  Metrics requiring
    // aggregation over time will be populated in each Process object.
    static void onUpdated(object processes);

    // Fired each time the Task Manager updates its process statistics,
    // providing the dictionary of updated Process objects, indexed by process
    // ID. Identical to onUpdate, with the addition of memory usage details
    // included in each Process object. Note, collecting memory usage
    // information incurs extra CPU usage and should only be listened for when
    // needed.
    // |processes|: A dictionary of updated $(ref:Process) objects for each live
    // process in the browser, indexed by process ID.  Memory usage details will
    // be included in each Process object.
    static void onUpdatedWithMemory(object processes);

    // Fired each time a process is created, providing the corrseponding Process
    // object.
    // |process|: Details of the process that was created. Metrics requiring
    // aggregation over time will not be populated in the object.
    static void onCreated(Process process);

    // Fired each time a process becomes unresponsive, providing the
    // corrseponding Process object.
    // |process|: Details of the unresponsive process. Metrics requiring
    // aggregation over time will not be populated in the object. Only available
    // for renderer processes.
    static void onUnresponsive(Process process);

    // Fired each time a process is terminated, providing the type of exit.
    // |processId|: The ID of the process that exited.
    // |exitType|: The type of exit that occurred for the process - normal,
    // abnormal, killed, crashed. Only available for renderer processes.
    // |exitCode|: The exit code if the process exited abnormally. Only
    // available for renderer processes.
    static void onExited(long processId, long exitType, long exitCode);
  };
};