path: root/chromium/chrome/browser/ui/webui/discards/discards.mojom

// Copyright 2017 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.

module discards.mojom;

import "chrome/browser/resource_coordinator/lifecycle_unit_state.mojom";
import "mojo/public/mojom/base/process_id.mojom";
import "mojo/public/mojom/base/time.mojom";
import "url/mojom/url.mojom";

// Identical to content::Visibility.
enum LifecycleUnitVisibility {
  HIDDEN = 0,
  OCCLUDED = 1,
  VISIBLE = 2,
};

struct SiteCharacteristicsFeature {
  // The cumulative observation time for this feature in seconds, set to 0 once
  // this feature has been observed.
  int64 observation_duration;
  // The time at which this feature has been used (set to 0 if it hasn't been
  // used), in seconds since epoch.
  int64 use_timestamp;
};

struct SiteCharacteristicsPerformanceMeasurement {
  // A decaying average of the CPU usage measurements. Units: microseconds.
  float avg_cpu_usage_us;
  // A decaying average of the process footprint measurements. Units: kilobytes.
  float avg_footprint_kb;
  // A decaying average of the wall-clock load time duration of the tab.
  // Units: microseconds.
  float avg_load_duration_us;
};

struct SiteCharacteristicsDatabaseSize {
  // The total number of rows in the database, or -1 if the value is not
  // available.
  int64 num_rows;

  // The total size of the database on disk in kilobytes, or -1 if the value
  // is not available.
  int64 on_disk_size_kb;
};

// The data stored for a given origin, this should mirror the
// SiteDataProto structure in
// performance_manager/persistence/site_data/site_data.proto.
struct SiteCharacteristicsDatabaseValue {
  // The last time this site has been in the loaded state, in seconds since
  // epoch.
  uint32 last_loaded;

  SiteCharacteristicsFeature updates_favicon_in_background;
  SiteCharacteristicsFeature updates_title_in_background;
  SiteCharacteristicsFeature uses_audio_in_background;
  SiteCharacteristicsFeature uses_notifications_in_background;

  // Load time performance measurement estimates. This maintains a decaying
  // average of the resource usage of a page until shortly after it becomes
  // idle.
  SiteCharacteristicsPerformanceMeasurement? load_time_estimates;
};

// Provides the key and miscellaneous in-memory only data pertaining to a
// row that potentially exists in a database.
struct SiteCharacteristicsDatabaseEntry {
  // The origin associated with this row.
  string origin;

  // This row is pending flush to disk.
  bool is_dirty;

  // NULL if the database entry doesn't exist on disk or in memory.
  SiteCharacteristicsDatabaseValue? value;
};

// Contains information about a specific DB instance.
struct SiteCharacteristicsDatabase {
  // Contains the entries requested.
  array<SiteCharacteristicsDatabaseEntry> db_rows;
};

// Discard related information about a single tab in a browser.
struct TabDiscardsInfo {
  // The URL associated with the tab. This corresponds to GetLastCommittedURL,
  // and is also what is visible in the Omnibox for a given tab.
  string tab_url;
  // The title of the tab, as displayed on the tab itself.
  string title;
  // The visibility of the LifecycleUnit.
  LifecycleUnitVisibility visibility;
  // The loading state of the LifecycleUnit.
  mojom.LifecycleUnitLoadingState loading_state;
  // The state of the LifecycleUnit.
  mojom.LifecycleUnitState state;
  // Whether the tab can be frozen.
  bool can_freeze;
  // List of human-readable reasons why a tab can't be frozen.
  array<string> cannot_freeze_reasons;
  // Whether the tab can be discarded.
  bool can_discard;
  // List of human-readable reasons why a tab can't be discarded.
  array<string> cannot_discard_reasons;
  // The number of times this tab has been discarded in the current browser
  // session.
  int32 discard_count;
  // If the tab is currently discarded, the discard reason.
  mojom.LifecycleUnitDiscardReason discard_reason;
  // The rank of the tab in the "importance to user" list. The tab with 1 is the
  // most important, the tab with N is the least important.
  int32 utility_rank;
  // The time the tab was last active (foreground in a window), in seconds.
  int32 last_active_seconds;
  // A unique ID for the tab. This is unique for a browser session and follows a
  // tab across tab strip operations, reloads and discards.
  int32 id;
  // Whether or not the tab is eligible for auto-discarding by the browser.
  // This can be manipulated by the chrome://discards UI, or via the discards
  // extension API.
  bool is_auto_discardable;
  // True if a reactivation score is calculated for the tab. Reactivation score
  // can be predicted only for background tabs.
  bool has_reactivation_score;
  // Tab Ranker reactivation score, if |has_reactivation_score| is true.
  double reactivation_score;
  // Site engagement score.
  double site_engagement_score;
  // Whether or not the tab has input focus.
  bool has_focus;
  // Delta between Unix Epoch and time at which the lifecycle state has changed.
  mojo_base.mojom.TimeDelta state_change_time;
};

