Erste Schritte mit der Memory Advice API

In dieser Anleitung wird beschrieben, wie Sie das Jetpack-Release der Memory Advice API mit Android Studio in Ihre App einbinden.

Für Spiele sollte die Memory Advice API-Version verwendet werden, die für die jeweilige Build-Umgebung empfohlen wird. Für Android Studio empfehlen wir die Jetpack-Version. Informationen zu Releases für andere Build-Umgebungen wie die Android Game Development Extension (AGDE) finden Sie unter Bereitstellungen.

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

So fügen Sie die Bibliothek Ihrem Android Studio-Projekt hinzu:

Aktivieren Sie die Android Jetpack-Bibliothek in der Datei gradle.properties auf Projektebene. Diese Datei befindet sich normalerweise im Stammverzeichnis Ihres Projekts:
```
  android.useAndroidX=true
```
Öffnen Sie die Datei build.gradle auf Modulebene und fügen Sie dem Block „dependencies“ das folgende implementation hinzu. Dadurch werden die Abhängigkeiten der Memory Advice API in Ihrer App deklariert.
```
 dependencies {
     implementation 'androidx.games:games-memory-advice:1.0.0-beta01'
 }
```
Geben Sie die NDK-Version im Block android an:
```
 ndkVersion "23.1.7779620"
```
Wählen Sie eine mit der Memory Advice API kompatible NDK-Version aus. Eine Liste der unterstützten NDK-Versionen finden Sie auf der Seite „Android Games Jetpack Release“.

Zusätzliche Build-Flags für CMake deklarieren Fügen Sie dazu den folgenden Code in den defaultConfig-Block ein, der sich im android-Block befindet:

 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 das 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 älter verwenden, finden Sie eine Konfigurationsanleitung auf der Prefab-Seite.
Speichere die Datei. Wenn die folgende Meldung angezeigt wird, klicken Sie auf die Schaltfläche 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

Wenn Sie die Headerdateien und die Laufzeitbibliothek für die Memory Advice API in Ihr Projekt einfügen möchten, öffnen Sie die CMakeLists.txt-Hauptdatei Ihres Projekts. Im Bereich Project (Projekt) befindet sich die Datei unter app > src > main > cpp. Führen Sie nach dem Öffnen der Datei die folgenden Schritte aus:

Fügen Sie oben in der Datei nach allen Zeilen mit cmake_minimum_required und project die folgende Zeile hinzu:
```
 find_package(games-memory-advice REQUIRED CONFIG)
```
Fügen Sie dem Befehl target_link_libraries den Wert games-memory-advice::memory_advice hinzu. Dadurch wird die Memory Advice API zu einer Abhängigkeit der nativen Bibliothek Ihres Projekts und in das endgültige Anwendungspaket aufgenommen. 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. Sie ist eine Kompilierungsabhängigkeit für die eigene gemeinsam genutzte C/C++-Bibliothek Ihrer App und wird automatisch geladen, wenn Ihre App ihre eigene gemeinsam genutzte Bibliothek mit der Funktion System.loadlibrary() lädt.

Dieser Schritt ist optional.

Suchen Sie in Ihrem Projekt nach dem Java-Code, der die nativen Bibliotheken lädt. Wenn sie nicht vorhanden ist, fügen Sie sie hinzu. Der Code sollte in etwa so aussehen wie System.loadLibrary("your-native-lib") und sich in einem static-Block befinden.

Fügen Sie System.loadLibrary("memory_advice") unter System.loadLibrary("your-native-lib") hinzu. Das Update 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 beschrieben, wie Sie die Bibliothek verwenden.

Headerdateien hinzufügen

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

    #include <memory_advice/memory_advice.h>

Bibliothek initialisieren

Sie müssen die Bibliothek einmal beim Start der App initialisieren. Fügen Sie dazu diesen 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 Ihrer nativen 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 Speicherstatus Ihrer App abrufen, indem Sie die Bibliothek in einem von Ihnen gewählten Intervall abfragen. Verwenden Sie die Funktion MemoryAdvice_getMemoryState, 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;
    }

Beobachter einrichten

Sie können auch einen Watcher einrichten und die Memory Advice API registrieren. Ihre Watcher-Funktion wird dann aufgerufen, wenn der Status sich entweder dem Grenzwert nähert oder der kritische Speicherstatus erreicht wird (aber nicht beim Status „ok“). Mit dem folgenden Code wird beispielsweise ein Watcher erstellt und alle 2 Sekunden eine Benachrichtigung über die Memory Advice API 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

Zusätzliche Ressourcen und Informationen zum Melden von Problemen finden Sie in der Übersicht.

Erste Schritte mit der Memory Advice API Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.