Memory Advice API overview

The Memory Advice API is an experimental native API that helps Android apps stay within safety limits for memory use. The API achieves this by estimating the amount of memory resources that are in use, and then notifying the app when certain thresholds are exceeded. The API can also report the estimated percentage of memory use directly to your app.

The estimations provided by the API help to determine when your app should adjust its memory use, or to find areas to improve in future versions of your app. The adjustments could include anything that changes memory consumption, such as lowering the details and quality of visual and audio assets.

The estimated memory resources include native heap memory allocated by malloc, and graphics memory allocated by the OpenGL ES and Vulkan Graphics APIs making the Memory Advice API ideal for games and graphic intensive apps.

The estimates are made based on the following:

  • Device metrics collected by the API
  • Machine learning data from devices
  • Device testing

At the API level, the Memory Advice API defines a set of memory advice states and communicates them to apps with a set of functions.

Get Started Get Started for Unity games

Distributions

The Memory Advice API is a part of the Android Games Development Kit (AGDK) and is distributed through the following channels:

Games should use the Memory Advice API release that is recommended for their build environment. For Android Studio, we recommend the Jetpack release. For the Android Game Development Extension (AGDE), we recommend the release on the AGDK download page.

Features

This section describes the Memory Advice API features.

Memory state

The API reports the following memory states to apps:

  • MEMORYADVICE_STATE_OK
  • MEMORYADVICE_STATE_APPROACHING_LIMIT
  • MEMORYADVICE_STATE_CRITICAL

For details, see the memoryadvice_memorystate reference pages.

Reporting the memory state

The API supports reporting the memory state through either a polling or a callback mechanism:

  • Polling:
    An app can call the API at any time to retrieve the memory state.

  • Callback:
    An app can register a callback function with the Memory Advice API. The app specifies the calling frequency for the callback. The API uses the frequency to determine when to execute the callback when the application memory condition is approaching the safe limit or is critically low. The callback is not invoked if the memory condition is safe. The callback is executed from its own thread, not from a thread belonging to the app.

Cost and calling frequency considerations

The Memory Advice API uses computational time to generate the memory status. The cost varies by device, but is usually between 1ms and 3ms per call. You should consider this overhead when determining how often to poll the memory state, or what frequency to specify for the memory state callback.

Requirements

Device requirements

  • Android 4.4 (API level 19) or higher.

App requirements

  • The API only supports native apps (apps primarily written in C/C++).

  • The API only supports physical devices; emulators are not supported.

NDK version requirements

The Memory Advice API release supports most popular NDK versions, refer to the release notes for the supported NDK list.

Additional Resources

Issues and Feedback

The Memory Advice API is in beta and welcomes feedback, if you have suggestions or find issues while using the API, create an issue in IssueTracker.