Performance Hint Manager

#include <performance_hint.h>

APerformanceHint allows apps to create performance hint sessions for groups of threads, and provide hints to the system about the workload of those threads, to help the system more accurately allocate power for them.

Summary

It is the NDK counterpart to the Java PerformanceHintManager SDK API.

Typedefs
`APerformanceHintManager`	typedef `struct APerformanceHintManager` An opaque type representing a handle to a performance hint manager.
`APerformanceHintSession`	typedef `struct APerformanceHintSession` An opaque type representing a handle to a performance hint session.
`AWorkDuration`	typedef `struct AWorkDuration` AWorkDuration is an opaque type that represents the breakdown of the actual workload duration in each component internally.

Functions
`APerformanceHint_closeSession(APerformanceHintSession *_Nonnull session)`	`void` Release the performance hint manager pointer acquired via APerformanceHint_createSession.
`APerformanceHint_createSession(APerformanceHintManager _Nonnull manager, const int32_t _Nonnull threadIds, size_t size, int64_t initialTargetWorkDurationNanos)`	`APerformanceHintSession *_Nullable` Creates a session for the given set of threads and sets their initial target work duration.
`APerformanceHint_getManager()`	`APerformanceHintManager *_Nullable` Acquire an instance of the performance hint manager.
`APerformanceHint_getPreferredUpdateRateNanos(APerformanceHintManager *_Nonnull manager)`	`int64_t` Get preferred update rate information for this device.
`APerformanceHint_reportActualWorkDuration(APerformanceHintSession *_Nonnull session, int64_t actualDurationNanos)`	`int` Reports the actual duration for the last cycle of work.
`APerformanceHint_reportActualWorkDuration2(APerformanceHintSession _Nonnull session, AWorkDuration _Nonnull workDuration)`	`int` Reports the durations for the last cycle of work.
`APerformanceHint_setPreferPowerEfficiency(APerformanceHintSession *_Nonnull session, bool enabled)`	`int` This tells the session that these threads can be safely scheduled to prefer power efficiency over performance.
`APerformanceHint_setThreads(APerformanceHintSession _Nonnull session, const pid_t _Nonnull threadIds, size_t size)`	`int` Set a list of threads to the performance hint session.
`APerformanceHint_updateTargetWorkDuration(APerformanceHintSession *_Nonnull session, int64_t targetDurationNanos)`	`int` Updates this session's target duration for each cycle of work.
`AWorkDuration_create()`	`AWorkDuration *_Nonnull` Creates a new AWorkDuration.
`AWorkDuration_release(AWorkDuration *_Nonnull aWorkDuration)`	`void` Destroys AWorkDuration and free all resources associated to it.
`AWorkDuration_setActualCpuDurationNanos(AWorkDuration *_Nonnull aWorkDuration, int64_t actualCpuDurationNanos)`	`void` Sets the actual CPU work duration in nanoseconds.
`AWorkDuration_setActualGpuDurationNanos(AWorkDuration *_Nonnull aWorkDuration, int64_t actualGpuDurationNanos)`	`void` Sets the actual GPU work duration in nanoseconds.
`AWorkDuration_setActualTotalDurationNanos(AWorkDuration *_Nonnull aWorkDuration, int64_t actualTotalDurationNanos)`	`void` Sets the actual total work duration in nanoseconds.
`AWorkDuration_setWorkPeriodStartTimestampNanos(AWorkDuration *_Nonnull aWorkDuration, int64_t workPeriodStartTimestampNanos)`	`void` Sets the work period start timestamp in nanoseconds.

Typedefs

APerformanceHintManager

struct APerformanceHintManager APerformanceHintManager

An opaque type representing a handle to a performance hint manager.

It must be released after use.

To use:

Obtain the performance hint manager instance by calling APerformanceHint_getManager function.
Create an APerformanceHintSession with APerformanceHint_createSession.
Get the preferred update rate in nanoseconds with APerformanceHint_getPreferredUpdateRateNanos.

APerformanceHintSession

struct APerformanceHintSession APerformanceHintSession

