性能提示管理器

APerformanceHint 允许应用为线程组创建性能提示会话，并向系统提供有关这些线程工作负载的提示，以帮助系统更准确地为它们分配电力。

摘要

它是 Java PerformanceHintManager SDK API 在 NDK 中的对应项。

类型定义
`APerformanceHintManager`	typedef `struct APerformanceHintManager` 表示性能提示管理器句柄的不透明类型。
`APerformanceHintSession`	typedef `struct APerformanceHintSession` 表示性能提示会话句柄的不透明类型。
`AWorkDuration`	typedef `struct AWorkDuration` AWorkDuration 是一种不透明类型，表示内部每个组件的实际工作负载持续时间的细分。

函数
`APerformanceHint_closeSession(APerformanceHintSession *_Nonnull session)`	`void` 释放通过 APerformanceHint_createSession 获取的性能提示管理器指针。
`APerformanceHint_createSession(APerformanceHintManager _Nonnull manager, const int32_t _Nonnull threadIds, size_t size, int64_t initialTargetWorkDurationNanos)`	`APerformanceHintSession *_Nullable` 为给定线程集创建会话并设置其初始目标工作时长。
`APerformanceHint_getManager()`	`APerformanceHintManager *_Nullable` 获取性能提示管理器的实例。
`APerformanceHint_getPreferredUpdateRateNanos(APerformanceHintManager *_Nonnull manager)`	`int64_t` 获取此设备支持的首选更新速率信息。
`APerformanceHint_reportActualWorkDuration(APerformanceHintSession *_Nonnull session, int64_t actualDurationNanos)`	`int` 报告上一个工作周期的实际持续时间。
`APerformanceHint_reportActualWorkDuration2(APerformanceHintSession _Nonnull session, AWorkDuration _Nonnull workDuration)`	`int` 报告上一个工作周期的时长。
`APerformanceHint_setPreferPowerEfficiency(APerformanceHintSession *_Nonnull session, bool enabled)`	`int` 这告诉会话，可以安全地将这些线程调度为优先选择电源效率而不是性能。
`APerformanceHint_setThreads(APerformanceHintSession _Nonnull session, const pid_t _Nonnull threadIds, size_t size)`	`int` 为性能提示会话设置线程列表。
`APerformanceHint_updateTargetWorkDuration(APerformanceHintSession *_Nonnull session, int64_t targetDurationNanos)`	`int` 更新此会话每个工作周期的目标持续时间。
`AWorkDuration_create()`	`AWorkDuration *_Nonnull` 创建新的 AWorkDuration。
`AWorkDuration_release(AWorkDuration *_Nonnull aWorkDuration)`	`void` 销毁 AWorkDuration 并释放与其关联的所有资源。
`AWorkDuration_setActualCpuDurationNanos(AWorkDuration *_Nonnull aWorkDuration, int64_t actualCpuDurationNanos)`	`void` 设置实际 CPU 工作持续时间（以纳秒为单位）。
`AWorkDuration_setActualGpuDurationNanos(AWorkDuration *_Nonnull aWorkDuration, int64_t actualGpuDurationNanos)`	`void` 设置实际 GPU 工作持续时间（以纳秒为单位）。
`AWorkDuration_setActualTotalDurationNanos(AWorkDuration *_Nonnull aWorkDuration, int64_t actualTotalDurationNanos)`	`void` 设置实际总工作持续时间（以纳秒为单位）。
`AWorkDuration_setWorkPeriodStartTimestampNanos(AWorkDuration *_Nonnull aWorkDuration, int64_t workPeriodStartTimestampNanos)`	`void` 设置工作周期开始时间戳（以纳秒为单位）。

类型定义

APerformanceHintManager

声明位于 android/performance_hint.h

struct APerformanceHintManager APerformanceHintManager

表示性能提示管理器句柄的不透明类型。

用法

调用 APerformanceHint_getManager 函数获取性能提示管理器实例。
使用 APerformanceHint_createSession 创建 APerformanceHintSession。
使用 APerformanceHint_getPreferredUpdateRateNanos 获取首选更新速率（以纳秒为单位）。

APerformanceHintSession

声明位于 android/performance_hint.h

struct APerformanceHintSession APerformanceHintSession

表示性能提示会话句柄的不透明类型。

会话只能通过 APerformanceHint_createSession 从 APerformanceHintManager 获取。使用后必须通过 APerformanceHint_closeSession 释放。

会话表示具有相互关联工作负载的线程组，因此应对其性能提示作为一个单元进行考虑。给定会话中的线程应该是长期存在的，而不是动态创建或销毁的。

