# SystemHealth

SystemHealth provides access to data about how various system resources are used by applications.

## Summary

CPU/GPU headroom APIs are designed to be best used by applications with consistent and intense workload such as games to query the remaining capacity headroom over a short period and perform optimization accordingly. Due to the nature of the fast job scheduling and frequency scaling of CPU and GPU, the headroom by nature will have "TOCTOU" problem which makes it less suitable for apps with inconsistent or low workload to take any useful action but simply monitoring. And to avoid oscillation it's not recommended to adjust workload too frequent (on each polling request) or too aggressively. As the headroom calculation is more based on reflecting past history usage than predicting future capacity. Take game as an example, if the API returns CPU headroom of 0 in one scenario (especially if it's constant across multiple calls), or some value significantly smaller than other scenarios, then it can reason that the recent performance result is more CPU bottlenecked. Then reducing the CPU workload intensity can help reserve some headroom to handle the load variance better, which can result in less frame drops or smooth FPS value. On the other hand, if the API returns large CPU headroom constantly, the app can be more confident to increase the workload and expect higher possibility of device meeting its performance expectation. App can also use thermal APIs to read the current thermal status and headroom first, then poll the CPU and GPU headroom if the device is (about to) getting thermal throttled. If the CPU/GPU headrooms provide enough significance such as one valued at 0 while the other at 100, then it can be used to infer that reducing CPU workload could be more efficient to cool down the device. There is a caveat that the power controller may scale down the frequency of the CPU and GPU due to thermal and other reasons, which can result in a higher than usual percentage usage of the capacity.

| ### Enumerations ||
|---|---|
| `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1gacc8d3699ca0537db14b990460b279fef{ https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ggacc8d3699ca0537db14b990460b279fefa0b1c9ee634eeade11340e3712faba573 = 0, https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ggacc8d3699ca0537db14b990460b279fefa0be8676ecbd4e06c56c7f3bb3db34fbc = 1 }` | enum |
| `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga7f51529801866f2fcc82d30b47ca7530{ https://developer.android.com/ndk/reference/group/system-health#group___system_health_1gga7f51529801866f2fcc82d30b47ca7530a67f6e22e6aa001035668eeb280386bdd = 0, https://developer.android.com/ndk/reference/group/system-health#group___system_health_1gga7f51529801866f2fcc82d30b47ca7530a5e3886d059d45f38ec8a9eb90942be74 = 1 }` | enum |

| ### Typedefs ||
|---|---|
| `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga907911dfef7d9dc605cc5f524861430a` | typedef `enum https://developer.android.com/ndk/reference/group/system-health#group___system_health_1gacc8d3699ca0537db14b990460b279fef` |
| `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga91ee480d0a55000afd06cff5efa479ea` | typedef `struct https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga91ee480d0a55000afd06cff5efa479ea` Params used to customize the calculation of CPU headroom. |
| `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1gafe6cd1ee2dda2551906982dee4ac17ed` | typedef `enum https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga7f51529801866f2fcc82d30b47ca7530` |
| `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga400dd0e2169128889310d1f5fea0fdf1` | typedef `struct https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga400dd0e2169128889310d1f5fea0fdf1` Params used to customize the calculation of GPU headroom. |

