Konfiguracja usługi ART

Zanim zaczniesz, zapoznaj się z ogólnymi informacjami o usłudze ART.

Począwszy od Androida 14 kompilacja AOT na urządzeniu w przypadku aplikacji (czyli dexopt) jest obsługiwana przez usługę ART. Usługa ART jest częścią modułu ART i można ją dostosowywać za pomocą właściwości systemu i interfejsów API.

Właściwości systemowe

Usługa ART obsługuje wszystkie odpowiednie opcje dex2oat.

Dodatkowo usługa ART obsługuje te właściwości systemu:

thought pm.dexopt.<reason>

Jest to zestaw właściwości systemowych, które określają domyślne filtry kompilatora dla wszystkich wstępnie zdefiniowanych przyczyn kompilacji opisanych w scenariuszach Dexopt.

Więcej informacji znajdziesz w sekcji Filtry kompilatora.

Standardowe wartości domyślne:

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 (domyślnie: speed)

Jest to zastępczy filtr kompilatora dla aplikacji używanych przez inne aplikacje.

Zasadniczo usługa ART wykonuje kompilację na podstawie profilu (speed-profile) dla wszystkich aplikacji, gdy jest to możliwe, zwykle podczas dexopt w tle. Istnieją jednak aplikacje, które są używane przez inne aplikacje (za pomocą <uses-library> lub ładowane dynamicznie za pomocą Context#createPackageContext z CONTEXT_INCLUDE_CODE). Ze względu na ochronę prywatności takie aplikacje nie mogą używać profili lokalnych.

W przypadku takiej aplikacji, jeśli wymagana jest kompilacja na podstawie profilu, usługa ART najpierw próbuje użyć profilu w chmurze. Jeśli profil Cloud Profiler nie istnieje, usługa ART używa filtra kompilatora określonego przez pm.dexopt.shared.

Jeśli żądana kompilacja nie jest oparta na profilu, ta właściwość nie ma wpływu.

thought pm.dexopt.<reason>.concurrency (domyślnie: 1)

Jest to liczba wywołań dex2oat z określonych, wstępnie zdefiniowanych powodów kompilacji (first-boot, boot-after-ota, boot-after-mainline-update i bg-dexopt).

Pamiętaj, że efekt tej opcji jest połączony z opcjami wykorzystania zasobów dex2oat (dalvik.vm.*dex2oat-threads, dalvik.vm.*dex2oat-cpu-set i profile zadań):

  • dalvik.vm.*dex2oat-threads określa liczbę wątków dla każdego wywołania dex2oat, a pm.dexopt.<reason>.concurrency – liczbę wywołań dex2oat. Oznacza to, że maksymalna liczba równoczesnych wątków jest iloczynem tych 2 właściwości systemu.
  • dalvik.vm.*dex2oat-cpu-set i profile zadań zawsze ograniczają wykorzystanie rdzeni procesora, niezależnie od maksymalnej liczby wątków równoczesnych (omówionej powyżej).

Pojedyncze wywołanie dex2oat może nie wykorzystywać w pełni wszystkich rdzeni procesora, niezależnie od wartości dalvik.vm.*dex2oat-threads. Dlatego zwiększenie liczby wywołań dex2oat (pm.dexopt.<reason>.concurrency) może poprawić wykorzystanie rdzeni procesora i przyspieszyć ogólny postęp dexopt. Jest to szczególnie przydatne podczas uruchamiania.

Jednak zbyt wiele wywołań dex2oat może spowodować, że na urządzeniu zabraknie pamięci. Można temu zapobiec, ustawiając dalvik.vm.dex2oat-swap na true, aby umożliwić korzystanie z pliku wymiany. Zbyt wiele wywołań może też powodować niepotrzebne przełączanie kontekstu. Dlatego tę liczbę należy dokładnie dostosować do każdego produktu.

pm.dexopt.downgrade_after_inactive_days (domyślnie: nie ustawiono)

Jeśli ta opcja jest ustawiona, usługa ART optymalizuje tylko aplikacje używane w ciągu ostatniej podanej liczby dni.

Dodatkowo, jeśli pamięć jest prawie pełna, podczas dexopt w tle usługa ART obniża poziom filtra kompilatora aplikacji, które nie były używane w ciągu ostatnich kilku dni, aby zwolnić miejsce. Powód kompilatora to inactive, a filtr kompilatora jest określany przez pm.dexopt.inactive. Próg miejsca, który aktywuje tę funkcję, to próg małej ilości miejsca w Menedżerze pamięci (można go skonfigurować w ustawieniach globalnych sys_storage_threshold_percentage i sys_storage_threshold_max_bytes, domyślnie: 500 MB) plus 500 MB.

Jeśli dostosujesz listę pakietów za pomocą ArtManagerLocal#setBatchDexoptStartCallback, pakiety z listy dostarczonej przez BatchDexoptStartCallback dla bg-dexopt nigdy nie zostaną zastąpione starszymi wersjami.

pm.dexopt.disable_bg_dexopt (domyślnie: false)

Służy tylko do testowania. Uniemożliwia usłudze ART zaplanowanie zadania dexopt w tle.

Jeśli zadanie dexopt w tle jest już zaplanowane, ale jeszcze nie zostało uruchomione, ta opcja nie ma wpływu. Oznacza to, że zadanie nadal będzie wykonywane.

Zalecana sekwencja poleceń, która zapobiega uruchamianiu zadania dexopt w tle:

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

Pierwszy wiersz zapobiega zaplanowaniu zadania dexopt w tle, jeśli nie zostało jeszcze zaplanowane. Drugi wiersz anuluje zaplanowane zadanie dexopt w tle, jeśli jest już zaplanowane, i natychmiast anuluje zadanie dexopt w tle, jeśli jest uruchomione.

Interfejsy API usługi ART

Usługa ART udostępnia interfejsy API Javy na potrzeby dostosowywania. Interfejsy API są zdefiniowane w pliku ArtManagerLocal. Informacje o użyciu znajdziesz w dokumentacji Javadoc w art/libartservice/service/java/com/android/server/art/ArtManagerLocal.java (kod źródłowy Androida 14, nieopublikowany kod źródłowy).

ArtManagerLocal to singleton przechowywany przez LocalManagerRegistry. Funkcja pomocnicza com.android.server.pm.DexOptHelper#getArtManagerLocal ułatwia jego uzyskanie.

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

Większość interfejsów API wymaga instancji PackageManagerLocal.FilteredSnapshot, która zawiera informacje o wszystkich aplikacjach. Możesz go uzyskać, wywołując PackageManagerLocal#withFilteredSnapshot, gdzie PackageManagerLocal jest również singletonem przechowywanym przez LocalManagerRegistry i można go uzyskać z com.android.server.pm.PackageManagerServiceUtils#getPackageManagerLocal.

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

Oto kilka typowych przypadków użycia interfejsów API.

Aktywowanie dexopt dla aplikacji

Możesz uruchomić dexopt dla dowolnej aplikacji w dowolnym momencie, wywołując ArtManagerLocal#dexoptPackage.

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

Możesz też przekazać własny powód dexopt. W takim przypadku należy wyraźnie ustawić klasę priorytetu i filtr kompilatora.

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

Anuluj dexopt

Jeśli operacja jest inicjowana przez wywołanie dexoptPackage, możesz przekazać sygnał anulowania, który pozwoli Ci anulować operację w określonym momencie. Może to być przydatne, gdy dexopt działa asynchronicznie.

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

Możesz też anulować dexopt w tle, który jest inicjowany przez usługę ART.

getArtManagerLocal().cancelBackgroundDexoptJob();

Pobieranie wyników dexopt

Jeśli operacja została zainicjowana przez wywołanie dexoptPackage, możesz uzyskać wynik z wartości zwracanej.

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

// Process the result here.
...

Usługa ART sama inicjuje operacje dexopt w wielu scenariuszach, np. dexopt w tle. Aby nasłuchiwać wszystkich wyników dexopt, niezależnie od tego, czy operacja została zainicjowana przez wywołanie dexoptPackage czy przez usługę ART, użyj ArtManagerLocal#addDexoptDoneCallback.

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

Pierwszy argument określa, czy w wyniku mają być uwzględniane tylko aktualizacje. Jeśli chcesz nasłuchiwać tylko pakietów aktualizowanych przez dexopt, ustaw wartość „true”.

Drugi argument to wykonawca wywołania zwrotnego. Aby wykonać wywołanie zwrotne w tym samym wątku, który wykonuje dexopt, użyj Runnable::run. Jeśli nie chcesz, aby wywołanie zwrotne blokowało dexopt, użyj asynchronicznego wykonawcy.

Możesz dodać wiele wywołań zwrotnych, a usługa ART wykona je wszystkie po kolei. Wszystkie wywołania zwrotne pozostaną aktywne w przypadku wszystkich przyszłych połączeń, chyba że je usuniesz.

Jeśli chcesz usunąć wywołanie zwrotne, zachowaj jego odwołanie podczas dodawania i użyj 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);