工作时长 API 可用于周期性工作负载，以动态调整线程性能并使工作按计划进行，同时优化可用的电源预算。使用工作时长 API 时，应在创建会话时指定初始目标时长，并随后可以使用 APerformanceHint_updateTargetWorkDuration 进行调整。在使用工作时长 API 时，客户端应在每个周期调用 APerformanceHint_reportActualWorkDuration 向系统报告完成实际花费的时间。

注意，APerformanceHintSession_* 的方法不是线程安全的，因此调用者必须确保线程安全。

所有计时都应来自 std::chrono::steady_clock 或 clock_gettime(CLOCK_MONOTONIC, ...)

AWorkDuration

声明位于 android/performance_hint.h

struct AWorkDuration AWorkDuration

AWorkDuration 是一种不透明类型，表示内部每个组件的实际工作负载持续时间的细分。

可以使用 AWorkDuration_create() 获取新的 AWorkDuration；当客户端完成使用 AWorkDuration 时，必须调用 AWorkDuration_release() 来销毁 AWorkDuration 并释放与其关联的所有资源。

此文件提供了一组函数，允许客户端设置 AWorkDuration 上每个组件的测量工作时长。

函数

APerformanceHint_closeSession

声明位于 android/performance_hint.h

void APerformanceHint_closeSession(
  APerformanceHintSession *_Nonnull session
)

释放通过 APerformanceHint_createSession 获取的性能提示管理器指针。

详情

参数

session

要释放的性能提示会话实例。

APerformanceHint_createSession

声明位于 android/performance_hint.h

APerformanceHintSession *_Nullable APerformanceHint_createSession(
  APerformanceHintManager *_Nonnull manager,
  const int32_t *_Nonnull threadIds,
  size_t size,
  int64_t initialTargetWorkDurationNanos
)

为给定线程集创建会话并设置其初始目标工作时长。

详情

参数

`manager`	性能提示管理器实例。
`threadIds`	与此会话关联的线程列表。它们必须是此进程线程组的一部分。
`size`	threadIds 列表的大小。
`initialTargetWorkDurationNanos`	新会话的目标持续时间（以纳秒为单位）。如果使用工作时长 API，此值必须为正数，否则为 0。

返回值

成功时返回 APerformanceHintManager 实例，失败时返回 nullptr。

APerformanceHint_getManager

声明位于 android/performance_hint.h

APerformanceHintManager *_Nullable APerformanceHint_getManager()

获取性能提示管理器的实例。

详情
返回值	成功时返回 APerformanceHintManager 实例，失败时返回 nullptr。

APerformanceHint_getPreferredUpdateRateNanos

声明位于 android/performance_hint.h

int64_t APerformanceHint_getPreferredUpdateRateNanos(
  APerformanceHintManager *_Nonnull manager
)

获取此设备支持的首选更新速率信息。

详情

参数

manager

性能提示管理器实例。

返回值

设备软件支持的首选更新速率。

APerformanceHint_reportActualWorkDuration

声明位于 android/performance_hint.h

int APerformanceHint_reportActualWorkDuration(
  APerformanceHintSession *_Nonnull session,
  int64_t actualDurationNanos
)

报告上一个工作周期的实际持续时间。

系统将尝试调整线程组内线程的调度和性能，以使实际持续时间接近目标持续时间。

详情

参数

`session`	要更新的性能提示会话实例。
`actualDurationNanos`	线程组完成其上一个任务所花费的时间（以纳秒为单位）。此值必须为正数。

返回值

成功时返回 0。如果 actualDurationNanos 不是正数，则返回 EINVAL。如果与系统服务的通信失败，则返回 EPIPE。

APerformanceHint_reportActualWorkDuration2

声明位于 android/performance_hint.h

int APerformanceHint_reportActualWorkDuration2(
  APerformanceHintSession *_Nonnull session,
  AWorkDuration *_Nonnull workDuration
)

报告上一个工作周期的时长。

系统将尝试调整线程组内线程的调度和性能，以使实际持续时间接近目标持续时间。

工作周期开始时间戳和实际总持续时间必须大于零。

详情

参数

`session`	要更新的 APerformanceHintSession 实例。
`workDuration`	AWorkDuration 结构体，其中包含线程组完成其上一个任务所花费的时间（以纳秒为单位），并分解为不同的组件。

实际 CPU 和 GPU 持续时间必须大于或等于零，并且其中至少一个必须大于零。当其中一个等于零时，表示此工作负载未测量该类型的工作。

详情
返回值	成功时返回 0。如果任何持续时间是无效数字，则返回 EINVAL。如果与系统服务的通信失败，则返回 EPIPE。

APerformanceHint_setPreferPowerEfficiency

声明位于 android/performance_hint.h

int APerformanceHint_setPreferPowerEfficiency(
  APerformanceHintSession *_Nonnull session,
  bool enabled
)

