# 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 resources for them.
## Summary
It is the NDK counterpart to the Java PerformanceHintManager SDK API.
This API is intended for periodic workloads, such as frame production. Clients are expected to create an instance of APerformanceHintManager, create a session with that, and then set a target duration for the session. Then, they can report the actual work duration at the end of each cycle to inform the framework about how long those workloads are taking. The framework will then compare the actual durations to the target duration and attempt to help the client reach a steady state under the target.
Unlike reportActualWorkDuration, the "notifyWorkload..." hints are intended to be sent in advance of large changes in the workload, to prevent them from going over the target when there is a sudden, unforseen change. Their effects are intended to last for only one cycle, after which reportActualWorkDuration will have a chance to catch up. These hints should be used judiciously, only in cases where the workload is changing substantially. To enforce that, they are tracked using a per-app rate limiter to avoid excessive hinting and encourage clients to be mindful about when to send them.
| ### Enumerations ||
|---|---|
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gabd6bee0fd2367e6b7ca84cb63dee832c{ https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ggabd6bee0fd2367e6b7ca84cb63dee832ca04c447207d521df552d6c0f19b7f7ff8, https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ggabd6bee0fd2367e6b7ca84cb63dee832cabbbce1d30417064497db3736172185e0, https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ggabd6bee0fd2367e6b7ca84cb63dee832ca98f84cbc49c4321df11644fceb47e2db, https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ggabd6bee0fd2367e6b7ca84cb63dee832cac0086c535732a304d804b55e2a5e81de, https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ggabd6bee0fd2367e6b7ca84cb63dee832cabae392a2d157fc99e06fdab7507e8088, https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ggabd6bee0fd2367e6b7ca84cb63dee832ca165661e0cd36a1b1aa98a3f21ccf8124 }` | enumThis enum represents different aspects of performance hint functionality. |
| ### Typedefs ||
|---|---|
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga66956d540c2e3709e12156d195e64726` | typedef `struct https://developer.android.com/ndk/reference/group/a-native-window#group___a_native_window_1ga66956d540c2e3709e12156d195e64726` |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga5b45d5c0c5a70ac8989ca27d5e1bb4b9` | typedef `enum https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gabd6bee0fd2367e6b7ca84cb63dee832c` This enum represents different aspects of performance hint functionality. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga7bcc08fd85dce85b374376af3ea73789` | typedef `struct https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga7bcc08fd85dce85b374376af3ea73789` An opaque type representing a handle to a performance hint manager. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gae0e9dcf831937738b43cc633830bc0a1` | typedef `struct https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gae0e9dcf831937738b43cc633830bc0a1` An opaque type representing a handle to a performance hint session. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaba6e03fc31ed39343932aa7e745fbcf0` | typedef `struct https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaba6e03fc31ed39343932aa7e745fbcf0` An opaque type representing a handle to a performance hint session creation configuration. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga9ec2697392f7de4f3cf244312c75f155` | typedef `struct ASurfaceControl` |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad6cd28ca0acf8de587ae1285f5f21c8a` | typedef `struct https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad6cd28ca0acf8de587ae1285f5f21c8a` [AWorkDuration](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad6cd28ca0acf8de587ae1285f5f21c8a) is an opaque type that represents the breakdown of the actual workload duration in each component internally. |
| ### Variables ||
|---|---|
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga8bacba0e25e12be1fd2d8ac7af14c5c9` | `int64_t Client side rate limiting is not use https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga367d4e234868b03a5394ef63ff898fe6 for support` |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaf7edf6d4ea5a37463f213737734d8954` | `int64_t Client side rate limiting is not` |
| ### Functions ||
|---|---|
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga7299660fd49e8a6fa886794a2518ad62(JNIEnv *_Nonnull env, jobject _Nonnull sessionObj)` | `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gae0e9dcf831937738b43cc633830bc0a1 *_Nonnull` Return the APerformanceHintSession wrapped by a Java PerformanceHintManager.Session object. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga9eda4a11b42fab2b81ada8263dfa7e66(https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gae0e9dcf831937738b43cc633830bc0a1 *_Nonnull session)` | `void` Release the performance hint manager pointer acquired via [APerformanceHint_createSession](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga04d10722fda22ba26818a4f12744691b). |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga04d10722fda22ba26818a4f12744691b(https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga7bcc08fd85dce85b374376af3ea73789 *_Nonnull manager, const int32_t *_Nonnull threadIds, size_t size, int64_t initialTargetWorkDurationNanos)` | `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gae0e9dcf831937738b43cc633830bc0a1 *https://developer.android.com/ndk/reference/group/ndk-binder#group___ndk_binder_1ga0890a8f74983b96e76f6b8748543032d` Creates a session for the given set of threads and sets their initial target work duration. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gae28d926038b8cb468805e459504b8551(https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga7bcc08fd85dce85b374376af3ea73789 *_Nonnull manager, https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaba6e03fc31ed39343932aa7e745fbcf0 *_Nonnull config, https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gae0e9dcf831937738b43cc633830bc0a1 *https://developer.android.com/ndk/reference/group/ndk-binder#group___ndk_binder_1ga0890a8f74983b96e76f6b8748543032d *_Nonnull sessionOut)` | `int` Creates a session using arguments from a corresponding [ASessionCreationConfig](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaba6e03fc31ed39343932aa7e745fbcf0). |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad5ef5828aa4c487fa14bfeb25387bf66()` | `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga7bcc08fd85dce85b374376af3ea73789 *https://developer.android.com/ndk/reference/group/ndk-binder#group___ndk_binder_1ga0890a8f74983b96e76f6b8748543032d` Acquire an instance of the performance hint manager. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gafa92ac0b38df936de9a8fc8bffa94cda(https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga7bcc08fd85dce85b374376af3ea73789 *_Nonnull manager)` | `int` Get maximum number of graphics pipieline threads per-app for this device. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga022dd3ba2e38d94c8e9754f5e353c1ec(https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga7bcc08fd85dce85b374376af3ea73789 *_Nonnull manager) __DEPRECATED_IN(36` | `int64_t` **[Deprecated.](https://developer.android.com/ndk/reference/deprecated/deprecated)** Client side rate limiting is not necessary, rate limiting is handled in the framework. If you were using this to check for hint session support, please use [APerformanceHint_isFeatureSupported](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga367d4e234868b03a5394ef63ff898fe6) instead.Get preferred update rate information for this device. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga367d4e234868b03a5394ef63ff898fe6(https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gabd6bee0fd2367e6b7ca84cb63dee832c feature)` | `bool` Checks whether the device exposes support for a specific feature. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gabb0370b87c188e1bc7060036e73ffc7c(https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gae0e9dcf831937738b43cc633830bc0a1 *_Nonnull session, bool cpu, bool gpu, const char *_Nonnull identifier)` | `int` Informs the framework of an upcoming increase in the workload of this session. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaa67b03e9743f890546424cfe090b9999(https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gae0e9dcf831937738b43cc633830bc0a1 *_Nonnull session, bool cpu, bool gpu, const char *_Nonnull identifier)` | `int` Informs the framework that the workload associated with this session is about to start, or that it is about to completely change, and that the system should discard any assumptions about its characteristics inferred from previous activity. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga9ba4fc3625d959c5551ea89f024df0c4(https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gae0e9dcf831937738b43cc633830bc0a1 *_Nonnull session, bool cpu, bool gpu, const char *_Nonnull identifier)` | `int` Informs the framework of an upcoming one-off expensive workload cycle for a given session. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga97ffe1220bdd915b797e31e41f5908c0(https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gae0e9dcf831937738b43cc633830bc0a1 *_Nonnull session, int64_t actualDurationNanos)` | `int` Reports the actual duration for the last cycle of work. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga93d8e4bea7ad626c64b21ea37493d9a3(https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gae0e9dcf831937738b43cc633830bc0a1 *_Nonnull session, https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad6cd28ca0acf8de587ae1285f5f21c8a *_Nonnull workDuration)` | `int` Reports the durations for the last cycle of work. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gae3bda6577fa1d220eb343b3a66abbb2c(https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gae0e9dcf831937738b43cc633830bc0a1 *_Nonnull session, https://developer.android.com/ndk/reference/group/a-native-window#group___a_native_window_1ga66956d540c2e3709e12156d195e64726 *_Nonnull *https://developer.android.com/ndk/reference/group/ndk-binder#group___ndk_binder_1ga0890a8f74983b96e76f6b8748543032d nativeWindows, size_t nativeWindowsSize, https://developer.android.com/ndk/reference/group/native-activity#group___native_activity_1ga9ec2697392f7de4f3cf244312c75f155 *_Nonnull *https://developer.android.com/ndk/reference/group/ndk-binder#group___ndk_binder_1ga0890a8f74983b96e76f6b8748543032d surfaceControls, size_t surfaceControlsSize)` | `int` Associates a session with any [ASurfaceControl](https://developer.android.com/ndk/reference/group/native-activity#group___native_activity_1ga9ec2697392f7de4f3cf244312c75f155) or [ANativeWindow](https://developer.android.com/ndk/reference/group/a-native-window#group___a_native_window) instances managed by this session. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad91efc82f89b9649638085f51d4357df(https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gae0e9dcf831937738b43cc633830bc0a1 *_Nonnull session, bool enabled)` | `int` This tells the session that these threads can be safely scheduled to prefer power efficiency over performance. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga2f50e9d66080ba8fe4278d5a171c44e4(https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gae0e9dcf831937738b43cc633830bc0a1 *_Nonnull session, const pid_t *_Nonnull threadIds, size_t size)` | `int` Set a list of threads to the performance hint session. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga6a2145ec6f22a9b6d37eb3a22df1af4d(https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gae0e9dcf831937738b43cc633830bc0a1 *_Nonnull session, int64_t targetDurationNanos)` | `int` Updates this session's target duration for each cycle of work. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga8bc4fecbac847a246a385b6d96dc55ce()` | `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaba6e03fc31ed39343932aa7e745fbcf0 *_Nonnull` |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gafd13b95c6ca4b83c0523ee2750de9416(https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaba6e03fc31ed39343932aa7e745fbcf0 *_Nonnull config)` | `void` Destroys a [ASessionCreationConfig](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaba6e03fc31ed39343932aa7e745fbcf0) and frees all resources associated with it. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaf8f16561d3bed16bafc567b9d6afedf7(https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaba6e03fc31ed39343932aa7e745fbcf0 *_Nonnull config, bool enabled)` | `void` Sessions setting this hint are expected to time the critical path of graphics pipeline from end to end, with the total work duration representing the time from the start of frame production until the buffer is fully finished drawing. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga8a2fc4a19902f6d6debb68c705a69a60(https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaba6e03fc31ed39343932aa7e745fbcf0 *_Nonnull config, https://developer.android.com/ndk/reference/group/a-native-window#group___a_native_window_1ga66956d540c2e3709e12156d195e64726 *_Nonnull *https://developer.android.com/ndk/reference/group/ndk-binder#group___ndk_binder_1ga0890a8f74983b96e76f6b8748543032d nativeWindows, size_t nativeWindowsSize, https://developer.android.com/ndk/reference/group/native-activity#group___native_activity_1ga9ec2697392f7de4f3cf244312c75f155 *_Nonnull *https://developer.android.com/ndk/reference/group/ndk-binder#group___ndk_binder_1ga0890a8f74983b96e76f6b8748543032d surfaceControls, size_t surfaceControlsSize)` | `void` Associates the created session with any [ASurfaceControl](https://developer.android.com/ndk/reference/group/native-activity#group___native_activity_1ga9ec2697392f7de4f3cf244312c75f155) or [ANativeWindow](https://developer.android.com/ndk/reference/group/a-native-window#group___a_native_window) instances it will be managing. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga158ab808595452cef85ea46de797e5aa(https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaba6e03fc31ed39343932aa7e745fbcf0 *_Nonnull config, bool enabled)` | `void` Sets whether power efficiency mode will be enabled for the session. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga32e855e91ce2b00fd5a29a43c4644a94(https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaba6e03fc31ed39343932aa7e745fbcf0 *_Nonnull config, int64_t targetWorkDurationNanos)` | `void` Sets the initial target work duration in nanoseconds for the session to be created. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga4cd24f5b4fc7716c88ef6b6bd6536e96(https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaba6e03fc31ed39343932aa7e745fbcf0 *_Nonnull config, const pid_t *_Nonnull tids, size_t size)` | `void` Sets the tids to be associated with the session to be created. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga675613e5e652fa2720e38ef5af1e4302(https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaba6e03fc31ed39343932aa7e745fbcf0 *_Nonnull config, bool cpu, bool gpu)` | `void` Enable automatic timing mode for sessions using the GRAPHICS_PIPELINE API with an attached surface. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga72a13735e87c3310fefea0f9c80cdba8()` | `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad6cd28ca0acf8de587ae1285f5f21c8a *_Nonnull` Creates a new AWorkDuration. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga04740422d2fbd456c7381ae9612c2fad(https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad6cd28ca0acf8de587ae1285f5f21c8a *_Nonnull aWorkDuration)` | `void` Destroys a [AWorkDuration](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad6cd28ca0acf8de587ae1285f5f21c8a) and frees all resources associated with it. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga1715ace0c7d5f16889f708be25a1382e(https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad6cd28ca0acf8de587ae1285f5f21c8a *_Nonnull aWorkDuration, int64_t actualCpuDurationNanos)` | `void` Sets the actual CPU work duration in nanoseconds. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaec3d523bd62a73d3bc44f918cb0b399e(https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad6cd28ca0acf8de587ae1285f5f21c8a *_Nonnull aWorkDuration, int64_t actualGpuDurationNanos)` | `void` Sets the actual GPU work duration in nanoseconds. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad440fb6f3c54366e4c3c5c8e7c05dda6(https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad6cd28ca0acf8de587ae1285f5f21c8a *_Nonnull aWorkDuration, int64_t actualTotalDurationNanos)` | `void` Sets the actual total work duration in nanoseconds. |
| `https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga047bbecb948225343341ec6ef33740dd(https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad6cd28ca0acf8de587ae1285f5f21c8a *_Nonnull aWorkDuration, int64_t workPeriodStartTimestampNanos)` | `void` Sets the work period start timestamp in nanoseconds. |
## Enumerations
### APerformanceHintFeature
Declared in `android/performance_hint.h`
```
APerformanceHintFeature
```
This enum represents different aspects of performance hint functionality.
These can be passed to [APerformanceHint_isFeatureSupported](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga367d4e234868b03a5394ef63ff898fe6) to determine whether the device exposes support for that feature.
Some of these features will not expose failure to the client if used when unsupported, to prevent the client from needing to worry about handling different logic for each possible support configuration. The exception to this is features with important user-facing side effects, such as [APERF_HINT_AUTO_CPU](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ggabd6bee0fd2367e6b7ca84cb63dee832cabae392a2d157fc99e06fdab7507e8088) and [APERF_HINT_AUTO_GPU](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ggabd6bee0fd2367e6b7ca84cb63dee832ca165661e0cd36a1b1aa98a3f21ccf8124) modes which expect the client not to report durations while they are active.
| Properties ||
|---|---|
| `APERF_HINT_AUTO_CPU` | This value represents the automatic CPU timing feature, as exposed by [ASessionCreationConfig_setUseAutoTiming](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga675613e5e652fa2720e38ef5af1e4302). |
| `APERF_HINT_AUTO_GPU` | This value represents the automatic GPU timing feature, as exposed by [ASessionCreationConfig_setUseAutoTiming](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga675613e5e652fa2720e38ef5af1e4302). |
| `APERF_HINT_GRAPHICS_PIPELINE` | This value represents the "graphics pipeline" mode, as exposed by [ASessionCreationConfig_setGraphicsPipeline](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaf8f16561d3bed16bafc567b9d6afedf7). |
| `APERF_HINT_POWER_EFFICIENCY` | This value represents the power efficiency mode, as exposed by [ASessionCreationConfig_setPreferPowerEfficiency](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga158ab808595452cef85ea46de797e5aa) and [APerformanceHint_setPreferPowerEfficiency](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad91efc82f89b9649638085f51d4357df). |
| `APERF_HINT_SESSIONS` | This value represents all APerformanceHintSession functionality. Using the Performance Hint API at all if this is not enabled will likely result in either [APerformanceHintManager](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga7bcc08fd85dce85b374376af3ea73789) or [APerformanceHintSession](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gae0e9dcf831937738b43cc633830bc0a1) failing to create, or the session having little to no benefit even if creation succeeds. |
| `APERF_HINT_SURFACE_BINDING` | This value the ability for sessions to bind to surfaces using [APerformanceHint_setNativeSurfaces](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gae3bda6577fa1d220eb343b3a66abbb2c) or [ASessionCreationConfig_setNativeSurfaces](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga8a2fc4a19902f6d6debb68c705a69a60). |
## Typedefs
### ANativeWindow
Declared in `android/performance_hint.h`
```
struct ANativeWindow ANativeWindow
```
### APerformanceHintFeature
Declared in `android/performance_hint.h`
```
enum APerformanceHintFeature APerformanceHintFeature
```
This enum represents different aspects of performance hint functionality.
These can be passed to [APerformanceHint_isFeatureSupported](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga367d4e234868b03a5394ef63ff898fe6) to determine whether the device exposes support for that feature.
Some of these features will not expose failure to the client if used when unsupported, to prevent the client from needing to worry about handling different logic for each possible support configuration. The exception to this is features with important user-facing side effects, such as [APERF_HINT_AUTO_CPU](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ggabd6bee0fd2367e6b7ca84cb63dee832cabae392a2d157fc99e06fdab7507e8088) and [APERF_HINT_AUTO_GPU](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ggabd6bee0fd2367e6b7ca84cb63dee832ca165661e0cd36a1b1aa98a3f21ccf8124) modes which expect the client not to report durations while they are active.
### APerformanceHintManager
Declared in `android/performance_hint.h`
```
struct APerformanceHintManager APerformanceHintManager
```
An opaque type representing a handle to a performance hint manager.
To use:
- Obtain the performance hint manager instance by calling [APerformanceHint_getManager](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad5ef5828aa4c487fa14bfeb25387bf66) function.
- Create an [APerformanceHintSession](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gae0e9dcf831937738b43cc633830bc0a1) with [APerformanceHint_createSession](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga04d10722fda22ba26818a4f12744691b).
- Get the preferred update rate in nanoseconds with [APerformanceHint_getPreferredUpdateRateNanos](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga022dd3ba2e38d94c8e9754f5e353c1ec).
### 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](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga7bcc08fd85dce85b374376af3ea73789) with [APerformanceHint_createSession](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga04d10722fda22ba26818a4f12744691b) or [APerformanceHint_createSessionUsingConfig](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gae28d926038b8cb468805e459504b8551). It must be freed with [APerformanceHint_closeSession](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga9eda4a11b42fab2b81ada8263dfa7e66) 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](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga6a2145ec6f22a9b6d37eb3a22df1af4d). While using the work duration API, the client is expected to call [APerformanceHint_reportActualWorkDuration](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga97ffe1220bdd915b797e31e41f5908c0) each cycle to report the actual time taken to complete to the system.
Note, methods of [APerformanceHintSession_\*](https://developer.android.com/ndk/reference//) are not thread safe so callers must ensure thread safety.
All timings should be from `std::chrono::steady_clock` or `clock_gettime(CLOCK_MONOTONIC, ...)`
### ASessionCreationConfig
Declared in `android/performance_hint.h`
```
struct ASessionCreationConfig ASessionCreationConfig
```
An opaque type representing a handle to a performance hint session creation configuration.
It is consumed by [APerformanceHint_createSessionUsingConfig](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gae28d926038b8cb468805e459504b8551).
A session creation config encapsulates the required information for creating a session. The only mandatory parameter is the set of TIDs, set using [ASessionCreationConfig_setTids](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga4cd24f5b4fc7716c88ef6b6bd6536e96). Only parameters relevant to the session need to be set, and any unspecified functionality will be treated as unused on the session. Configurations without a valid set of TIDs, or which try to enable automatic timing without the graphics pipeline mode, are considered invalid.
The caller may reuse this object and modify the settings in it to create additional sessions.
### ASurfaceControl
Declared in `android/performance_hint.h`
```
struct ASurfaceControl ASurfaceControl
```
### AWorkDuration
Declared in `android/performance_hint.h`
```
struct AWorkDuration AWorkDuration
```
[AWorkDuration](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad6cd28ca0acf8de587ae1285f5f21c8a) is an opaque type that represents the breakdown of the actual workload duration in each component internally.
A new [AWorkDuration](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad6cd28ca0acf8de587ae1285f5f21c8a) can be obtained using [AWorkDuration_create()](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga72a13735e87c3310fefea0f9c80cdba8), when the client finishes using [AWorkDuration](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad6cd28ca0acf8de587ae1285f5f21c8a), [AWorkDuration_release()](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga04740422d2fbd456c7381ae9612c2fad) must be called to destroy and free up the resources associated with [AWorkDuration](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad6cd28ca0acf8de587ae1285f5f21c8a).
This file provides a set of functions to allow clients to set the measured work duration of each component on [AWorkDuration](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad6cd28ca0acf8de587ae1285f5f21c8a).
- [AWorkDuration_setWorkPeriodStartTimestampNanos()](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga047bbecb948225343341ec6ef33740dd)
- [AWorkDuration_setActualTotalDurationNanos()](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad440fb6f3c54366e4c3c5c8e7c05dda6)
- [AWorkDuration_setActualCpuDurationNanos()](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga1715ace0c7d5f16889f708be25a1382e)
- [AWorkDuration_setActualGpuDurationNanos()](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaec3d523bd62a73d3bc44f918cb0b399e)
## Variables
### checking
Declared in `android/performance_hint.h`
```
int64_t Client side rate limiting is not use APerformanceHint_isFeatureSupported for support checking
```
### necessary
Declared in `android/performance_hint.h`
```
int64_t Client side rate limiting is not necessary
```
## Functions
### APerformanceHint_borrowSessionFromJava
Declared in `android/performance_hint.h`
```
APerformanceHintSession *_Nonnull APerformanceHint_borrowSessionFromJava(
JNIEnv *_Nonnull env,
jobject _Nonnull sessionObj
)
```
Return the APerformanceHintSession wrapped by a Java PerformanceHintManager.Session object.
The Java session maintains ownership over the wrapped native session, so it cannot be closed using [APerformanceHint_closeSession](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga9eda4a11b42fab2b81ada8263dfa7e66). The return value is valid until the Java object containing this value dies.
The returned pointer is intended to be used by JNI calls to access native performance APIs using a Java hint session wrapper, and then immediately discarded. Using the pointer after the death of the Java container results in undefined behavior.
Details Parameters `env` The Java environment where the PerformanceHintManager.Session lives. `sessionObj` The Java Session to unwrap. **Returns** A pointer to the APerformanceHintSession that backs the Java Session.
### APerformanceHint_closeSession
Declared in `android/performance_hint.h`
```
void APerformanceHint_closeSession(
APerformanceHintSession *_Nonnull session
)
```
Release the performance hint manager pointer acquired via [APerformanceHint_createSession](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga04d10722fda22ba26818a4f12744691b).
This cannot be used to close a Java PerformanceHintManager.Session, as its lifecycle is tied to the object in the SDK.
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** APerformanceHintSession pointer on success, nullptr on failure.
### APerformanceHint_createSessionUsingConfig
Declared in `android/performance_hint.h`
```
int APerformanceHint_createSessionUsingConfig(
APerformanceHintManager *_Nonnull manager,
ASessionCreationConfig *_Nonnull config,
APerformanceHintSession *_Nullable *_Nonnull sessionOut
)
```
Creates a session using arguments from a corresponding [ASessionCreationConfig](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaba6e03fc31ed39343932aa7e745fbcf0).
Note: when using graphics pipeline mode, using too many cumulative graphics pipeline threads is not a failure and will still create a session, but it will cause all graphics pipeline sessions to have undefined behavior and the method will return EBUSY.
Details Parameters `manager` The performance hint manager instance. `config` The configuration struct containing required information to create a session. `sessionOut` A client-provided pointer, which will be set to the new APerformanceHintSession on success or EBUSY, and to nullptr on failure. **Returns** 0 on success. EINVAL if the creation config is in an invalid state. EPIPE if communication failed. ENOTSUP if hint sessions are not supported, or if auto timing is enabled but unsupported. EBUSY if too many graphics pipeline threads are passed.
### 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_getMaxGraphicsPipelineThreadsCount
Declared in `android/performance_hint.h`
```
int APerformanceHint_getMaxGraphicsPipelineThreadsCount(
APerformanceHintManager *_Nonnull manager
)
```
Get maximum number of graphics pipieline threads per-app for this device.
Details Parameters `manager` The performance hint manager instance. **Returns** the maximum number of graphics pipeline threads supported by device.
### APerformanceHint_getPreferredUpdateRateNanos
Declared in `android/performance_hint.h`
```
int64_t APerformanceHint_getPreferredUpdateRateNanos(
APerformanceHintManager *_Nonnull manager
) __DEPRECATED_IN(36
```
Get preferred update rate information for this device.
**[Deprecated.](https://developer.android.com/ndk/reference/deprecated/deprecated)** Client side rate limiting is not necessary, rate limiting is handled in the framework. If you were using this to check for hint session support, please use [APerformanceHint_isFeatureSupported](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga367d4e234868b03a5394ef63ff898fe6) instead.
Details Parameters `manager` The performance hint manager instance. **Returns** the preferred update rate supported by device software.
### APerformanceHint_isFeatureSupported
Declared in `android/performance_hint.h`
```
bool APerformanceHint_isFeatureSupported(
APerformanceHintFeature feature
)
```
Checks whether the device exposes support for a specific feature.
Details Parameters `feature` The specific feature enum to check. **Returns** false if unsupported, true if supported.
### APerformanceHint_notifyWorkloadIncrease
Declared in `android/performance_hint.h`
```
int APerformanceHint_notifyWorkloadIncrease(
APerformanceHintSession *_Nonnull session,
bool cpu,
bool gpu,
const char *_Nonnull identifier
)
```
Informs the framework of an upcoming increase in the workload of this session.
The user can specify whether the increase is expected to be on the CPU, GPU, or both.
These hints should be sent shortly before the start of the cycle where the workload is going to change, or as early as possible during that cycle for maximum effect. Hints sent towards the end of the cycle may be interpreted as applying to the next cycle. Any unsupported hints will be silently dropped, to avoid the need for excessive support checking each time they are sent, and sending a hint for both CPU and GPU will count as two separate hints for the rate limiter. These hints should not be sent repeatedly for an ongoing expensive workload, as workload time reporting is intended to handle this.
Details Parameters `session` The [APerformanceHintSession](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gae0e9dcf831937738b43cc633830bc0a1) instance to send a hint for. `cpu` Indicates if the workload increase is expected to affect the CPU. `gpu` Indicates if the workload increase is expected to affect the GPU. `identifier` A required string used to distinguish this specific hint, using utf-8 encoding. This string will only be held for the duration of the method, and can be discarded after. **Returns** 0 on success. EBUSY if the hint was rate limited. EPIPE if communication with the system service has failed.
### APerformanceHint_notifyWorkloadReset
Declared in `android/performance_hint.h`
```
int APerformanceHint_notifyWorkloadReset(
APerformanceHintSession *_Nonnull session,
bool cpu,
bool gpu,
const char *_Nonnull identifier
)
```
Informs the framework that the workload associated with this session is about to start, or that it is about to completely change, and that the system should discard any assumptions about its characteristics inferred from previous activity.
The user can specify whether the reset is expected to affect the CPU, GPU, or both.
These hints should be sent shortly before the start of the cycle where the workload is going to change, or as early as possible during that cycle for maximum effect. Hints sent towards the end of the cycle may be interpreted as applying to the next cycle. Any unsupported hints will be silently dropped, to avoid the need for excessive support checking each time they are sent, and sending a hint for both CPU and GPU will count as two separate hints for the rate limiter. These hints should not be sent repeatedly for an ongoing expensive workload, as workload time reporting is intended to handle this.
Details Parameters `session` The [APerformanceHintSession](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gae0e9dcf831937738b43cc633830bc0a1) instance to send a hint for. `cpu` Indicates if the workload reset is expected to affect the CPU. `gpu` Indicates if the workload reset is expected to affect the GPU. `identifier` A required string used to distinguish this specific hint, using utf-8 encoding. This string will only be held for the duration of the method, and can be discarded after. **Returns** 0 on success. EBUSY if the hint was rate limited. EPIPE if communication with the system service has failed.
### APerformanceHint_notifyWorkloadSpike
Declared in `android/performance_hint.h`
```
int APerformanceHint_notifyWorkloadSpike(
APerformanceHintSession *_Nonnull session,
bool cpu,
bool gpu,
const char *_Nonnull identifier
)
```
Informs the framework of an upcoming one-off expensive workload cycle for a given session.
This cycle will be treated as not representative of the workload as a whole, and it will be discarded the purposes of load tracking. The user can specify whether the workload spike is expected to be on the CPU, GPU, or both.
These hints should be sent shortly before the start of the cycle where the workload is going to change, or as early as possible during that cycle for maximum effect. Hints sent towards the end of the cycle may be interpreted as applying to the next cycle. Any unsupported hints will be silently dropped, to avoid the need for excessive support checking each time they are sent, and sending a hint for both CPU and GPU will count as two separate hints for the rate limiter. These hints should not be sent repeatedly for an ongoing expensive workload, as workload time reporting is intended to handle this.
Details Parameters `session` The [APerformanceHintSession](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gae0e9dcf831937738b43cc633830bc0a1) instance to send a hint for. `cpu` Indicates if the workload spike is expected to affect the CPU. `gpu` Indicates if the workload spike is expected to affect the GPU. `identifier` A required string used to distinguish this specific hint, using utf-8 encoding. This string will only be held for the duration of the method, and can be discarded after. **Returns** 0 on success. EBUSY if the hint was rate limited. EPIPE if communication with the system service has failed.
### 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 or the target it 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](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gae0e9dcf831937738b43cc633830bc0a1) instance to update. `workDuration` The [AWorkDuration](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad6cd28ca0acf8de587ae1285f5f21c8a) 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_setNativeSurfaces
Declared in `android/performance_hint.h`
```
int APerformanceHint_setNativeSurfaces(
APerformanceHintSession *_Nonnull session,
ANativeWindow *_Nonnull *_Nullable nativeWindows,
size_t nativeWindowsSize,
ASurfaceControl *_Nonnull *_Nullable surfaceControls,
size_t surfaceControlsSize
)
```
Associates a session with any [ASurfaceControl](https://developer.android.com/ndk/reference/group/native-activity#group___native_activity_1ga9ec2697392f7de4f3cf244312c75f155) or [ANativeWindow](https://developer.android.com/ndk/reference/group/a-native-window#group___a_native_window) instances managed by this session.
Any previously associated objects that are not passed in again lose their association. Invalid or dead instances are ignored, and passing both lists as null drops all current associations.
This method is primarily intended for sessions that manage the timing of an entire graphics pipeline end-to-end for frame pacing, such as those using the [ASessionCreationConfig_setGraphicsPipeline](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaf8f16561d3bed16bafc567b9d6afedf7) API. However, any session directly or indirectly managing a graphics pipeline should still associate themselves with directly relevant ASurfaceControl or ANativeWindow instances for better optimization. Additionally, if the surface associated with a session changes, this method should be called again to re-create the association.
To see any benefit from this method, the client must make sure they are updating the frame rate of attached surfaces using methods such as [ANativeWindow_setFrameRate](https://developer.android.com/ndk/reference/group/a-native-window#group___a_native_window_1ga0e026ac6946f1daeca37048289f93846), or by updating any associated ASurfaceControls with transactions that have {ASurfaceTransaction_setFrameRate}.
Details Parameters `session` The [APerformanceHintSession](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gae0e9dcf831937738b43cc633830bc0a1) instance to update. `nativeWindows` A pointer to a list of ANativeWindows associated with this session. nullptr can be passed to indicate there are no associated ANativeWindows. `nativeWindowsSize` The number of ANativeWindows in the list. `surfaceControls` A pointer to a list of ASurfaceControls associated with this session. nullptr can be passed to indicate there are no associated ASurfaceControls. `surfaceControlsSize` The number of ASurfaceControls in the list. **Returns** 0 on success. EPIPE if communication has failed. ENOTSUP if this is not supported on the device.
### 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.
Note: when using a session with the graphics pipeline mode enabled, using too many cumulative graphics pipeline threads is not a failure, but it will cause all graphics pipeline sessions to have undefined behavior and the method will return EBUSY.
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. EBUSY if too many graphics pipeline threads were passed.
### 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 for the session to report work durations, and may be zero to disable this functionality. **Returns** 0 on success. EINVAL if targetDurationNanos is less than zero. EPIPE if communication with the system service has failed.
### ASessionCreationConfig_create
Declared in `android/performance_hint.h`
```
ASessionCreationConfig *_Nonnull ASessionCreationConfig_create()
```
### ASessionCreationConfig_release
Declared in `android/performance_hint.h`
```
void ASessionCreationConfig_release(
ASessionCreationConfig *_Nonnull config
)
```
Destroys a [ASessionCreationConfig](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaba6e03fc31ed39343932aa7e745fbcf0) and frees all resources associated with it.
Details Parameters `config` The [ASessionCreationConfig](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaba6e03fc31ed39343932aa7e745fbcf0) created by calling [ASessionCreationConfig_create()](https://developer.android.com/ndk/reference//#_1ga8bc4fecbac847a246a385b6d96dc55ce).
### ASessionCreationConfig_setGraphicsPipeline
Declared in `android/performance_hint.h`
```
void ASessionCreationConfig_setGraphicsPipeline(
ASessionCreationConfig *_Nonnull config,
bool enabled
)
```
Sessions setting this hint are expected to time the critical path of graphics pipeline from end to end, with the total work duration representing the time from the start of frame production until the buffer is fully finished drawing.
It should include any threads on the critical path of that pipeline, up to a limit accessible from [APerformanceHint_getMaxGraphicsPipelineThreadsCount()](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gafa92ac0b38df936de9a8fc8bffa94cda).
Details Parameters `config` The [ASessionCreationConfig](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaba6e03fc31ed39343932aa7e745fbcf0) created by calling [ASessionCreationConfig_create()](https://developer.android.com/ndk/reference//#_1ga8bc4fecbac847a246a385b6d96dc55ce). `enabled` Whether this session manages a graphics pipeline's critical path.
### ASessionCreationConfig_setNativeSurfaces
Declared in `android/performance_hint.h`
```
void ASessionCreationConfig_setNativeSurfaces(
ASessionCreationConfig *_Nonnull config,
ANativeWindow *_Nonnull *_Nullable nativeWindows,
size_t nativeWindowsSize,
ASurfaceControl *_Nonnull *_Nullable surfaceControls,
size_t surfaceControlsSize
)
```
Associates the created session with any [ASurfaceControl](https://developer.android.com/ndk/reference/group/native-activity#group___native_activity_1ga9ec2697392f7de4f3cf244312c75f155) or [ANativeWindow](https://developer.android.com/ndk/reference/group/a-native-window#group___a_native_window) instances it will be managing.
Invalid or dead instances are ignored.
This method is primarily intended for sessions that manage the timing of an entire graphics pipeline end-to-end for frame pacing, such as those using the [ASessionCreationConfig_setGraphicsPipeline](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaf8f16561d3bed16bafc567b9d6afedf7) API. However, any session directly or indirectly managing a graphics pipeline should still associate themselves with directly relevant ASurfaceControl or ANativeWindow instances for better optimization. Additionally, if the surface associated with a session changes, this method should be called again to re-create the association.
To see any benefit from this method, the client must make sure they are updating the frame rate of attached surfaces using methods such as [ANativeWindow_setFrameRate](https://developer.android.com/ndk/reference/group/a-native-window#group___a_native_window_1ga0e026ac6946f1daeca37048289f93846), or by updating any associated ASurfaceControls with transactions that have {ASurfaceTransaction_setFrameRate}.
Details Parameters `config` The [ASessionCreationConfig](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaba6e03fc31ed39343932aa7e745fbcf0) created by calling [ASessionCreationConfig_create()](https://developer.android.com/ndk/reference//#_1ga8bc4fecbac847a246a385b6d96dc55ce). `nativeWindows` A pointer to a list of ANativeWindows associated with this session. nullptr can be passed to indicate there are no associated ANativeWindows. `nativeWindowsSize` The number of ANativeWindows in the list. `surfaceControls` A pointer to a list of ASurfaceControls associated with this session. nullptr can be passed to indicate there are no associated ASurfaceControls. `surfaceControlsSize` The number of ASurfaceControls in the list.
### ASessionCreationConfig_setPreferPowerEfficiency
Declared in `android/performance_hint.h`
```
void ASessionCreationConfig_setPreferPowerEfficiency(
ASessionCreationConfig *_Nonnull config,
bool enabled
)
```
Sets whether power efficiency mode will be enabled for the session.
This tells the session that these threads can be safely scheduled to prefer power efficiency over performance.
Details Parameters `config` The [ASessionCreationConfig](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaba6e03fc31ed39343932aa7e745fbcf0) created by calling [ASessionCreationConfig_create()](https://developer.android.com/ndk/reference//#_1ga8bc4fecbac847a246a385b6d96dc55ce). `enabled` Whether power efficiency mode will be enabled.
### ASessionCreationConfig_setTargetWorkDurationNanos
Declared in `android/performance_hint.h`
```
void ASessionCreationConfig_setTargetWorkDurationNanos(
ASessionCreationConfig *_Nonnull config,
int64_t targetWorkDurationNanos
)
```
Sets the initial target work duration in nanoseconds for the session to be created.
Details Parameters `config` The [ASessionCreationConfig](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaba6e03fc31ed39343932aa7e745fbcf0) created by calling [ASessionCreationConfig_create()](https://developer.android.com/ndk/reference//#_1ga8bc4fecbac847a246a385b6d96dc55ce). `targetWorkDurationNanos` The parameter to specify a target duration in nanoseconds for the new session; this value must be positive to use the work duration API, and may be ignored otherwise or set to zero. Negative values are invalid.
### ASessionCreationConfig_setTids
Declared in `android/performance_hint.h`
```
void ASessionCreationConfig_setTids(
ASessionCreationConfig *_Nonnull config,
const pid_t *_Nonnull tids,
size_t size
)
```
Sets the tids to be associated with the session to be created.
Details Parameters `config` The [ASessionCreationConfig](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaba6e03fc31ed39343932aa7e745fbcf0) created by calling [ASessionCreationConfig_create()](https://developer.android.com/ndk/reference//#_1ga8bc4fecbac847a246a385b6d96dc55ce) `tids` The list of tids to be associated with this session. They must be part of this process' thread group. `size` The size of the list of tids.
### ASessionCreationConfig_setUseAutoTiming
Declared in `android/performance_hint.h`
```
void ASessionCreationConfig_setUseAutoTiming(
ASessionCreationConfig *_Nonnull config,
bool cpu,
bool gpu
)
```
Enable automatic timing mode for sessions using the GRAPHICS_PIPELINE API with an attached surface.
In this mode, sessions do not need to report timing data for the CPU, GPU, or both depending on the configuration. To use this mode, sessions should set a native surface using {}, enable graphics pipeline mode with [ASessionCreationConfig_setGraphicsPipeline()](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaf8f16561d3bed16bafc567b9d6afedf7), and then call this method to set whether automatic timing is desired for the CPU, GPU, or both. Trying to enable this without also enabling the graphics pipeline mode will cause session creation to fail.
It is still be beneficial to set an accurate target time, as this may help determine timing information for some workloads where there is less information available from the framework, such as games. Additionally, reported CPU durations will be ignored while automatic CPU timing is enabled, and similarly GPU durations will be ignored when automatic GPU timing is enabled. When both are enabled, the entire [APerformanceHint_reportActualWorkDuration](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga97ffe1220bdd915b797e31e41f5908c0) call will be ignored, and the session will be managed completely automatically.
If the client is manually controlling their frame rate for those surfaces, then they must make sure they are updating the frame rate with [ANativeWindow_setFrameRate](https://developer.android.com/ndk/reference/group/a-native-window#group___a_native_window_1ga0e026ac6946f1daeca37048289f93846), or updating any associated ASurfaceControls with transactions that have {ASurfaceTransaction_setFrameRate} set.
The user of this API should ensure this feature is supported by checking [APERF_HINT_AUTO_CPU](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ggabd6bee0fd2367e6b7ca84cb63dee832cabae392a2d157fc99e06fdab7507e8088) and [APERF_HINT_AUTO_GPU](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ggabd6bee0fd2367e6b7ca84cb63dee832ca165661e0cd36a1b1aa98a3f21ccf8124) with [APerformanceHint_isFeatureSupported](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga367d4e234868b03a5394ef63ff898fe6) and falling back to manual timing if it is not. Trying to use automatic timing when it is unsupported will cause session creation to fail.
Details Parameters `config` The [ASessionCreationConfig](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gaba6e03fc31ed39343932aa7e745fbcf0) created by calling [ASessionCreationConfig_create()](https://developer.android.com/ndk/reference//#_1ga8bc4fecbac847a246a385b6d96dc55ce). `cpu` Whether to enable automatic timing for the CPU for this session. `gpu` Whether to enable automatic timing for the GPU for this session.
### AWorkDuration_create
Declared in `android/performance_hint.h`
```
AWorkDuration *_Nonnull AWorkDuration_create()
```
Creates a new AWorkDuration.
When the client finishes using [AWorkDuration](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad6cd28ca0acf8de587ae1285f5f21c8a), it should call [AWorkDuration_release()](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga04740422d2fbd456c7381ae9612c2fad) to destroy [AWorkDuration](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad6cd28ca0acf8de587ae1285f5f21c8a) and release all resources associated with it.
| Details ||
|---|---|
| **Returns** | AWorkDuration pointer. |
### AWorkDuration_release
Declared in `android/performance_hint.h`
```
void AWorkDuration_release(
AWorkDuration *_Nonnull aWorkDuration
)
```
Destroys a [AWorkDuration](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad6cd28ca0acf8de587ae1285f5f21c8a) and frees all resources associated with it.
Details Parameters `aWorkDuration` The [AWorkDuration](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad6cd28ca0acf8de587ae1285f5f21c8a) created by calling [AWorkDuration_create()](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga72a13735e87c3310fefea0f9c80cdba8)
### 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](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad6cd28ca0acf8de587ae1285f5f21c8a) created by calling [AWorkDuration_create()](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga72a13735e87c3310fefea0f9c80cdba8) `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](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad6cd28ca0acf8de587ae1285f5f21c8a) created by calling [AWorkDuration_create()](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga72a13735e87c3310fefea0f9c80cdba8). `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](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad6cd28ca0acf8de587ae1285f5f21c8a) created by calling [AWorkDuration_create()](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga72a13735e87c3310fefea0f9c80cdba8) `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](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1gad6cd28ca0acf8de587ae1285f5f21c8a) created by calling [AWorkDuration_create()](https://developer.android.com/ndk/reference/group/a-performance-hint#group___a_performance_hint_1ga72a13735e87c3310fefea0f9c80cdba8) `workPeriodStartTimestampNanos` The work period start timestamp in nanoseconds based on CLOCK_MONOTONIC about when the work starts. This timestamp must be greater than zero.