با Memory Advice API شروع کنید

این راهنما نحوه ادغام نسخه Jetpack Memory Advice API را در برنامه خود با استفاده از Android Studio شرح می دهد.

بازی ها باید از نسخه Memory Advice API استفاده کنند که برای محیط ساخت آنها توصیه می شود. برای اندروید استودیو، نسخه Jetpack را توصیه می کنیم. برای اطلاعات در مورد نسخه‌های منتشر شده برای محیط‌های ساخت دیگر، مانند برنامه افزودنی توسعه بازی Android (AGDE)، به توزیع‌ها مراجعه کنید.

کتابخانه را اضافه کنید

این بخش نحوه افزودن کتابخانه به پروژه اندروید استودیو (افزونه اندروید Gradle) را توضیح می دهد.

وابستگی ها را اضافه کنید

برای افزودن کتابخانه به پروژه Android Studio خود، مراحل زیر را انجام دهید:

کتابخانه Android Jetpack را در سطح پروژه gradle.properties فعال کنید، فایل معمولاً در فهرست اصلی پروژه شما قرار دارد:
```
  android.useAndroidX=true
```
فایل build.gradle سطح ماژول را باز کنید و 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 Jetpack موجود است.
پرچم های ساخت اضافی را برای 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 مراجعه کنید.
فایل را ذخیره کنید. اگر پیام زیر را مشاهده کردید، روی دکمه Sync Now کلیک کنید تا پروژه خود را به روز کنید:
```
  Gradle files have changed since last project sync. A project sync may be
  necessary for the IDE to work properly.
```

CMake را برای ساخت 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
     #...
 )
```

فایل های جاوا را پیکربندی کنید

کتابخانه بومی همراه با Memory Advice API libmemory_advice.so است. این یک وابستگی کامپایل برای کتابخانه مشترک C/C++ خود برنامه شما است و زمانی که برنامه شما کتابخانه مشترک خود را با تابع System.loadlibrary() بارگیری می کند، به طور خودکار بارگیری می شود.

این مرحله اختیاری است.

کد جاوا را در پروژه خود پیدا کنید که کتابخانه های بومی را بارگیری می کند. اگر وجود ندارد، آن را اضافه کنید. کد باید شبیه 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");
 }
```

از کتابخانه استفاده کنید

در این بخش نحوه استفاده از کتابخانه توضیح داده شده است.

فایل های هدر را اضافه کنید

فایل هدر کتابخانه زیر را در پروژه خود قرار دهید:

    #include <memory_advice/memory_advice.h>

کتابخانه را راه اندازی کنید

وقتی برنامه شروع به کار کرد، باید کتابخانه را یک بار مقداردهی اولیه کنید. برای انجام این کار، این کد را به پروژه خود اضافه کنید:

    MemoryAdvice_init(env, activity);

پارامترهای env و activity متغیرهای JNIEnv* و jobject هستند که باید در کتابخانه اصلی شما در دسترس باشند. هر فراخوانی JNI به کتابخانه بومی شما باید حاوی این متغیرها باشد. اگر از کتابخانه GameActivity استفاده می کنید، قبل از فراخوانی تابع MemoryAdvice_init ، حتماً رشته تماس را به JavaVM وصل کنید .

نظرسنجی برای وضعیت حافظه

شما می توانید وضعیت حافظه برنامه خود را با نظرسنجی از کتابخانه در بازه زمانی مورد نظر خود بازیابی کنید. هر زمان که نیاز به نظرسنجی از کتابخانه دارید از تابع 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 ایجاد می کند و هر 2 ثانیه یک اعلان Memory Advice API درخواست می کند:

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

بعدش چی

برای منابع اضافی و مشکلات گزارش، مرور کلی را ببینید.