这告诉会话，可以安全地将这些线程调度为优先选择电源效率而不是性能。

详情

参数

`session`	要更新的性能提示会话实例。
`enabled`	用于设置此会话是否使用电源高效调度的标志。

返回值

成功时返回 0。如果与系统服务的通信失败，则返回 EPIPE。

APerformanceHint_setThreads

声明位于 android/performance_hint.h

int APerformanceHint_setThreads(
  APerformanceHintSession *_Nonnull session,
  const pid_t *_Nonnull threadIds,
  size_t size
)

为性能提示会话设置线程列表。

此操作将使用给定的线程列表替换当前的线程列表。

详情

参数

`session`	要更新的性能提示会话实例。
`threadIds`	与此会话关联的线程列表。它们必须是此应用线程组的一部分。
`size`	threadIds 列表的大小。

返回值

成功时返回 0。如果线程 ID 列表为空或任何线程 ID 不属于线程组，则返回 EINVAL。如果与系统服务的通信失败，则返回 EPIPE。如果任何线程 ID 不属于该应用，则返回 EPERM。

APerformanceHint_updateTargetWorkDuration

声明位于 android/performance_hint.h

int APerformanceHint_updateTargetWorkDuration(
  APerformanceHintSession *_Nonnull session,
  int64_t targetDurationNanos
)

更新此会话每个工作周期的目标持续时间。

详情

参数

`session`	要更新的性能提示会话实例。
`targetDurationNanos`	新的所需持续时间（以纳秒为单位）。此值必须为正数。

返回值

成功时返回 0。如果 targetDurationNanos 不是正数，则返回 EINVAL。如果与系统服务的通信失败，则返回 EPIPE。

AWorkDuration_create

声明位于 android/performance_hint.h

AWorkDuration *_Nonnull AWorkDuration_create()

创建新的 AWorkDuration。

当客户端完成使用 AWorkDuration 时，应调用 AWorkDuration_release() 来销毁 AWorkDuration 并释放与其关联的所有资源。

详情
返回值	成功时返回 AWorkDuration，否则返回 nullptr。

AWorkDuration_release

声明位于 android/performance_hint.h

void AWorkDuration_release(
  AWorkDuration *_Nonnull aWorkDuration
)

销毁 AWorkDuration 并释放与其关联的所有资源。

详情

参数

aWorkDuration

调用 AWorkDuration_create() 创建的 AWorkDuration

AWorkDuration_setActualCpuDurationNanos

声明位于 android/performance_hint.h

void AWorkDuration_setActualCpuDurationNanos(
  AWorkDuration *_Nonnull aWorkDuration,
  int64_t actualCpuDurationNanos
)

设置实际 CPU 工作持续时间（以纳秒为单位）。

详情

参数

`aWorkDuration`	调用 AWorkDuration_create() 创建的 AWorkDuration
`actualCpuDurationNanos`	实际 CPU 工作持续时间（以纳秒为单位）。此数字必须大于或等于零。如果等于零，表示未测量 CPU 工作。

AWorkDuration_setActualGpuDurationNanos

声明位于 android/performance_hint.h

void AWorkDuration_setActualGpuDurationNanos(
  AWorkDuration *_Nonnull aWorkDuration,
  int64_t actualGpuDurationNanos
)

设置实际 GPU 工作持续时间（以纳秒为单位）。

详情

参数

`aWorkDuration`	调用 AWorkDuration_create() 创建的 AWorkDuration。
`actualGpuDurationNanos`	实际 GPU 工作持续时间（以纳秒为单位），此数字必须大于或等于零。如果等于零，表示未测量 GPU 工作。

AWorkDuration_setActualTotalDurationNanos

声明位于 android/performance_hint.h

void AWorkDuration_setActualTotalDurationNanos(
  AWorkDuration *_Nonnull aWorkDuration,
  int64_t actualTotalDurationNanos
)

设置实际总工作持续时间（以纳秒为单位）。

详情

参数

`aWorkDuration`	调用 AWorkDuration_create() 创建的 AWorkDuration
`actualTotalDurationNanos`	实际总工作持续时间（以纳秒为单位）。此数字必须大于零。

AWorkDuration_setWorkPeriodStartTimestampNanos

声明位于 android/performance_hint.h

void AWorkDuration_setWorkPeriodStartTimestampNanos(
  AWorkDuration *_Nonnull aWorkDuration,
  int64_t workPeriodStartTimestampNanos
)

设置工作周期开始时间戳（以纳秒为单位）。

详情

参数

`aWorkDuration`	调用 AWorkDuration_create() 创建的 AWorkDuration
`workPeriodStartTimestampNanos`	基于 CLOCK_MONOTONIC 的工作周期开始时间戳（以纳秒为单位），表示工作开始的时间。此时间戳必须大于零。