The Memory Advice API is in beta.

Get started with the Memory Advice API

This guide describes how to integrate the Jetpack release of the Memory Advice API in your app using Android Studio.

Games should use the Memory Advice API release that is recommended for their build environment. For Android Studio, we recommend the Jetpack release. For information about releases for other build environments, such as the Android Game Development Extension (AGDE), see Distributions.

Add the library

This section describes how to add the library to your Android Studio (Android Gradle Plugin) project.

Add the dependencies

To add the library to your Android Studio project, complete the following steps:

Enable Android Jetpack library in the project level gradle.properties), the file normally is located in root directory of your project:
```
  android.useAndroidX=true
```
Open the module level build.gradle file and add the following implementation to the dependencies block. This declares the memory advice API dependencies in your app.
```
 dependencies {
     implementation 'androidx.games:games-memory-advice:1.0.0-beta01'
 }
```
Specify the NDK version inside the android block:
```
 ndkVersion "23.1.7779620"
```
Make sure to choose a version of the NDK compatible with Memory Advice API. A list of supported NDK versions is available on the Android Games Jetpack Release page.

Declare additional build flags for CMake. To do so, add the following code to the defaultConfig block that is inside the android block:

 externalNativeBuild {
     cmake {
         cppFlags '-std=c++14'
         // c++_shared flavor is the only supported STL type.
         arguments "-DANDROID_STL=c++_shared"
     }
 }

Enable the Prefab feature. For Android Gradle Plugin(AGP) 4.1 or higher, add the following code to the android block:
```
 buildFeatures {
    prefab true
 }
```
If you are using AGP 4.0 or older, see the Prefab page for configuration instructions.

Save the file. If you see the following message, click the Sync Now button to update your project:

  Gradle files have changed since last project sync. A project sync may be
  necessary for the IDE to work properly.

Configure CMake for C/C++ build

To add the header files and runtime library for Memory Advice API into your project, open your project's main CMakeLists.txt file. In the Project pane, the file is in app > src > main > cpp. After opening the file, perform the following steps:

Near the top of the file, add the following line after any cmake_minimum_required and project lines:
```
 find_package(games-memory-advice REQUIRED CONFIG)
```
In the target_link_libraries command, add games-memory-advice::memory_advice. This makes the Memory Advice API a dependency to your project’s native library and includes it in your final application package. The update should look similar to the following:
```
 target_link_libraries(
     your-native-lib

     #link memory advice to the project
     games-memory-advice::memory_advice

     #rest of the dependencies
     #...
 )
```

Configure the Java files

The native library included with the Memory Advice API is libmemory_advice.so. It is a compiling dependency for your app's own C/C++ shared library, and is automatically loaded when your app loads its own shared library with the System.loadlibrary() function.

This step is optional.

Find the java code in your project that loads the native libraries. If it doesn't exist, add it. The code should look similar to System.loadLibrary("your-native-lib"), and is located in a static block.

Add System.loadLibrary("memory_advice") under System.loadLibrary("your-native-lib"). The update should look similar to the following:

 static {
     System.loadLibrary("your-native-lib");
     // Note: loading libmemory_advice.so is optional.
     System.loadLibrary("memory_advice");
 }

Use the library

This section describes how to use the library.

Add the header files

Include the following library header file in your project:

    #include <memory_advice/memory_advice.h>

Initialize the library

You need to initialize the library once when the app starts. To do so, add this code to your project:

    MemoryAdvice_init(env, activity);

The env and activity parameters are the JNIEnv* and jobject variables that should be available to your native library. Every JNI call to your native library should contain these variables. If you are using the GameActivity library, make sure to attach the calling thread to the JavaVM before calling the MemoryAdvice_init function.

Poll for memory state

You can retrieve the memory state of your app by polling the library at the interval of your choosing. Use the MemoryAdvice_getMemoryState function whenever you need to poll the library:

    MemoryAdvice_MemoryState state = MemoryAdvice_getMemoryState();
    switch (state) {
      case MEMORYADVICE_STATE_OK:
        // The application can safely allocate significant memory.
        break;
      case MEMORYADVICE_STATE_APPROACHING_LIMIT:
        //The application should minimize memory allocation.
        break;
      case MEMORYADVICE_STATE_CRITICAL:
        // The application should free memory as soon as possible,
        // until the memory state changes.
        break;
    }

Set up a watcher

You can also set up a watcher and register the Memory Advice API, and your watcher function will get called when the state is either approaching the limit or the critical memory state (but not for the ok state). For example, the following code creates a watcher and requests a Memory Advice API notification every 2 seconds:

    static int USER_DATA;
    constexpr int callback_waittime_ms = 2000;

    void callback(MemoryAdvice_MemoryState state, void* context) {
        switch (state) {
          case MEMORYADVICE_STATE_APPROACHING_LIMIT:
            //The application should minimize memory allocation.
            break;
          case MEMORYADVICE_STATE_CRITICAL:
            // The application should free memory as soon as possible,
            // until the memory state changes.
            break;
        }
    }

    MemoryAdvice_registerWatcher(callback_waittime_ms, callback, &USER_DATA);

What's next

See the overview for additional resources and reporting issues.