| ### Functions ||
|---|---|
| `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1gac31c016b9a218cf2ce61899930bfde14(void)` | `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga91ee480d0a55000afd06cff5efa479ea *_Nonnull` Creates a new instance of [ACpuHeadroomParams](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga91ee480d0a55000afd06cff5efa479ea). |
| `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga35fb8f6584a7abefc80ca707562a497a(https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga91ee480d0a55000afd06cff5efa479ea *https://developer.android.com/ndk/reference/group/ndk-binder#group___ndk_binder_1ga0890a8f74983b96e76f6b8748543032d params)` | `void` Deletes the [ACpuHeadroomParams](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga91ee480d0a55000afd06cff5efa479ea) instance. |
| `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1gab6589d30be2a1a1144368fb87960eba4(https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga91ee480d0a55000afd06cff5efa479ea *_Nonnull params)` | `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1gacc8d3699ca0537db14b990460b279fef` Gets the CPU headroom calculation type in [ACpuHeadroomParams](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga91ee480d0a55000afd06cff5efa479ea). |
| `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga8638a23d2e8e57121c39f50c7f4b300a(https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga91ee480d0a55000afd06cff5efa479ea *_Nonnull params)` | `int` Gets the CPU headroom calculation window size in milliseconds. |
| `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga2423729476f990a3a6fc5b76a859f48f(https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga91ee480d0a55000afd06cff5efa479ea *_Nonnull params, https://developer.android.com/ndk/reference/group/system-health#group___system_health_1gacc8d3699ca0537db14b990460b279fef calculationType)` | `void` Sets the CPU headroom calculation type in [ACpuHeadroomParams](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga91ee480d0a55000afd06cff5efa479ea). |
| `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga7b7ea8d0b6e3c23aa9801b0601ba9df7(https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga91ee480d0a55000afd06cff5efa479ea *_Nonnull params, int windowMillis)` | `void` Sets the CPU headroom calculation window size in milliseconds. |
| `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1gac3da22b8f29ee3eb4078f394d3b5b872(https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga91ee480d0a55000afd06cff5efa479ea *_Nonnull params, const int *_Nonnull tids, size_t tidsSize)` | `void` Sets the thread TIDs to track in [ACpuHeadroomParams](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga91ee480d0a55000afd06cff5efa479ea). |
| `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga3d055f6c6f98e550a5c38b29aa084b0f(void)` | `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga400dd0e2169128889310d1f5fea0fdf1 *_Nonnull` Creates a new instance of [AGpuHeadroomParams](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga400dd0e2169128889310d1f5fea0fdf1). |
| `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1gad38871e43c739f15fa4ef64fed582f07(https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga400dd0e2169128889310d1f5fea0fdf1 *https://developer.android.com/ndk/reference/group/ndk-binder#group___ndk_binder_1ga0890a8f74983b96e76f6b8748543032d params)` | `void` Deletes the [AGpuHeadroomParams](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga400dd0e2169128889310d1f5fea0fdf1) instance. |
| `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga478417feeb72bb010c3e32e220593ebc(https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga400dd0e2169128889310d1f5fea0fdf1 *_Nonnull params)` | `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga7f51529801866f2fcc82d30b47ca7530` Gets the GPU headroom calculation type in [AGpuHeadroomParams](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga400dd0e2169128889310d1f5fea0fdf1). |
| `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga898ddda8d3cc72d931f14be6cb764e5d(https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga400dd0e2169128889310d1f5fea0fdf1 *_Nonnull params)` | `int` Gets the GPU headroom calculation window size in milliseconds. |
| `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga09fd43b0ffe46415b244a473ac96faa0(https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga400dd0e2169128889310d1f5fea0fdf1 *_Nonnull params, https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga7f51529801866f2fcc82d30b47ca7530 calculationType)` | `void` Sets the GPU headroom calculation type in [AGpuHeadroomParams](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga400dd0e2169128889310d1f5fea0fdf1). |
| `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga6aa6bb7ac949e6857d05d55aa7bbcd4e(https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga400dd0e2169128889310d1f5fea0fdf1 *_Nonnull params, int windowMillis)` | `void` Sets the GPU headroom calculation window size in milliseconds. |
| `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1gac6468ef6505f6bca722b35e1127d302a(const https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga91ee480d0a55000afd06cff5efa479ea *https://developer.android.com/ndk/reference/group/ndk-binder#group___ndk_binder_1ga0890a8f74983b96e76f6b8748543032d params, float *_Nonnull outHeadroom)` | `int` Provides an estimate of available CPU capacity headroom of the device. |
| `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1gaf2f6561bc27f85a083b4a76ad62865c4(int32_t *_Nonnull outMinMillis, int32_t *_Nonnull outMaxMillis)` | `int` Gets the range of the calculation window size for CPU headroom. |
| `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1gaf14ba5e1592e8fe64b25ab90b704e351(int64_t *_Nonnull outMinIntervalMillis)` | `int` Gets minimum polling interval for calling [ASystemHealth_getCpuHeadroom](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1gac6468ef6505f6bca722b35e1127d302a) in milliseconds. |
| `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga68d42269da7a17a8acd3603a756c5631(const https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga400dd0e2169128889310d1f5fea0fdf1 *https://developer.android.com/ndk/reference/group/ndk-binder#group___ndk_binder_1ga0890a8f74983b96e76f6b8748543032d params, float *_Nonnull outHeadroom)` | `int` Provides an estimate of available GPU capacity headroom of the device. |
| `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1gae4a3b089293a2cd8847f813b5121497f(int32_t *_Nonnull outMinMillis, int32_t *_Nonnull outMaxMillis)` | `int` Gets the range of the calculation window size for GPU headroom. |
| `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1gad176acff181becda26957355419335ae(int64_t *_Nonnull outMinIntervalMillis)` | `int` Gets minimum polling interval for calling [ASystemHealth_getGpuHeadroom](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga68d42269da7a17a8acd3603a756c5631) in milliseconds. |
| `https://developer.android.com/ndk/reference/group/system-health#group___system_health_1gaeba99f04dc83b1e2bc9fb76d7f48d969(size_t *_Nonnull outSize)` | `int` Gets the maximum number of TIDs this device supports for getting CPU headroom. |

