components/performance_manager/public/mojom/web_memory.mojom

// Copyright 2020 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 performance_manager.mojom;

// All WebMemory* structs below are used for reporting the memory usage of the
// page via the performance.measureMemory Web API. These structs roughly follow
// the structs defined by the specification of the API:
// https://wicg.github.io/performance-measure-memory/
//
// The renderer process invokes the OnWebMemoryMeasurementRequested method of
// DocumentCoordinationUnit from coordination_unit.mojom to send a memory
// measurement request to the browser process. The result of the measurement
// is provided in WebMemoryMeasurement, which attributes the memory usage of
// the page to ExecutionContexts (iframes and workers).
//
// The main invariant is that only the following ExecutionContexts can ever
// appear in the result:
// - same-origin contexts, i.e. those that have the same origin as the context
//   that called the MeasureMemory function.
// - cross-origin contexts with same-origin parent contexts, i.e. iframes that
//   are *immediately* embedded in a same-origin context.
//
// The invariant is important to ensure that cross-origin contexts embedded
// in other cross-origin contexts are not observable to the calling origin.

// Information about ExecutionContext reported in the memory usage breakdown.
struct WebMemoryAttribution {
  // Specifies the scope (or type) of the context.
  enum Scope {
    kCrossOriginAggregated, // Dummy scope for cross-origin iframes.
    kWindow,
    // TODO(1085129): Add worker scopes once they are implemented.
  };
  Scope scope;
  // The current URL of the context. It is null for cross-origin contexts.
  // This is a string instead of url.mojom.Url because it is only used for
  // reporting so there's no need to serialize to GURL, which has a lot of
  // overhead.
  string? url;
  // The src attribute of the container. Can be null if the container has no
  // such attribute.
  string? src;
  // The id attribute of the container. Can be null if the container has no
  // such attribute.
  string? id;
};

// The amount of memory used by a breakdown.
struct WebMemoryUsage {
  uint64 bytes;
};

// Describes a memory region and attributes it to a set of contexts.
// Usually the set consists of a single context. If there are multiple
// contexts then this means that the memory may be owned by any of them.
struct WebMemoryBreakdownEntry {
  // The memory used in this breakdown. It is null for breakdowns that did not
  // have a memory measurement (for example a frame that was added after the
  // measurement started).
  WebMemoryUsage? memory;

  array<WebMemoryAttribution> attribution;
  // TODO(1085129): Add memory types once they are implemented.
};

// The result of the MeasureMemory function.
struct WebMemoryMeasurement {
  // By default a memory measurement may be performed after some delay because
  // it is folded into the next garbage collection. The eager mode is used for
  // testing to force the measurement right away.
  enum Mode {
    kDefault,
    kEager
  };
  array<WebMemoryBreakdownEntry> breakdown;
};