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 WorkDuration)	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.

• AWorkDuration_setWorkPeriodStartTimestampNanos()
• AWorkDuration_setActualTotalDurationNanos()
• AWorkDuration_setActualCpuDurationNanos()
• AWorkDuration_setActualGpuDurationNanos()

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, actual total duration and actual CPU duration must be positive.

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 GPU duration must be non-negative. If the actual GPU duration is 0, it means the actual GPU duration is not measured.

Details
Returns	0 on success. EINVAL if session is nullptr or 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 WorkDuration
)

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, the number must be positive.

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 non-negative. If the actual GPU duration is 0, it means the actual GPU duration is 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, the number must be positive.

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, the timestamp must be positive.