## Enumerations

### ACpuHeadroomCalculationType

Declared in `android/system_health.h`

```
 ACpuHeadroomCalculationType
```

| Properties ||
|---|---|
| `ACPU_HEADROOM_CALCULATION_TYPE_AVERAGE` | The headroom calculation type bases on average value over a specified window. Introduced in API level 36. |
| `ACPU_HEADROOM_CALCULATION_TYPE_MIN` | The headroom calculation type bases on minimum value over a specified window. Introduced in API level 36. |

### AGpuHeadroomCalculationType

Declared in `android/system_health.h`

```
 AGpuHeadroomCalculationType
```

| Properties ||
|---|---|
| `AGPU_HEADROOM_CALCULATION_TYPE_AVERAGE` | The headroom calculation type bases on average value over a specified window. Introduced in API level 36. |
| `AGPU_HEADROOM_CALCULATION_TYPE_MIN` | The headroom calculation type bases on minimum value over a specified window. Introduced in API level 36. |

## Typedefs

### ACpuHeadroomCalculationType

Declared in `android/system_health.h`

```
enum ACpuHeadroomCalculationType ACpuHeadroomCalculationType
```

### ACpuHeadroomParams

Declared in `android/system_health.h`

```
struct ACpuHeadroomParams ACpuHeadroomParams
```
Params used to customize the calculation of CPU headroom.

Also see [ASystemHealth_getCpuHeadroom](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1gac6468ef6505f6bca722b35e1127d302a).

### AGpuHeadroomCalculationType

Declared in `android/system_health.h`

```
enum AGpuHeadroomCalculationType AGpuHeadroomCalculationType
```

### AGpuHeadroomParams

Declared in `android/system_health.h`

```
struct AGpuHeadroomParams AGpuHeadroomParams
```
Params used to customize the calculation of GPU headroom.

Also see [ASystemHealth_getGpuHeadroom](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga68d42269da7a17a8acd3603a756c5631).

## Functions

### ACpuHeadroomParams_create

Declared in `android/system_health.h`

```
ACpuHeadroomParams *_Nonnull ACpuHeadroomParams_create(
  void
)
```
Creates a new instance of [ACpuHeadroomParams](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga91ee480d0a55000afd06cff5efa479ea).

When the client finishes using [ACpuHeadroomParams](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga91ee480d0a55000afd06cff5efa479ea), [ACpuHeadroomParams_destroy](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga35fb8f6584a7abefc80ca707562a497a) must be called to destroy and free up the resources associated with [ACpuHeadroomParams](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga91ee480d0a55000afd06cff5efa479ea).

Available since API level 36.

<br />

| Details ||
|---|---|
| **Returns** | A new instance of [ACpuHeadroomParams](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga91ee480d0a55000afd06cff5efa479ea). |

### ACpuHeadroomParams_destroy

Declared in `android/system_health.h`

```
void ACpuHeadroomParams_destroy(
  ACpuHeadroomParams *_Nullable params
)
```
Deletes the [ACpuHeadroomParams](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga91ee480d0a55000afd06cff5efa479ea) instance.

Available since API level 36.

<br />

Details Parameters `params` The params to be deleted.

### ACpuHeadroomParams_getCalculationType

Declared in `android/system_health.h`