// Interface for providing information about discards. Lives in the browser
// process and is invoked in the renderer process via Javascript code running in
// the chrome://discards WebUI.
interface DetailsProvider {
  // Returns an array of TabDiscardsInfo containing discard information about
  // each tab currently open in the browser, across all profiles.
  GetTabDiscardsInfo() => (array<TabDiscardsInfo> infos);

  // Returns the in-memory entries and the entries for the requested origins.
  // Note that any entry may take some time to load from disk, and so there may
  // not be any data for a given entry until on the second or subsequent
  // requests.
  GetSiteCharacteristicsDatabase(
      array<string> explicitly_requested_origins) =>
          (SiteCharacteristicsDatabase? result);

  // Returns the size of the database in number of rows and kilobytes.
  // Note that this may be fairly expensive to acquire, and so shouldn't be
  // called frequently.
  GetSiteCharacteristicsDatabaseSize() =>
      (SiteCharacteristicsDatabaseSize? db_size);

  // Sets the auto-discardable state of a tab, as specified by its stable
  // |tab_id|, earlier returned by GetTabDiscardsInfo. Invokes a callback when
  // the change has been made.
  SetAutoDiscardable(int32 tab_id, bool is_auto_discardable) => ();

  // Discards a tab given its |tab_id|. If |urgent| is specified the unload
  // handlers will not be run, and the tab will be unloaded with prejudice.
  // Invokes a callback when the discard is complete.
  DiscardById(int32 tab_id, bool urgent) => ();

  // Freezes a tab given its |tab_id|.
  FreezeById(int32 tab_id);

  // Loads a tab given its |tab_id|.
  LoadById(int32 tab_id);

  // Discards the least important tab. If |urgent| is specified the unload
  // handlers will not be run, and the tab will be unloaded with prejudice.
  // This can fail to discard a tab if no tabs are currently considered
  // eligible for discard. Invokes a callback when the discard is complete, or
  // if the decision was made not to discard.
  Discard(bool urgent) => ();
};

// Represents the momentary state of a Page CU.
struct PageInfo {
  int64 id;

  url.mojom.Url main_frame_url;

  // TODO(siggi): Estimate data.
};

// Represents the momentary state of a Frame CU.
struct FrameInfo {
  int64 id;

  url.mojom.Url url;
  int64 page_id;
  int64 parent_frame_id;
  int64 process_id;
};

// Represents the momentary state of a Process CU.
struct ProcessInfo {
  int64 id;

  mojo_base.mojom.ProcessId pid;
  mojo_base.mojom.TimeDelta cumulative_cpu_usage;
  uint64 private_footprint_kb;
};

// Used to transport favicon data.
struct FavIconInfo {
  int64 node_id;

  // Contains the base64-encoded icon data, suitable for inclusion in a
  // data URL.
  string icon_data;
};

// Implement to receive a stream of notifications when performance manager
// graph nodes are created, changed or deleted.
interface GraphChangeStream {
  // The |frame| was created.
  FrameCreated(FrameInfo frame);
  // The |page| was created.
  PageCreated(PageInfo pages);
  // The |process| was created.
  ProcessCreated(ProcessInfo process);

  // The |frame| changed.
  FrameChanged(FrameInfo frame);
  // The |page| changed.
  PageChanged(PageInfo page);
  // The |process| changed.
  ProcessChanged(ProcessInfo process);

  // A |favicon| became available, whether because the associated page changed
  // its favicon, or because an initial lookup completed.
  FavIconDataAvailable(FavIconInfo favicon);

  // The node with |node_id| was deleted.
  NodeDeleted(int64 node_id);
};

// This interface allows subscribing to a stream of events that track the state
// of the performance manager graph.
interface GraphDump {
  // Subscribes |change_subscriber| to a graph change stream.
  SubscribeToChanges(pending_remote<GraphChangeStream> change_subscriber);
};