Erste Schritte mit der Memory Advice API

In diesem Leitfaden wird beschrieben, wie du den Jetpack-Release der Memory Advice API mithilfe von Android Studio in deine App einbindest.

Für Spiele sollte die Memory Advice API-Version verwendet werden, die für ihre Build-Umgebung empfohlen wird. Für Android Studio empfehlen wir den Jetpack-Release. Informationen zu Releases für andere Build-Umgebungen, z. B. die Android Game Development Extension (AGDE), findest du unter Distributionen.

Bibliothek hinzufügen

In diesem Abschnitt wird beschrieben, wie Sie die Bibliothek Ihrem Android Studio-Projekt (Android Gradle-Plug-in) hinzufügen.

Abhängigkeiten hinzufügen

Führen Sie die folgenden Schritte aus, um die Bibliothek zu Ihrem Android Studio-Projekt hinzuzufügen:

Aktivieren Sie die Android Jetpack-Bibliothek auf Projektebene gradle.properties), befindet sich die Datei normalerweise im Stammverzeichnis Ihres Projekts:
```
  android.useAndroidX=true
```
Öffnen Sie die Datei build.gradle auf Modulebene und fügen Sie den folgenden implementation dem Abhängigkeitenblock hinzu. Dadurch werden die API-Abhängigkeiten für die Arbeitsspeicherempfehlung in Ihrer App deklariert.
```
 dependencies {
     implementation 'androidx.games:games-memory-advice:1.0.0-beta01'
 }
```
Geben Sie die NDK-Version im android-Block an:
```
 ndkVersion "23.1.7779620"
```
Wählen Sie eine Version des NDK aus, die mit der Memory Advice API kompatibel ist. Eine Liste der unterstützten NDK-Versionen ist auf der Seite zu den Android Games Jetpack-Releases verfügbar.

Deklarieren Sie zusätzliche Build-Flags für CMake. Fügen Sie dazu den folgenden Code in den defaultConfig-Block innerhalb des android-Blocks ein:

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

Aktivieren Sie die Funktion Prefab. Fügen Sie für Android Gradle-Plug-in(AGP) 4.1 oder höher den folgenden Code in den android-Block ein:
```
 buildFeatures {
    prefab true
 }
```
Wenn Sie AGP 4.0 oder eine ältere Version verwenden, finden Sie eine Konfigurationsanleitung auf der Prefab-Seite.
Speichere die Datei. Wenn die folgende Meldung angezeigt wird, klicken Sie auf die Schaltfläche Sync Now (Jetzt synchronisieren), um Ihr Projekt zu aktualisieren:
```
  Gradle files have changed since last project sync. A project sync may be
  necessary for the IDE to work properly.
```

CMake für C/C++ Build konfigurieren

Öffnen Sie die CMakeLists.txt-Hauptdatei Ihres Projekts, um die Header-Dateien und die Laufzeitbibliothek für die Memory Advice API in Ihr Projekt einzufügen. Im Bereich Projekt befindet sich die Datei unter app > src > main > cpp. Führe nach dem Öffnen der Datei die folgenden Schritte aus:

Fügen Sie oben in der Datei nach den Zeilen cmake_minimum_required und project die folgende Zeile ein:
```
 find_package(games-memory-advice REQUIRED CONFIG)
```
Fügen Sie im Befehl target_link_libraries den Befehl games-memory-advice::memory_advice hinzu. Dadurch ist die Memory Advice API von der nativen Bibliothek Ihres Projekts abhängig und nimmt sie in Ihr endgültiges Anwendungspaket auf. Das Update sollte in etwa so aussehen:
```
 target_link_libraries(
     your-native-lib

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

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

Java-Dateien konfigurieren

Die native Bibliothek, die in der Memory Advice API enthalten ist, ist libmemory_advice.so. Er ist eine Kompilierungsabhängigkeit für die eigene gemeinsam genutzte Bibliothek C/C++ Ihrer Anwendung. Sie wird automatisch geladen, wenn Ihre Anwendung ihre eigene gemeinsam genutzte Bibliothek mit der Funktion System.loadlibrary() lädt.

Dieser Schritt ist optional.

Suchen Sie in Ihrem Projekt den Java-Code, über den die nativen Bibliotheken geladen werden. Ist dies nicht der Fall, fügen Sie sie hinzu. Der Code sollte ähnlich aussehen wie System.loadLibrary("your-native-lib") und befindet sich in einem static-Block.

Fügen Sie System.loadLibrary("memory_advice") unter System.loadLibrary("your-native-lib") hinzu. Die Aktualisierung sollte in etwa so aussehen:

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

Bibliothek verwenden

In diesem Abschnitt wird die Verwendung der Bibliothek beschrieben.

Headerdateien hinzufügen

Fügen Sie die folgende Bibliotheksheaderdatei in Ihr Projekt ein:

    #include <memory_advice/memory_advice.h>

Bibliothek initialisieren

Du musst die Bibliothek beim Start der App einmal initialisieren. Fügen Sie dazu folgenden Code in Ihr Projekt ein:

    MemoryAdvice_init(env, activity);

Die Parameter env und activity sind die Variablen JNIEnv* und jobject, die für Ihre native Bibliothek verfügbar sein sollten. Jeder JNI-Aufruf an Ihre native Bibliothek sollte diese Variablen enthalten. Wenn Sie die GameActivity-Bibliothek verwenden, müssen Sie den aufrufenden Thread an die JavaVM anhängen, bevor Sie die Funktion MemoryAdvice_init aufrufen.

Arbeitsspeicherstatus abfragen

Sie können den Arbeitsspeicherstatus Ihrer Anwendung abrufen, indem Sie die Bibliothek im gewünschten Intervall abfragen. Verwenden Sie die Funktion MemoryAdvice_getMemoryState immer dann, wenn Sie die Bibliothek abfragen müssen:

    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;
    }

Watcher einrichten

Sie können auch einen Watcher einrichten und die Memory Advice API registrieren. Die Watcher-Funktion wird dann aufgerufen, wenn sich der Status entweder dem Limit oder dem kritischen Arbeitsspeicherstatus nähert (aber nicht für den Zustand „OK“). Mit dem folgenden Code wird beispielsweise ein Watcher erstellt und alle zwei Sekunden eine Memory Advice API-Benachrichtigung angefordert:

    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);

Nächste Schritte

In der Übersicht finden Sie weitere Ressourcen und Probleme mit Berichten.