```
ACpuHeadroomCalculationType ACpuHeadroomParams_getCalculationType(
  ACpuHeadroomParams *_Nonnull params
)
```
Gets the CPU headroom calculation type in [ACpuHeadroomParams](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga91ee480d0a55000afd06cff5efa479ea).

This will return the default value chosen by the device if not set.

Available since API level 36.

<br />

Details Parameters `params` The params to read from. **Returns** The headroom calculation type.

### ACpuHeadroomParams_getCalculationWindowMillis

Declared in `android/system_health.h`

```
int ACpuHeadroomParams_getCalculationWindowMillis(
  ACpuHeadroomParams *_Nonnull params
)
```
Gets the CPU headroom calculation window size in milliseconds.

This will return the default value chosen by the device if not set.

Available since API level 36.

<br />

Details Parameters `params` The params to read from. **Returns** This will return the default value chosen by the device if the params is not set.

### ACpuHeadroomParams_setCalculationType

Declared in `android/system_health.h`

```
void ACpuHeadroomParams_setCalculationType(
  ACpuHeadroomParams *_Nonnull params,
  ACpuHeadroomCalculationType calculationType
)
```
Sets the CPU headroom calculation type in [ACpuHeadroomParams](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga91ee480d0a55000afd06cff5efa479ea).

Available since API level 36.

<br />

Details Parameters `params` The params to be set. `calculationType` The headroom calculation type.

### ACpuHeadroomParams_setCalculationWindowMillis

Declared in `android/system_health.h`

```
void ACpuHeadroomParams_setCalculationWindowMillis(
  ACpuHeadroomParams *_Nonnull params,
  int windowMillis
)
```
Sets the CPU headroom calculation window size in milliseconds.

Available since API level 36.

<br />

Details Parameters `params` The params to be set. `windowMillis` The window size in milliseconds ranges from [ASystemHealth_getCpuHeadroomCalculationWindowRange](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1gaf2f6561bc27f85a083b4a76ad62865c4). The smaller the window size, the larger fluctuation in the headroom value should be expected. The default value can be retrieved from the [ACpuHeadroomParams_getCalculationWindowMillis](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga8638a23d2e8e57121c39f50c7f4b300a) if not set. The device will try to use the closest feasible window size to this param.

### ACpuHeadroomParams_setTids

Declared in `android/system_health.h`

```
void ACpuHeadroomParams_setTids(
  ACpuHeadroomParams *_Nonnull params,
  const int *_Nonnull tids,
  size_t tidsSize
)
```
Sets the thread TIDs to track in [ACpuHeadroomParams](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga91ee480d0a55000afd06cff5efa479ea).

The TIDs should belong to the same of the process that will make the headroom call. And they should not have different core affinity.

If not set or set to empty, the headroom will be based on the PID of the process making the call.

Available since API level 36.

<br />

Details Parameters `params` The params to be set. `tids` Non-null array of TIDs, where maximum size can be read from [ASystemHealth_getMaxCpuHeadroomTidsSize](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1gaeba99f04dc83b1e2bc9fb76d7f48d969). `tidsSize` The size of the tids array.

### AGpuHeadroomParams_create

Declared in `android/system_health.h`

```
AGpuHeadroomParams *_Nonnull AGpuHeadroomParams_create(
  void
)
```
Creates a new instance of [AGpuHeadroomParams](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga400dd0e2169128889310d1f5fea0fdf1).

When the client finishes using [AGpuHeadroomParams](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga400dd0e2169128889310d1f5fea0fdf1), [AGpuHeadroomParams_destroy](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1gad38871e43c739f15fa4ef64fed582f07) must be called to destroy and free up the resources associated with [AGpuHeadroomParams](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga400dd0e2169128889310d1f5fea0fdf1).

Available since API level 36.

<br />

| Details ||
|---|---|
| **Returns** | A new instance of [AGpuHeadroomParams](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga400dd0e2169128889310d1f5fea0fdf1). |

### AGpuHeadroomParams_destroy

Declared in `android/system_health.h`

```
void AGpuHeadroomParams_destroy(
  AGpuHeadroomParams *_Nullable params
)
```
Deletes the [AGpuHeadroomParams](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga400dd0e2169128889310d1f5fea0fdf1) instance.

Available since API level 36.

<br />

Details Parameters `params` The params to be deleted.

### AGpuHeadroomParams_getCalculationType