An opaque type representing a handle to a performance hint session.

A session can only be acquired from a APerformanceHintManager with APerformanceHint_createSession. It must be freed with APerformanceHint_closeSession after use.

A Session represents a group of threads with an inter-related workload such that hints for their performance should be considered as a unit. The threads in a given session should be long-lived and not created or destroyed dynamically.

The work duration API can be used with periodic workloads to dynamically adjust thread performance and keep the work on schedule while optimizing the available power budget. When using the work duration API, the starting target duration should be specified while creating the session, and can later be adjusted with APerformanceHint_updateTargetWorkDuration. While using the work duration API, the client is expected to call APerformanceHint_reportActualWorkDuration each cycle to report the actual time taken to complete to the system.

All timings should be from std::chrono::steady_clock or clock_gettime(CLOCK_MONOTONIC, ...)

AWorkDuration

struct AWorkDuration AWorkDuration

AWorkDuration is an opaque type that represents the breakdown of the actual workload duration in each component internally.

A new AWorkDuration can be obtained using AWorkDuration_create(), when the client finishes using AWorkDuration, AWorkDuration_release() must be called to destroy and free up the resources associated with AWorkDuration.

This file provides a set of functions to allow clients to set the measured work duration of each component on AWorkDuration.

Functions

APerformanceHint_closeSession

void APerformanceHint_closeSession(
  APerformanceHintSession *_Nonnull session
)

Release the performance hint manager pointer acquired via APerformanceHint_createSession.

Details

Parameters

session

The performance hint session instance to release.

APerformanceHint_createSession

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

Creates a session for the given set of threads and sets their initial target work duration.

Details

Parameters

`manager`	The performance hint manager instance.
`threadIds`	The list of threads to be associated with this session. They must be part of this process' thread group.
`size`	The size of the list of threadIds.
`initialTargetWorkDurationNanos`	The target duration in nanoseconds for the new session. This must be positive if using the work duration API, or 0 otherwise.

Returns

APerformanceHintManager instance on success, nullptr on failure.

APerformanceHint_getManager

APerformanceHintManager *_Nullable APerformanceHint_getManager()

Acquire an instance of the performance hint manager.

Details
Returns	APerformanceHintManager instance on success, nullptr on failure.

APerformanceHint_getPreferredUpdateRateNanos

int64_t APerformanceHint_getPreferredUpdateRateNanos(
  APerformanceHintManager *_Nonnull manager
)

Get preferred update rate information for this device.

Details

Parameters

manager

The performance hint manager instance.

Returns

the preferred update rate supported by device software.

APerformanceHint_reportActualWorkDuration

int APerformanceHint_reportActualWorkDuration(
  APerformanceHintSession *_Nonnull session,
  int64_t actualDurationNanos
)

Reports the actual duration for the last cycle of work.

The system will attempt to adjust the scheduling and performance of the threads within the thread group to bring the actual duration close to the target duration.

Details

Parameters

`session`	The performance hint session instance to update.
`actualDurationNanos`	The duration of time the thread group took to complete its last task in nanoseconds. This must be positive.

Returns

0 on success. EINVAL if actualDurationNanos is not positive. EPIPE if communication with the system service has failed.

APerformanceHint_reportActualWorkDuration2

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

Reports the durations for the last cycle of work.

The system will attempt to adjust the scheduling and performance of the threads within the thread group to bring the actual duration close to the target duration.

The work period start timestamp and actual total duration must be greater than zero.

Details

Parameters

`session`	The APerformanceHintSession instance to update.
`workDuration`	The AWorkDuration structure of times the thread group took to complete its last task in nanoseconds breaking down into different components.

The actual CPU and GPU durations must be greater than or equal to zero, and at least one of them must be greater than zero. When one of them is equal to zero, it means that type of work was not measured for this workload.

Details
Returns	0 on success. EINVAL if any duration is an invalid number. EPIPE if communication with the system service has failed.

APerformanceHint_setPreferPowerEfficiency

int APerformanceHint_setPreferPowerEfficiency(
  APerformanceHintSession *_Nonnull session,
  bool enabled
)