Dostosowywanie listy pakietów i parametrów dexopt

Usługa ART sama inicjuje operacje dexopt podczas uruchamiania i w tle. Aby dostosować listę pakietów lub parametry dexopt dla tych operacji, użyj 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.
      }
    });

Możesz dodawać elementy do listy pakowania, usuwać je, sortować, a nawet użyć zupełnie innej listy.

Wywołanie zwrotne musi ignorować nieznane przyczyny, ponieważ w przyszłości mogą zostać dodane kolejne.

Możesz ustawić maksymalnie 1 BatchDexoptStartCallback. Wywołanie zwrotne pozostanie aktywne we wszystkich przyszłych połączeniach, chyba że je usuniesz.

Jeśli chcesz usunąć wywołanie zwrotne, użyj ArtManagerLocal#clearBatchDexoptStartCallback.

getArtManagerLocal().clearBatchDexoptStartCallback();

Dostosowywanie parametrów zadania dexopt w tle

Domyślnie zadanie dexopt w tle jest uruchamiane raz dziennie, gdy urządzenie jest bezczynne i się ładuje. Można to zmienić za pomocą ArtManagerLocal#setScheduleBackgroundDexoptJobCallback.

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

Możesz ustawić maksymalnie 1 ScheduleBackgroundDexoptJobCallback. Wywołanie zwrotne pozostanie aktywne we wszystkich przyszłych połączeniach, dopóki go nie wyczyścisz.