Declared in `android/system_health.h`

```
AGpuHeadroomCalculationType AGpuHeadroomParams_getCalculationType(
  AGpuHeadroomParams *_Nonnull params
)
```
Gets the GPU headroom calculation type in [AGpuHeadroomParams](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga400dd0e2169128889310d1f5fea0fdf1).

This will return the default value chosen by the device if not set.

Available since API level 36.

<br />

Details Parameters `params` The params to read from. **Returns** The headroom calculation type.

### AGpuHeadroomParams_getCalculationWindowMillis

Declared in `android/system_health.h`

```
int AGpuHeadroomParams_getCalculationWindowMillis(
  AGpuHeadroomParams *_Nonnull params
)
```
Gets the GPU headroom calculation window size in milliseconds.

This will return the default value chosen by the device if not set.

Available since API level 36.

<br />

Details Parameters `params` The params to read from. **Returns** This will return the default value chosen by the device if the params is not set.

### AGpuHeadroomParams_setCalculationType

Declared in `android/system_health.h`

```
void AGpuHeadroomParams_setCalculationType(
  AGpuHeadroomParams *_Nonnull params,
  AGpuHeadroomCalculationType calculationType
)
```
Sets the GPU headroom calculation type in [AGpuHeadroomParams](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga400dd0e2169128889310d1f5fea0fdf1).

Available since API level 36.

<br />

Details Parameters `params` The params to be set. `calculationType` The headroom calculation type.

### AGpuHeadroomParams_setCalculationWindowMillis

Declared in `android/system_health.h`

```
void AGpuHeadroomParams_setCalculationWindowMillis(
  AGpuHeadroomParams *_Nonnull params,
  int windowMillis
)
```
Sets the GPU headroom calculation window size in milliseconds.

Available since API level 36.

<br />

Details Parameters `params` The params to be set. `windowMillis` The window size in milliseconds ranges from [ASystemHealth_getGpuHeadroomCalculationWindowRange](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1gae4a3b089293a2cd8847f813b5121497f). The smaller the window size, the larger fluctuation in the headroom value should be expected. The default value can be retrieved from the [AGpuHeadroomParams_getCalculationWindowMillis](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga898ddda8d3cc72d931f14be6cb764e5d) if not set. The device will try to use the closest feasible window size to this param.

### ASystemHealth_getCpuHeadroom

Declared in `android/system_health.h`

```
int ASystemHealth_getCpuHeadroom(
  const ACpuHeadroomParams *_Nullable params,
  float *_Nonnull outHeadroom
)
```
Provides an estimate of available CPU capacity headroom of the device.

The value can be used by the calling application to determine if the workload was CPU bound and then take action accordingly to ensure that the workload can be completed smoothly. It can also be used with the thermal status and headroom to determine if reducing the CPU bound workload can help reduce the device temperature to avoid thermal throttling.

If the params are valid, each call will perform at least one synchronous binder transaction that can take more than 1ms. So it's not recommended to call or wait for this on critical threads. Some devices may implement this as an on-demand API with lazy initialization, so the caller should expect higher latency when making the first call (especially with non-default params) since app starts or after changing params, as the device may need to change its data collection.

Available since API level 36.

<br />

Details Parameters `params` The params to customize the CPU headroom calculation, or nullptr to use default. `outHeadroom` Non-null output pointer to a single float, which will be set to the CPU headroom value. The value will be a single value or `Float.NaN` if it's temporarily unavailable due to server error or not enough user CPU workload. Each valid value ranges from \[0, 100\], where 0 indicates no more cpu resources can be granted. **Returns** 0 on success. EPIPE if failed to get the CPU headroom. EPERM if the TIDs do not belong to the same process. ENOTSUP if API or requested params is unsupported.

### ASystemHealth_getCpuHeadroomCalculationWindowRange

Declared in `android/system_health.h`

```
int ASystemHealth_getCpuHeadroomCalculationWindowRange(
  int32_t *_Nonnull outMinMillis,
  int32_t *_Nonnull outMaxMillis
)
```
Gets the range of the calculation window size for CPU headroom.

Available since API level 36.

<br />

Details Parameters `outMinMillis` Non-null output pointer to be set to the minimum window size in milliseconds. `outMaxMillis` Non-null output pointer to be set to the maximum window size in milliseconds. **Returns** 0 on success. ENOTSUP if API is unsupported.