This tells the session that these threads can be safely scheduled to prefer power efficiency over performance.

Details

Parameters

`session`	The performance hint session instance to update.
`enabled`	The flag which sets whether this session will use power-efficient scheduling.

Returns

0 on success. EPIPE if communication with the system service has failed.

APerformanceHint_setThreads

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

Set a list of threads to the performance hint session.

This operation will replace the current list of threads with the given list of threads.

Details

Parameters

`session`	The performance hint session instance to update.
`threadIds`	The list of threads to be associated with this session. They must be part of this app's thread group.
`size`	The size of the list of threadIds.

Returns

0 on success. EINVAL if the list of thread ids is empty or if any of the thread ids are not part of the thread group. EPIPE if communication with the system service has failed. EPERM if any thread id doesn't belong to the application.

APerformanceHint_updateTargetWorkDuration

int APerformanceHint_updateTargetWorkDuration(
  APerformanceHintSession *_Nonnull session,
  int64_t targetDurationNanos
)

Updates this session's target duration for each cycle of work.

Details

Parameters

`session`	The performance hint session instance to update.
`targetDurationNanos`	The new desired duration in nanoseconds. This must be positive.

Returns

0 on success. EINVAL if targetDurationNanos is not positive. EPIPE if communication with the system service has failed.

AWorkDuration_create

AWorkDuration *_Nonnull AWorkDuration_create()

Creates a new AWorkDuration.

When the client finishes using AWorkDuration, it should call AWorkDuration_release() to destroy AWorkDuration and release all resources associated with it.

Details
Returns	AWorkDuration on success and nullptr otherwise.

AWorkDuration_release

void AWorkDuration_release(
  AWorkDuration *_Nonnull aWorkDuration
)

Destroys AWorkDuration and free all resources associated to it.

Details

Parameters

aWorkDuration

The AWorkDuration created by calling AWorkDuration_create()

AWorkDuration_setActualCpuDurationNanos

void AWorkDuration_setActualCpuDurationNanos(
  AWorkDuration *_Nonnull aWorkDuration,
  int64_t actualCpuDurationNanos
)

Sets the actual CPU work duration in nanoseconds.

Details

Parameters

`aWorkDuration`	The AWorkDuration created by calling AWorkDuration_create()
`actualCpuDurationNanos`	The actual CPU work duration in nanoseconds. This number must be greater than or equal to zero. If it is equal to zero, that means the CPU was not measured.

AWorkDuration_setActualGpuDurationNanos

void AWorkDuration_setActualGpuDurationNanos(
  AWorkDuration *_Nonnull aWorkDuration,
  int64_t actualGpuDurationNanos
)

Sets the actual GPU work duration in nanoseconds.

Details

Parameters

`aWorkDuration`	The AWorkDuration created by calling AWorkDuration_create().
`actualGpuDurationNanos`	The actual GPU work duration in nanoseconds, the number must be greater than or equal to zero. If it is equal to zero, that means the GPU was not measured.

AWorkDuration_setActualTotalDurationNanos

void AWorkDuration_setActualTotalDurationNanos(
  AWorkDuration *_Nonnull aWorkDuration,
  int64_t actualTotalDurationNanos
)

Sets the actual total work duration in nanoseconds.

Details

Parameters

`aWorkDuration`	The AWorkDuration created by calling AWorkDuration_create()
`actualTotalDurationNanos`	The actual total work duration in nanoseconds. This number must be greater than zero.

AWorkDuration_setWorkPeriodStartTimestampNanos

void AWorkDuration_setWorkPeriodStartTimestampNanos(
  AWorkDuration *_Nonnull aWorkDuration,
  int64_t workPeriodStartTimestampNanos
)

Sets the work period start timestamp in nanoseconds.

Details

Parameters

`aWorkDuration`	The AWorkDuration created by calling AWorkDuration_create()
`workPeriodStartTimestampNanos`	The work period start timestamp in nanoseconds based on CLOCK_MONOTONIC about when the work starts. This timestamp must be greater than zero.