הגדרת השירות של ART

לפני שמתחילים, כדאי לקרוא את הסקירה הכללית על שירות ART.

החל מ-Android 14, הידור AOT באפליקציות במכשיר (שנקרא גם dexopt) מטופל על ידי שירות ART. שירות ART הוא חלק ממודול ART, ואפשר להתאים אותו אישית באמצעות מאפייני מערכת וממשקי API.

מאפייני מערכת

שירות ART תומך בכל האפשרויות הרלוונטיות של dex2oat.

בנוסף, שירות ART תומך במאפייני המערכת הבאים:

thought pm.dexopt.<reason>

זו קבוצה של מאפייני מערכת שקובעים את מסנני ברירת המחדל של המקמפל לכל סיבות הקימפול שמוגדרות מראש ומתוארות בתרחישים של Dexopt.

מידע נוסף זמין במאמר מסנני קומפיילר.

ערכי ברירת המחדל הרגילים הם:

pm.dexopt.first-boot=verify
pm.dexopt.boot-after-ota=verify
pm.dexopt.boot-after-mainline-update=verify
pm.dexopt.bg-dexopt=speed-profile
pm.dexopt.inactive=verify
pm.dexopt.cmdline=verify

pm.dexopt.shared (ברירת מחדל: speed)

זהו מסנן הקומפיילר החלופי לאפליקציות שמשמשות אפליקציות אחרות.