### ASystemHealth_getCpuHeadroomMinIntervalMillis

Declared in `android/system_health.h`

```
int ASystemHealth_getCpuHeadroomMinIntervalMillis(
  int64_t *_Nonnull outMinIntervalMillis
)
```
Gets minimum polling interval for calling [ASystemHealth_getCpuHeadroom](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1gac6468ef6505f6bca722b35e1127d302a) in milliseconds.

The [ASystemHealth_getCpuHeadroom](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1gac6468ef6505f6bca722b35e1127d302a) API may return cached result if called more frequently than the interval.

Available since API level 36.

<br />

Details Parameters `outMinIntervalMillis` Non-null output pointer to a int64_t, which will be set to the minimum polling interval in milliseconds. **Returns** 0 on success. ENOTSUP if API is unsupported.

### ASystemHealth_getGpuHeadroom

Declared in `android/system_health.h`

```
int ASystemHealth_getGpuHeadroom(
  const AGpuHeadroomParams *_Nullable params,
  float *_Nonnull outHeadroom
)
```
Provides an estimate of available GPU capacity headroom of the device.

The value can be used by the calling application to determine if the workload was GPU bound and then take action accordingly to ensure that the workload can be completed smoothly. It can also be used with the thermal status and headroom to determine if reducing the GPU bound workload can help reduce the device temperature to avoid thermal throttling.

If the params are valid, each call will perform at least one synchronous binder transaction that can take more than 1ms. So it's not recommended to call or wait for this on critical threads. Some devices may implement this as an on-demand API with lazy initialization, so the caller should expect higher latency when making the first call (especially with non-default params) since app starts or after changing params, as the device may need to change its data collection.

Available since API level 36

<br />

Details Parameters `params` The params to customize the GPU headroom calculation, or nullptr to use default `outHeadroom` Non-null output pointer to a single float, which will be set to the GPU headroom value. The value will be a single value or `Float.NaN` if it's temporarily unavailable. Each valid value ranges from \[0, 100\], where 0 indicates no more gpu resources can be granted. **Returns** 0 on success. EPIPE if failed to get the GPU headroom. ENOTSUP if API or requested params is unsupported.

### ASystemHealth_getGpuHeadroomCalculationWindowRange

Declared in `android/system_health.h`

```
int ASystemHealth_getGpuHeadroomCalculationWindowRange(
  int32_t *_Nonnull outMinMillis,
  int32_t *_Nonnull outMaxMillis
)
```
Gets the range of the calculation window size for GPU headroom.

Available since API level 36.

<br />

Details Parameters `outMinMillis` Non-null output pointer to be set to the minimum window size in milliseconds. `outMaxMillis` Non-null output pointer to be set to the maximum window size in milliseconds. **Returns** 0 on success. ENOTSUP if API is unsupported.

### ASystemHealth_getGpuHeadroomMinIntervalMillis

Declared in `android/system_health.h`

```
int ASystemHealth_getGpuHeadroomMinIntervalMillis(
  int64_t *_Nonnull outMinIntervalMillis
)
```
Gets minimum polling interval for calling [ASystemHealth_getGpuHeadroom](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga68d42269da7a17a8acd3603a756c5631) in milliseconds.

The [ASystemHealth_getGpuHeadroom](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1ga68d42269da7a17a8acd3603a756c5631) API may return cached result if called more frequently than the interval.

Available since API level 36.

<br />

Details Parameters `outMinIntervalMillis` Non-null output pointer to a int64_t, which will be set to the minimum polling interval in milliseconds. **Returns** 0 on success. ENOTSUP if API is unsupported.

### ASystemHealth_getMaxCpuHeadroomTidsSize

Declared in `android/system_health.h`

```
int ASystemHealth_getMaxCpuHeadroomTidsSize(
  size_t *_Nonnull outSize
)
```
Gets the maximum number of TIDs this device supports for getting CPU headroom.

See [ACpuHeadroomParams_setTids](https://developer.android.com/ndk/reference/group/system-health#group___system_health_1gac3da22b8f29ee3eb4078f394d3b5b872).

Available since API level 36.

<br />

Details Parameters `outSize` Non-null output pointer to the max size. **Returns** 0 on success. ENOTSUP if the CPU headroom API is unsupported.