Jeśli chcesz usunąć wywołanie zwrotne, użyj ArtManagerLocal#clearScheduleBackgroundDexoptJobCallback.

getArtManagerLocal().clearScheduleBackgroundDexoptJobCallback();

Tymczasowo wyłącz dexopt

Każda operacja dexopt inicjowana przez usługę ART wywołuje zdarzenie BatchDexoptStartCallback. Możesz anulować operacje, aby skutecznie wyłączyć dexopt.

Jeśli anulowana operacja to dexopt w tle, obowiązują domyślne zasady ponawiania (30 sekund, wykładniczo, maksymalnie 5 godzin).

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

Możesz mieć maksymalnie 1 BatchDexoptStartCallback. Jeśli chcesz też używać BatchDexoptStartCallback do dostosowywania listy pakietów lub parametrów dexopt, musisz połączyć kod w jedną funkcję wywołania zwrotnego.

// Bad example.

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

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

Operacja dexopt wykonywana podczas instalacji aplikacji nie jest inicjowana przez usługę ART. Zamiast tego jest inicjowane przez menedżera pakietów za pomocą wywołania dexoptPackage. Dlatego nie uruchamia on reguły BatchDexoptStartCallback. Aby wyłączyć dexopt podczas instalacji aplikacji, uniemożliw menedżerowi pakietów wywoływanie dexoptPackage.

