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:
- Binary releases in the Android Games Jetpack libraries.
- Binary releases on the AGDK download page.
- Source code on AOSP.
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
- Memory Advice API release notes
- Memory Advice API reference documentation
- Memory Advice sample on Github
- Memory Advice API source code
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.