איך מתחילים להשתמש ב-Memory Adwise API

במדריך הזה מוסבר איך לשלב את גרסת Jetpack של Memory Advice API באפליקציה באמצעות Android Studio.

במשחקים צריך להשתמש בגרסת Memory Advice API שמומלצת לסביבת הבנייה שלהם. ל-Android Studio, אנחנו ממליצים על גרסת Jetpack. מידע על מהדורות לסביבות בנייה אחרות, כמו Android Game Development Extension‏ (AGDE), זמין במאמר בנושא הפצות.

הוספת הספרייה

בקטע הזה מוסבר איך להוסיף את הספרייה לפרויקט Android Studio (Android Gradle Plugin).

הוספת יחסי התלות

כדי להוסיף את הספרייה לפרויקט Android Studio, מבצעים את השלבים הבאים:

מפעילים את ספריית Android Jetpack ברמת הפרויקט gradle.properties). הקובץ בדרך כלל נמצא בספריית השורש של הפרויקט:
```
  android.useAndroidX=true
```
פותחים את הקובץ build.gradle ברמת המודול ומוסיפים את השורה הבאה לבלוק dependencies.implementation הפעולה הזו מצהירה על התלויות של ה-API של עצות לשימוש בזיכרון באפליקציה.
```
 dependencies {
     implementation 'androidx.games:games-memory-advice:1.0.0-beta01'
 }
```
מציינים את גרסת ה-NDK בתוך הבלוק android:
```
 ndkVersion "23.1.7779620"
```
חשוב לבחור גרסה של NDK שתואמת ל-Memory Advice API. רשימה של גרסאות NDK נתמכות זמינה בדף הגרסה של Android Games Jetpack.

הצהרה על סימוני build נוספים עבור CMake. כדי לעשות את זה, מוסיפים את הקוד הבא לבלוק defaultConfig שנמצא בתוך הבלוק android:

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

מפעילים את התכונה Prefab. ב-Android Gradle Plugin‏(AGP) מגרסה 4.1 ואילך, מוסיפים את הקוד הבא לבלוק android:
```
 buildFeatures {
    prefab true
 }
```
אם אתם משתמשים ב-AGP 4.0 או בגרסה מוקדמת יותר, תוכלו למצוא הוראות להגדרה בדף בנושא Prefab.
שומרים את הקובץ. אם מוצגת ההודעה הבאה, לוחצים על הלחצן סנכרון עכשיו כדי לעדכן את הפרויקט:
```
  Gradle files have changed since last project sync. A project sync may be
  necessary for the IDE to work properly.
```

הגדרת CMake ל-build של C/C++‎

כדי להוסיף את קובצי הכותרת ואת ספריית זמן הריצה של Memory Advice API לפרויקט, פותחים את הקובץ הראשי CMakeLists.txt של הפרויקט. בחלונית Project (פרויקט), הקובץ נמצא בתיקייה app > src > main > cpp. אחרי שפותחים את הקובץ, מבצעים את השלבים הבאים:

בחלק העליון של הקובץ, מוסיפים את השורה הבאה אחרי השורות cmake_minimum_required ו-project:
```
 find_package(games-memory-advice REQUIRED CONFIG)
```
בפקודה target_link_libraries, מוסיפים את games-memory-advice::memory_advice. כך Memory Advice API הופך לתלות בספרייה המקורית של הפרויקט ונכלל בחבילת האפליקציה הסופית. העדכון אמור להיראות כך:
```
 target_link_libraries(
     your-native-lib

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

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

הגדרת קובצי Java

הספרייה המובנית שכלולה ב-Memory Advice API היא libmemory_advice.so. היא תלויה בהידור של הספרייה המשותפת של C/C++ של האפליקציה, והיא נטענת באופן אוטומטי כשהאפליקציה טוענת את הספרייה המשותפת שלה באמצעות הפונקציה System.loadlibrary().

השלב הזה הוא אופציונלי.

מוצאים את קוד ה-Java בפרויקט שבו נטענות הספריות המקוריות. אם הוא לא קיים, מוסיפים אותו. הקוד צריך להיראות דומה ל-System.loadLibrary("your-native-lib"), והוא ממוקם בבלוק static.

מוסיפים System.loadLibrary("memory_advice") מתחת ל-System.loadLibrary("your-native-lib"). העדכון אמור להיראות כך:

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

שימוש בספרייה

בקטע הזה מוסבר איך משתמשים בספרייה.

הוספת קובצי הכותרת

צריך לכלול את קובץ ה-header של הספרייה הבא בפרויקט:

    #include <memory_advice/memory_advice.h>

הפעלת הספרייה

צריך להפעיל את הספרייה פעם אחת כשהאפליקציה מתחילה לפעול. כדי לעשות זאת, מוסיפים את הקוד הזה לפרויקט:

    MemoryAdvice_init(env, activity);

הפרמטרים env ו-activity הם המשתנים JNIEnv* ו-jobject שצריכים להיות זמינים בספרייה המקורית. כל קריאת JNI לספרייה המקורית צריכה להכיל את המשתנים האלה. אם אתם משתמשים בספריית GameActivity, הקפידו לצרף את ה-thread של הקריאה ל-JavaVM לפני שאתם קוראים לפונקציה MemoryAdvice_init.

סקר לגבי מצב הזיכרון

אתם יכולים לאחזר את מצב הזיכרון של האפליקציה על ידי שליחת שאילתות לספרייה במרווח שתבחרו. משתמשים בפונקציה MemoryAdvice_getMemoryState בכל פעם שצריך לבצע סקר בספרייה:

    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 ולרשום את Memory Advice API, והפונקציה של ה-watcher תקרא כשהמצב מתקרב למגבלה או למצב הזיכרון הקריטי (אבל לא למצב ok). לדוגמה, הקוד הבא יוצר רכיב מעקב ומבקש התראה מ-Memory Advice API כל 2 שניות:

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

השלבים הבאים

בסקירה הכללית מפורטים מקורות מידע נוספים ומוסבר איך מדווחים על בעיות.

איך מתחילים להשתמש ב-Memory Adwise API קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.