services/resource_coordinator/public/mojom/coordination_unit.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 resource_coordinator.mojom;

import "mojo/public/mojom/base/process_id.mojom";
import "mojo/public/mojom/base/time.mojom";
import "services/resource_coordinator/public/mojom/lifecycle.mojom";
import "services/resource_coordinator/public/mojom/signals.mojom";

// Any new type here needs to be mirrored between coordination_unit_types.h and
// coordination_unit.mojom, and have mappings between the two defined in
// coordination_unit_mojom_traits.h/.cc (see comment in coordination_unit_id.h).
enum CoordinationUnitType {
  kFrame,
  kPage,
  kProcess,
  kSystem,
};

// Intervention policy status. This mirrors the definitions used by the
// InterventionPolicyDatabase defined in
// chrome/browser/resource_coordinator/intervention_policy_database.proto
enum InterventionPolicy {
  // The frame/page policy is yet unknown. This is the state while a frame is
  // still loading.
  kUnknown,
  // The frame/page has explicitly opted-in to an intervention.
  kOptIn,
  // The frame/page has explicitly opted-out from an intervention.
  kOptOut,
  // The frame/page has neither opted-in or opted-out. The intervention will be
  // applied usings its own heuristics.
  kDefault,
};

// A list of interventions for which policy is communicated from individual
// frames and propagated through the frame tree. As each frame loads it will
// communicate the policy state to the associated FrameCoordinationUnit, and
// these will eventually be aggregated to the parent PageCoordinationUnit and
// applied to an entire frame tree.
enum PolicyControlledIntervention {
  // Page lifecycles is a feature that causes pages to transition through
  // lifecycle states in an attempt to save/reclaim resources.
  kPageLifecycleTransitions,
};

struct CoordinationUnitID {
  CoordinationUnitType type;
  int64 id;
};

struct ProcessResourceMeasurement {
  // Identifies the process associated with this measurement.
  mojo_base.mojom.ProcessId pid;

  // The cumulative CPU usage accrued to this process from its start.
  mojo_base.mojom.TimeDelta cpu_usage;

  // The private memory footprint of the process.
  uint32 private_footprint_kb = 0;
};

struct ProcessResourceMeasurementBatch {
  // These times bracket the capture of the entire dump, e.g. each distinct
  // measurement is captured somewhere between |batch_started_time| and
  // |batch_ended_time|.
  mojo_base.mojom.TimeTicks batch_started_time;
  mojo_base.mojom.TimeTicks batch_ended_time;

  array<ProcessResourceMeasurement> measurements;
};

// A FrameCoordinationUnit has at most one ProcessCoordinationUnit as its
// parent, at most one PageCoordinationUnit as its parent, at most one
// FrameCoordinationUnit as parent frame, and can have many child frames.
interface FrameCoordinationUnit {
  // Mainly used to force a round-trip to the service over the pipe for
  // a specific unit, so we don't have to deal with possibly-not-yet-created
  // children.
  GetID() => (CoordinationUnitID id);

  // Sets the process hosting this frame.
  SetProcess(CoordinationUnitID id);

  // Add a new binding to an existing FrameCoordinationUnit.
  AddBinding(FrameCoordinationUnit& request);
  AddChildFrame(CoordinationUnitID cu_id);
  RemoveChildFrame(CoordinationUnitID cu_id);

  // Property signals.
  SetNetworkAlmostIdle(bool idle);
  SetLifecycleState(LifecycleState state);
  SetHasNonEmptyBeforeUnload(bool has_nonempty_beforeunload);
  SetInterventionPolicy(PolicyControlledIntervention intervention,
                        InterventionPolicy policy);

  // Event signals.
  OnNonPersistentNotificationCreated();
};

interface PageCoordinationUnit {
  // Mainly used to force a round-trip to the service over the pipe for
  // a specific unit, so we don't have to deal with possibly-not-yet-created
  // children.
  GetID() => (CoordinationUnitID id);

  // Add a new binding to an existing PageCoordinationUnit.
  AddBinding(PageCoordinationUnit& request);
  AddFrame(CoordinationUnitID cu_id);
  RemoveFrame(CoordinationUnitID cu_id);

  // Property signals.
  SetIsLoading(bool is_loading);
  SetVisibility(bool visible);
  SetUKMSourceId(int64 ukm_source_id);

  // Event signals.
  OnFaviconUpdated();
  OnTitleUpdated();

  // |navigation_committed_time| is the time when the commit occurred.
  // |navigation_id| is the unique ID of the navigation handle that was
  // committed.
  OnMainFrameNavigationCommitted(
      mojo_base.mojom.TimeTicks navigation_committed_time,
      int64 navigation_id, string url);
};

interface ProcessCoordinationUnit {
  // Mainly used to force a round-trip to the service over the pipe for
  // a specific unit, so we don't have to deal with possibly-not-yet-created
  // children.
  GetID() => (CoordinationUnitID id);

  // Add a new binding to an existing ProcessCoordinationUnit.
  AddBinding(ProcessCoordinationUnit& request);

  // Property signals.
  SetCPUUsage(double cpu_usage);
  SetExpectedTaskQueueingDuration(mojo_base.mojom.TimeDelta duration);
  SetLaunchTime(mojo_base.mojom.Time launch_time);
  SetMainThreadTaskLoadIsLow(bool main_thread_task_load_is_low);
  SetPID(mojo_base.mojom.ProcessId pid);
  // Called when the process is known to have died or to have failed to start.
  SetProcessExitStatus(int32 exit_status);

  // Event signals.

  // Fired when one of the renderer heaps is about to exceed its limit.
  // If nothing is done, then the renderer is likely to crash with OOM.
  OnRendererIsBloated();
};

// There is exactly one SystemCoordinationUnit at all times.
interface SystemCoordinationUnit {
  // Gets the ID of this coordination unit.
  GetID() => (CoordinationUnitID id);

  // Add a new binding to an existing SystemCoordinationUnit.
  AddBinding(SystemCoordinationUnit& request);

  // Event signals.

  // Fired when all ProcessCUs have been adorned with consistent CPU usage
  // metrics. This allows for subsequent heuristics to propagate these
  // measurements to PageCUs via a heuristic.
  OnProcessCPUUsageReady();

  // Distributes a measurement batch onto the CU graph. This may generate
  // events.
  DistributeMeasurementBatch(ProcessResourceMeasurementBatch measurement_batch);
};