chromium/components/services/heap_profiling/public/mojom/heap_profiling_client.mojom

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

module heap_profiling.mojom;

// The data that is recorded for an allocation stack.
enum StackMode {
  // Instruction addresses from unwinding the stack. Includes the thread name as
  // the first frame.
  NATIVE_WITH_THREAD_NAMES,

  // Instruction addresses from unwinding the stack.
  NATIVE_WITHOUT_THREAD_NAMES,
};

// Type of the allocator responsible for the allocation sample.
enum AllocatorType {
  kMalloc,
  kPartitionAlloc,
};

// A wrapper for parameters that affect each client's implementation of
// profiling.
struct ProfilingParams {
  // |stack_mode| refers to the type of data that should be recorded for each
  // allocation.
  StackMode stack_mode;

  // The sampling rate is used to determined the probability of sampling an
  // allocation. Probability = min((size of allocation) / (sampling interval),
  // 1). A sampling rate of |1| is equivalent to sampling all alloations. A
  // sampling rate of |0| is invalid and will be treated as |1|.
  uint32 sampling_rate;
};

// A single memory allocation sample.
struct HeapProfileSample {
  // Allocator type.
  AllocatorType allocator;

  // The size of the allocation.
  uint64 size;

  // The total bytes attributed to the desampled allocation. Each sampled
  // allocation represents a series of similar allocations. Dividing |total| by
  // |size| yields the expected number of allocations.
  uint64 total;

  // Id of the context string.
  uint64 context_id;

  // Program stack in top to bottom order recorded for the allocation.
  // Each element of the |stack| is either a PC memory address or a string
  // if it is among the |strings| map items of |HeapProfile|.
  array<uint64> stack;
};

// Heap profile data. Can be retrieved from the client with
// |RetrieveHeapProfile| method.
struct HeapProfile {
  // Samples recorded for the profile.
  array<HeapProfileSample> samples;

  // Strings used within the profile.
  map<uint64, string> strings;
};

// This interface is implemented by "memlog clients" (profiled processes that
// can send memory allocation events to the profiling process). These functions
// are called by the profiling process to control the senders.
interface ProfilingClient {
  // Start recording allocations.
  // Collected allocations are either streamed to the profiling process via
  // |params.sender_pipe|, or accumulated in the profiled process depending on
  // the |params.use_in_process_storage|.
  // There is currently no mechanism to stop recording allocations.
  StartProfiling(ProfilingParams params) => ();

  // Captures and returns a snapshot of the heap profile of the current process.
  RetrieveHeapProfile() => (HeapProfile profile);

  // Captures a snapshot of the heap profile and adds to Perfetto traces in
  // proto format.
  AddHeapProfileToTrace() => (bool success);
};