components/power_metrics/resource_coalition_mac.h

   1 // Copyright 2021 The Chromium Authors
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // Resource Coalition is an (undocumented) mechanism available in macOS that
   6 // allows retrieving accrued resource usage metrics for a group of processes,
   7 // including processes that have died. Typically, a coalition includes a root
   8 // process and its descendants. The source can help understand the mechanism:
   9 // https://github.com/apple/darwin-xnu/blob/main/osfmk/kern/coalition.c
  10
  11 #ifndef COMPONENTS_POWER_METRICS_RESOURCE_COALITION_MAC_H_
  12 #define COMPONENTS_POWER_METRICS_RESOURCE_COALITION_MAC_H_
  13
  14 #include <stdint.h>
  15 #include <memory>
  16
  17 #include <mach/mach_time.h>
  18
  19 #include "base/process/process_handle.h"
  20 #include "base/time/time.h"
  21 #include "components/power_metrics/resource_coalition_internal_types_mac.h"
  22 #include "third_party/abseil-cpp/absl/types/optional.h"
  23
  24 namespace power_metrics {
  25
  26 struct EnergyImpactCoefficients;
  27
  28 // Returns the coalition id for the process identified by |pid| or nullopt if
  29 // not available.
  30 absl::optional<uint64_t> GetProcessCoalitionId(base::ProcessId pid);
  31
  32 // Returns resource usage data for the coalition identified by |coalition_id|,
  33 // or nullptr if not available (e.g. if `coalition_id` is invalid or if the
  34 // kernel can't allocate memory).
  35 std::unique_ptr<coalition_resource_usage> GetCoalitionResourceUsage(
  36     int64_t coalition_id);
  37
  38 // Returns a `coalition_resource_usage` in which each member is the result of
  39 // subtracting the corresponding fields in `left` and `right`.
  40 coalition_resource_usage GetCoalitionResourceUsageDifference(
  41     const coalition_resource_usage& left,
  42     const coalition_resource_usage& right);
  43
  44 // Struct that contains the rate of resource usage for a coalition.
  45 struct CoalitionResourceUsageRate {
  46   double cpu_time_per_second;
  47   double interrupt_wakeups_per_second;
  48   double platform_idle_wakeups_per_second;
  49   double bytesread_per_second;
  50   double byteswritten_per_second;
  51   double gpu_time_per_second;
  52   // Only makes sense on Intel macs, not computed on M1 macs.
  53   absl::optional<double> energy_impact_per_second;
  54   // Only available on M1 macs as of September 2021.
  55   double power_nw;
  56
  57   double qos_time_per_second[THREAD_QOS_LAST];
  58 };
  59
  60 // Returns rate of resource usage for a coalition, given the usage at
  61 // the beginning and end of an interval and the duration of the interval.
  62 absl::optional<CoalitionResourceUsageRate> GetCoalitionResourceUsageRate(
  63     const coalition_resource_usage& begin,
  64     const coalition_resource_usage& end,
  65     base::TimeDelta interval_duration,
  66     mach_timebase_info_data_t timebase,
  67     absl::optional<EnergyImpactCoefficients> energy_impact_coefficients);
  68
  69 }  // namespace power_metrics
  70
  71 #endif  // COMPONENTS_POWER_METRICS_RESOURCE_COALITION_MAC_H_