Zastępowanie filtra kompilatora w przypadku niektórych pakietów (Android 15 lub nowszy)

Możesz zastąpić filtr kompilatora w przypadku niektórych pakietów, rejestrując wywołanie zwrotne za pomocą setAdjustCompilerFilterCallback. Wywołanie zwrotne jest wywoływane za każdym razem, gdy pakiet ma zostać poddany optymalizacji dexopt, niezależnie od tego, czy optymalizacja dexopt jest inicjowana przez usługę ART podczas uruchamiania i optymalizacji dexopt w tle, czy przez wywołanie interfejsu API dexoptPackage.

Jeśli pakiet nie wymaga dostosowania, wywołanie zwrotne musi zwrócić wartość originalCompilerFilter.

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

Możesz ustawić tylko 1 AdjustCompilerFilterCallback. Jeśli chcesz użyć AdjustCompilerFilterCallback do zastąpienia filtra kompilatora w przypadku wielu pakietów, musisz połączyć kod w jedną funkcję wywołania zwrotnego. Wywołanie zwrotne pozostaje aktywne we wszystkich przyszłych połączeniach, dopóki go nie usuniesz.

Jeśli chcesz usunąć wywołanie zwrotne, użyj ArtManagerLocal#clearAdjustCompilerFilterCallback.

getArtManagerLocal().clearAdjustCompilerFilterCallback();

Inne dostosowania

Usługa ART obsługuje też inne dostosowania.

Ustaw próg temperatury dla dexopt w tle

Kontrolę temperatury zadania dexopt w tle przeprowadza Job Scheduler. Zadanie zostanie natychmiast anulowane, gdy temperatura osiągnie THERMAL_STATUS_MODERATE. Próg THERMAL_STATUS_MODERATE można dostosować.

Sprawdzanie, czy dexopt działa w tle

Zadaniem dexopt w tle zarządza Job Scheduler, a jego identyfikator zadania to 27873780. Aby określić, czy zadanie jest uruchomione na Androidzie 16 lub nowszym, użyj JobScheduler#getPendingJobReasons (na Androidzie 14 i 15 użyj 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.
  ...
}

Podaj profil dla dexopt

Aby użyć profilu do kierowania dexopt, umieść plik .prof lub .dm obok pliku APK.

Plik .prof musi być plikiem profilu w formacie binarnym, a jego nazwa musi być nazwą pliku APK + .prof. Na przykład

base.apk.prof

Nazwa pliku .dm musi być taka sama jak nazwa pliku APK, ale z rozszerzeniem .dm. Na przykład

base.dm

Aby sprawdzić, czy profil jest używany do dexopt, uruchom dexopt z speed-profile i sprawdź wynik.

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

Pierwszy wiersz usuwa wszystkie profile utworzone przez środowisko wykonawcze (czyli te w /data/misc/profiles), jeśli takie istnieją, aby upewnić się, że profil obok pliku APK jest jedynym profilem, którego może używać usługa ART. Drugi wiersz uruchamia dexopt z speed-profile i przekazuje -v, aby wyświetlić szczegółowy wynik.

Jeśli profil jest używany, w wyniku zobaczysz actualCompilerFilter=speed-profile. W przeciwnym razie zobaczysz actualCompilerFilter=verify. Na przykład

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}

Oto typowe przyczyny, dla których usługa ART nie używa profilu:

  • Profil ma nieprawidłową nazwę pliku lub nie znajduje się obok pakietu APK.
  • Profil ma nieprawidłowy format.
  • Profil nie pasuje do pliku APK. (Sumy kontrolne w profilu nie pasują do sum kontrolnych plików .dex w pliku APK).