באופן עקרוני, שירות ART מבצע קומפילציה מבוססת-פרופיל (speed-profile) לכל האפליקציות כשאפשר, בדרך כלל במהלך dexopt ברקע. עם זאת, יש אפליקציות שמשמשות אפליקציות אחרות (דרך <uses-library> או נטענות באופן דינמי באמצעות Context#createPackageContext עם CONTEXT_INCLUDE_CODE). אפליקציות כאלה לא יכולות להשתמש בפרופילים מקומיים מטעמי פרטיות.

באפליקציה כזו, אם מתבקשת קומפילציה מבוססת-פרופיל, שירות ART מנסה קודם להשתמש בפרופיל בענן. אם אין פרופיל Cloud Profiler, שירות ART משתמש במסנן המקמפל שצוין על ידי pm.dexopt.shared.

אם הקומפילציה המבוקשת לא מבוססת על פרופיל, למאפיין הזה אין השפעה.

‫pm.dexopt.<reason>.concurrency (ברירת המחדל: 1)

זהו מספר ההפעלות של dex2oat מסיבות קומפילציה מסוימות שהוגדרו מראש (first-boot,‏ boot-after-ota,‏ boot-after-mainline-update ו-bg-dexopt).

שימו לב שההשפעה של האפשרות הזו משולבת עם אפשרויות השימוש במשאבים של dex2oat (dalvik.vm.*dex2oat-threads, dalvik.vm.*dex2oat-cpu-set ופרופילי המשימות):

  • dalvik.vm.*dex2oat-threads שולט במספר השרשורים לכל הפעלה של dex2oat, ו-pm.dexopt.<reason>.concurrency שולט במספר ההפעלות של dex2oat. כלומר, המספר המקסימלי של שרשורים בו-זמניים הוא המכפלה של שני מאפייני המערכת.
  • ‫dalvik.vm.*dex2oat-cpu-set והפרופילים של המשימות תמיד מגבילים את השימוש בליבות המעבד (CPU), בלי קשר למספר המקסימלי של הליכי המשנה בו-זמנית (שנדון למעלה).

יכול להיות שהפעלה אחת של dex2oat לא תנצל את כל ליבות המעבד (CPU), בלי קשר ל-dalvik.vm.*dex2oat-threads. לכן, הגדלת מספר הקריאות ל-dex2oat (pm.dexopt.<reason>.concurrency) יכולה לשפר את השימוש בליבות המעבד (CPU) ולהאיץ את ההתקדמות הכוללת של dexopt. זה שימושי במיוחד במהלך ההפעלה.

עם זאת, יותר מדי קריאות ל-dex2oat עלולות לגרום למכשיר לחרוג ממגבלת הזיכרון, למרות שאפשר למנוע את זה על ידי הגדרת dalvik.vm.dex2oat-swap ל-true כדי לאפשר שימוש בקובץ החלפה. יותר מדי הפעלות עלולות גם לגרום להחלפת הקשר מיותרת. לכן, צריך להתאים את המספר הזה בקפידה לכל מוצר בנפרד.

‫pm.dexopt.downgrade_after_inactive_days (ברירת מחדל: לא מוגדר)

אם האפשרות הזו מוגדרת, שירות ART מבצע אופטימיזציה של קובצי DEX רק לאפליקציות שהיו בשימוש במספר הימים האחרונים שצוין.

בנוסף, אם נפח האחסון כמעט נגמר, במהלך dexopt ברקע, שירות ART משדרג לאחור את מסנן המקמפל של אפליקציות שלא היו בשימוש במספר הימים האחרונים שצוין, כדי לפנות מקום. הסיבה לכך היא inactive, והמסנן של הקומפיילר נקבע לפי pm.dexopt.inactive. סף המקום הפנוי להפעלת התכונה הזו הוא סף המקום הפנוי הנמוך של מנהל האחסון (ניתן להגדרה באמצעות ההגדרות הגלובליות sys_storage_threshold_percentage ו-sys_storage_threshold_max_bytes, ברירת המחדל: 500MB) בתוספת 500MB.

אם מתאימים אישית את רשימת החבילות באמצעות ArtManagerLocal#setBatchDexoptStartCallback, החבילות ברשימה שסופקה על ידי BatchDexoptStartCallback עבור bg-dexopt אף פעם לא משודרגות לאחור.

‫pm.dexopt.disable_bg_dexopt (ברירת מחדל: false)

האוסף הזה מיועד לבדיקה בלבד. היא מונעת מ-ART Service לתזמן את משימת dexopt ברקע.

אם משימת dexopt ברקע כבר מתוזמנת אבל עדיין לא הופעלה, לאפשרות הזו אין השפעה. כלומר, המשימה עדיין תפעל.

כדי למנוע את ההפעלה של משימת dexopt ברקע, מומלץ להשתמש ברצף הפקודות הבא:

setprop pm.dexopt.disable_bg_dexopt true
pm bg-dexopt-job --disable

השורה הראשונה מונעת את התזמון של משימת dexopt ברקע, אם היא עדיין לא תזומנה. השורה השנייה מבטלת את התזמון של משימת dexopt ברקע, אם היא כבר מתוזמנת, ומבטלת את משימת dexopt ברקע באופן מיידי, אם היא פועלת.

ממשקי API של שירות ART

שירות ART חושף ממשקי API של Java להתאמה אישית. ממשקי ה-API מוגדרים ב-ArtManagerLocal. אפשר לעיין ב-Javadoc ב-art/libartservice/service/java/com/android/server/art/ArtManagerLocal.java כדי לראות דוגמאות לשימוש (קוד מקור של Android 14, קוד מקור של פיתוח שלא פורסם).

‫ArtManagerLocal הוא סינגלטון שמוחזק על ידי LocalManagerRegistry. פונקציית העזר com.android.server.pm.DexOptHelper#getArtManagerLocal עוזרת לקבל אותו.

import static com.android.server.pm.DexOptHelper.getArtManagerLocal;

רוב ממשקי ה-API דורשים מופע של PackageManagerLocal.FilteredSnapshot, שמכיל את המידע של כל האפליקציות. אפשר לקבל אותו על ידי קריאה ל-PackageManagerLocal#withFilteredSnapshot, כאשר PackageManagerLocal הוא גם סינגלטון שמוחזק על ידי LocalManagerRegistry ואפשר לקבל אותו מ-com.android.server.pm.PackageManagerServiceUtils#getPackageManagerLocal.

import static com.android.server.pm.PackageManagerServiceUtils.getPackageManagerLocal;

הנה כמה תרחישים נפוצים לשימוש בממשקי ה-API.

הפעלת dexopt לאפליקציה

אפשר להפעיל את dexopt לכל אפליקציה בכל שלב על ידי קריאה ל-ArtManagerLocal#dexoptPackage.

try (var snapshot = getPackageManagerLocal().withFilteredSnapshot()) {
  getArtManagerLocal().dexoptPackage(
      snapshot,
      "com.google.android.calculator",
      new DexoptParams.Builder(ReasonMapping.REASON_INSTALL).build());
}

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

try (var snapshot = getPackageManagerLocal().withFilteredSnapshot()) {
  getArtManagerLocal().dexoptPackage(
      snapshot,
      "com.google.android.calculator",
      new DexoptParams.Builder("my-reason")
          .setCompilerFilter("speed-profile")
          .setPriorityClass(ArtFlags.PRIORITY_BACKGROUND)
          .build());
}

ביטול dexopt

אם פעולה מתחילה באמצעות קריאה ל-dexoptPackage, אפשר להעביר אות ביטול שמאפשר לבטל את הפעולה בשלב כלשהו. זה יכול להיות שימושי כשמפעילים את dexopt באופן אסינכרוני.

Executor executor = ...;  // Your asynchronous executor here.
var cancellationSignal = new CancellationSignal();
executor.execute(() -> {
  try (var snapshot = getPackageManagerLocal().withFilteredSnapshot()) {
    getArtManagerLocal().dexoptPackage(
        snapshot,
        "com.google.android.calculator",
        new DexoptParams.Builder(ReasonMapping.REASON_INSTALL).build(),
        cancellationSignal);
  }
});

// When you want to cancel the operation.
cancellationSignal.cancel();

אפשר גם לבטל את dexopt ברקע, שמופעל על ידי ART Service.

getArtManagerLocal().cancelBackgroundDexoptJob();

קבלת תוצאות של dexopt

אם פעולה מתחילה באמצעות קריאה ל-dexoptPackage, אפשר לקבל את התוצאה מהערך המוחזר.

DexoptResult result;
try (var snapshot = getPackageManagerLocal().withFilteredSnapshot()) {
  result = getArtManagerLocal().dexoptPackage(...);
}

// Process the result here.
...

בנוסף, ART Service מפעיל בעצמו פעולות dexopt בתרחישים רבים, כמו dexopt ברקע. כדי להאזין לכל התוצאות של dexopt, בין אם הפעולה מתחילה בקריאה ל-dexoptPackage ובין אם היא מתחילה בשירות ART, צריך להשתמש ב-ArtManagerLocal#addDexoptDoneCallback.

getArtManagerLocal().addDexoptDoneCallback(
    false /* onlyIncludeUpdates */,
    Runnable::run,
    (result) -> {
      // Process the result here.
      ...
    });

הארגומנט הראשון קובע אם לכלול רק עדכונים בתוצאה. אם רוצים להאזין רק לחבילות שמעודכנות על ידי dexopt, צריך להגדיר את הערך כ-true.

הארגומנט השני הוא ה-executor של הקריאה החוזרת (callback). כדי להפעיל את הקריאה החוזרת באותו ה-thread שמבצע את dexopt, משתמשים ב-Runnable::run. אם אתם לא רוצים שהקריאה החוזרת תחסום את dexopt, השתמשו ב-executor אסינכרוני.

אפשר להוסיף כמה קריאות חוזרות, ושירות ART יבצע את כולן ברצף. כל פונקציות ה-callback יישארו פעילות בכל השיחות העתידיות, אלא אם תסירו אותן.

כדי להסיר קריאה חוזרת, צריך לשמור את ההפניה לקריאה החוזרת כשמוסיפים אותה, ולהשתמש ב-ArtManagerLocal#removeDexoptDoneCallback.

DexoptDoneCallback callback = (result) -> {
  // Process the result here.
  ...
};

getArtManagerLocal().addDexoptDoneCallback(
    false /* onlyIncludeUpdates */, Runnable::run, callback);

// When you want to remove it.
getArtManagerLocal().removeDexoptDoneCallback(callback);

התאמה אישית של רשימת החבילות והפרמטרים של dexopt

‫ART Service מפעיל פעולות dexopt בעצמו במהלך ההפעלה וברקע. כדי להתאים אישית את רשימת החבילות או את הפרמטרים של dexopt לפעולות האלה, צריך להשתמש ב-ArtManagerLocal#setBatchDexoptStartCallback.

getArtManagerLocal().setBatchDexoptStartCallback(
    Runnable::run,
    (snapshot, reason, defaultPackages, builder, cancellationSignal) -> {
      switch (reason) {
        case ReasonMapping.REASON_BG_DEXOPT:
          var myPackages = new ArrayList<String>(defaultPackages);
          myPackages.add(...);
          myPackages.remove(...);
          myPackages.sort(...);
          builder.setPackages(myPackages);
          break;
        default:
          // Ignore unknown reasons.
      }
    });

אתם יכולים להוסיף פריטים לרשימת החבילות, להסיר ממנה פריטים, למיין אותה או אפילו להשתמש ברשימה אחרת לגמרי.

הקריאה החוזרת צריכה להתעלם מסיבות לא ידועות, כי יכול להיות שנוסיף עוד סיבות בעתיד.

אפשר להגדיר לכל היותר BatchDexoptStartCallback אחד. הקריאה החוזרת תישאר פעילה לכל השיחות העתידיות, אלא אם תמחקו אותה.

כדי לנקות את הקריאה החוזרת, משתמשים ב-ArtManagerLocal#clearBatchDexoptStartCallback.

getArtManagerLocal().clearBatchDexoptStartCallback();

התאמה אישית של הפרמטרים של משימת dexopt ברקע

כברירת מחדל, משימת dexopt ברקע פועלת פעם ביום כשהמכשיר לא בשימוש ובטעינה. אפשר לשנות את זה באמצעות ArtManagerLocal#setScheduleBackgroundDexoptJobCallback.

getArtManagerLocal().setScheduleBackgroundDexoptJobCallback(
    Runnable::run,
    builder -> {
      builder.setPeriodic(TimeUnit.DAYS.toMillis(2));
    });

אפשר להגדיר לכל היותר ScheduleBackgroundDexoptJobCallback אחד. הקריאה החוזרת תישאר פעילה בכל השיחות הבאות, אלא אם תמחקו אותה.

כדי לנקות את הקריאה החוזרת, משתמשים ב-ArtManagerLocal#clearScheduleBackgroundDexoptJobCallback.

getArtManagerLocal().clearScheduleBackgroundDexoptJobCallback();

השבתה זמנית של dexopt

כל פעולת dexopt שמופעלת על ידי שירות ART מפעילה את BatchDexoptStartCallback. אתם יכולים להמשיך לבטל את הפעולות כדי להשבית את dexopt באופן יעיל.

אם הפעולה שאתם מבטלים היא dexopt ברקע, היא פועלת לפי מדיניות ברירת המחדל לניסיון חוזר (30 שניות, אקספוננציאלי, מוגבל ל-5 שעות).

// Good example.

var shouldDisableDexopt = new AtomicBoolean(false);

getArtManagerLocal().setBatchDexoptStartCallback(
    Runnable::run,
    (snapshot, reason, defaultPackages, builder, cancellationSignal) -> {
      if (shouldDisableDexopt.get()) {
        cancellationSignal.cancel();
      }
    });

// Disable dexopt.
shouldDisableDexopt.set(true);
getArtManagerLocal().cancelBackgroundDexoptJob();

// Re-enable dexopt.
shouldDisableDexopt.set(false);

אפשר להגדיר רק BatchDexoptStartCallback אחד. אם רוצים להשתמש גם ב-BatchDexoptStartCallback כדי להתאים אישית את רשימת החבילות או את הפרמטרים של dexopt, צריך לשלב את הקוד ב-callback אחד.

// Bad example.

// Disable dexopt.
getArtManagerLocal().unscheduleBackgroundDexoptJob();

// Re-enable dexopt.
getArtManagerLocal().scheduleBackgroundDexoptJob();

פעולת ה-dexopt שמתבצעת בהתקנת האפליקציה לא מופעלת על ידי שירות ART. במקום זאת, מנהל החבילות מפעיל אותו באמצעות קריאה ל-dexoptPackage. לכן, הוא לא מפעיל את BatchDexoptStartCallback. כדי להשבית את dexopt בהתקנת אפליקציה, צריך למנוע ממנהל החבילות לקרוא ל-dexoptPackage.

שינוי מסנן המהדר לחבילות מסוימות (Android מגרסה 15 ואילך)

אפשר לשנות את מסנן המקמפל לחבילות מסוימות על ידי רישום קריאה חוזרת (callback) דרך setAdjustCompilerFilterCallback. הקריאה החוזרת (callback) מתבצעת בכל פעם שחבילה עומדת לעבור dexopt, לא משנה אם ה-dexopt מופעל על ידי שירות ART במהלך ההפעלה ו-dexopt ברקע או על ידי קריאה ל-API של dexoptPackage.

אם לא צריך לשנות את החבילה, הקריאה החוזרת צריכה להחזיר את הערך originalCompilerFilter.

getArtManagerLocal().setAdjustCompilerFilterCallback(
    Runnable::run,
    (packageName, originalCompilerFilter, reason) -> {
      if (isVeryImportantPackage(packageName)) {
        return "speed-profile";
      }
      return originalCompilerFilter;
    });

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

כדי לנקות את הקריאה החוזרת, משתמשים ב-ArtManagerLocal#clearAdjustCompilerFilterCallback.

getArtManagerLocal().clearAdjustCompilerFilterCallback();

התאמות אישיות אחרות

‫ART Service תומך גם בהתאמות אישיות אחרות.

הגדרת סף הטמפרטורה ל-dexopt ברקע

הבקרה התרמית של משימת dexopt ברקע מבוצעת על ידי מתזמן המשימות. המשימה תבוטל באופן מיידי כשהטמפרטורה תגיע ל-THERMAL_STATUS_MODERATE. אפשר לשנות את הסף של THERMAL_STATUS_MODERATE.

איך בודקים אם dexopt פועל ברקע

משימת dexopt ברקע מנוהלת על ידי Job Scheduler, ומזהה המשימה שלה הוא 27873780. כדי לקבוע אם המשימה פועלת ב-Android מגרסה 16 ואילך, משתמשים ב-JobScheduler#getPendingJobReasons (ב-Android מגרסאות 14 ו-15, משתמשים ב-JobScheduler#getPendingJobReason במקום זאת).

// Good example (Android 16 and higher).

var jobScheduler =
    Objects.requireNonNull(mContext.getSystemService(JobScheduler.class));
int[] reasons = jobScheduler.getPendingJobReasons(27873780);

if (Arrays.stream(reasons).anyMatch(r -> r == PENDING_JOB_REASON_EXECUTING)) {
  // Do something when the job is running.
  ...
}
// Bad example.

var backgroundDexoptRunning = new AtomicBoolean(false);

getArtManagerLocal().setBatchDexoptStartCallback(
    Runnable::run,
    (snapshot, reason, defaultPackages, builder, cancellationSignal) -> {
      if (reason.equals(ReasonMapping.REASON_BG_DEXOPT)) {
        backgroundDexoptRunning.set(true);
      }
    });

getArtManagerLocal().addDexoptDoneCallback(
    false /* onlyIncludeUpdates */,
    Runnable::run,
    (result) -> {
      if (result.getReason().equals(ReasonMapping.REASON_BG_DEXOPT)) {
        backgroundDexoptRunning.set(false);
      }
    });

if (backgroundDexoptRunning.get()) {
  // Do something when the job is running.
  ...
}

הוספת פרופיל ל-dexopt

כדי להשתמש בפרופיל להנחיית dexopt, צריך להציב קובץ .prof או קובץ .dm לצד ה-APK.

הקובץ .prof חייב להיות קובץ פרופיל בפורמט בינארי, ושם הקובץ חייב להיות שם הקובץ של ה-APK בתוספת .prof. לדוגמה,

base.apk.prof

שם הקובץ של קובץ ה-.dm חייב להיות שם הקובץ של ה-APK, כשהסיומת מוחלפת ב-.dm. לדוגמה,

base.dm

כדי לוודא שהפרופיל משמש ל-dexopt, מריצים את dexopt עם speed-profile ובודקים את התוצאה.

pm art clear-app-profiles <package-name>
pm compile -m speed-profile -f -v <package-name>

השורה הראשונה מנקה את כל הפרופילים שנוצרו על ידי סביבת זמן הריצה (כלומר, אלה שב-/data/misc/profiles), אם יש כאלה, כדי לוודא שהפרופיל לצד ה-APK הוא הפרופיל היחיד ששירות ART יכול להשתמש בו. השורה השנייה מריצה את dexopt עם speed-profile, ומעבירה את -v כדי להדפיס את התוצאה המפורטת.

אם הפרופיל נמצא בשימוש, הערך actualCompilerFilter=speed-profile יופיע בתוצאה. אחרת, יוצג הסמל actualCompilerFilter=verify. לדוגמה,

DexContainerFileDexoptResult{dexContainerFile=/data/app/~~QR0fTV0UbDbIP1Su7XzyPg==/com.google.android.gms-LvusF2uARKOtBbcaPHdUtQ==/base.apk, primaryAbi=true, abi=x86_64, actualCompilerFilter=speed-profile, status=PERFORMED, dex2oatWallTimeMillis=4549, dex2oatCpuTimeMillis=14550, sizeBytes=3715344, sizeBeforeBytes=3715344}

סיבות נפוצות לכך ש-ART Service לא משתמש בפרופיל:

  • שם הקובץ של הפרופיל שגוי או שהוא לא נמצא ליד ה-APK.
  • הפרופיל בפורמט שגוי.
  • הפרופיל לא תואם ל-APK. (סיכומי הביקורת בפרופיל לא תואמים לסיכומי הביקורת של קובצי ה-.dex ב-APK).