Performance Hint Manager

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
An opaque type representing a handle to a performance hint manager.
APerformanceHintSession typedef
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)
Creates a session for the given set of threads and sets their initial target work duration.
APerformanceHint_getManager()
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

Declared in android/performance_hint.h 
struct APerformanceHintManager APerformanceHintManager

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

It must be released after use.

To use:

APerformanceHintSession

Declared in android/performance_hint.h 
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

Declared in android/performance_hint.h 
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

Declared in android/performance_hint.h 
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

Declared in android/performance_hint.h 
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

Declared in android/performance_hint.h 
APerformanceHintManager *_Nullable APerformanceHint_getManager()

Acquire an instance of the performance hint manager.

Details
Returns
APerformanceHintManager instance on success, nullptr on failure.

APerformanceHint_getPreferredUpdateRateNanos

Declared in android/performance_hint.h 
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

Declared in android/performance_hint.h 
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

Declared in android/performance_hint.h 
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

Declared in android/performance_hint.h 
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

Declared in android/performance_hint.h 
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

Declared in android/performance_hint.h 
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

Declared in android/performance_hint.h 
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

Declared in android/performance_hint.h 
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

Declared in android/performance_hint.h 
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

Declared in android/performance_hint.h 
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

Declared in android/performance_hint.h 
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

Declared in android/performance_hint.h 
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.