Настройка сервиса ART

Прежде чем начать, ознакомьтесь с общими сведениями о сервисе ART.

Начиная с Android 14, компиляция AOT на устройстве для приложений (также известная как dexopt) обрабатывается ART Service. ART Service – это часть модуля ART, которую можно настраивать с помощью системных свойств и API.

Свойства системы

ART Service поддерживает все необходимые параметры dex2oat.

Кроме того, ART Service поддерживает следующие системные свойства:

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 Service выполняет компиляцию на основе профиля (speed-profile) для всех приложений, когда это возможно, обычно во время фоновой оптимизации dexopt. Однако некоторые приложения используются другими приложениями (через <uses-library> или динамически загружаются с помощью Context#createPackageContext с CONTEXT_INCLUDE_CODE). Такие приложения не могут использовать локальные профили из соображений конфиденциальности.

Если для такого приложения запрашивается компиляция на основе профиля, ART Service сначала пытается использовать облачный профиль. Если облачного профиля нет, ART Service использует фильтр компилятора, указанный в 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, а профили задач всегда ограничивают использование ядер ЦП, независимо от максимального количества параллельных потоков (см. выше).

Один вызов dex2oat может не полностью использовать все ядра ЦП, независимо от значения dalvik.vm.*dex2oat-threads. Поэтому увеличение количества вызовов dex2oat (pm.dexopt.<reason>.concurrency) может повысить эффективность использования ядер ЦП и ускорить процесс dexopt. Это особенно полезно во время загрузки.

Однако слишком большое количество вызовов dex2oat может привести к нехватке памяти на устройстве. Чтобы этого избежать, можно задать для параметра dalvik.vm.dex2oat-swap значение true, разрешив использование файла подкачки. Слишком большое количество вызовов также может привести к ненужному переключению контекста. Поэтому это число следует тщательно настраивать для каждого продукта.

pm.dexopt.downgrade_after_inactive_days (по умолчанию не задано)

Если этот параметр задан, ART Service оптимизирует только приложения, которые использовались в течение указанного количества дней.

Кроме того, если на устройстве заканчивается свободное место, во время фоновой оптимизации dexopt сервис ART понижает уровень фильтра компилятора для приложений, которые не использовались в течение определенного количества дней. Причина компиляции – inactive, а фильтр компиляции определяется по pm.dexopt.inactive. Пороговое значение для запуска этой функции – это пороговое значение низкого объема свободного пространства в Менеджере хранилища (настраивается с помощью глобальных настроек sys_storage_threshold_percentage и sys_storage_threshold_max_bytes, по умолчанию – 500 МБ) плюс 500 МБ.

Если вы настроите список пакетов с помощью 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 Service предоставляет Java API для настройки. 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, независимо от того, инициирована ли операция вызовом dexoptPackage или ART Service, используйте ArtManagerLocal#addDexoptDoneCallback.

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

Первый аргумент определяет, нужно ли включать в результат только обновления. Если вы хотите прослушивать только пакеты, обновленные dexopt, установите значение true.

Второй аргумент – исполнитель обратного вызова. Чтобы выполнить обратный вызов в том же потоке, в котором выполняется dexopt, используйте Runnable::run. Если вы не хотите, чтобы обратный вызов блокировал dexopt, используйте асинхронный исполнитель.

Вы можете добавить несколько обратных вызовов, и ART Service выполнит их все последовательно. Все обратные вызовы будут активны для всех будущих вызовов, пока вы их не удалите.

Если вы хотите удалить обратный вызов, сохраните ссылку на него при добавлении и используйте 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 Service, запускает BatchDexoptStartCallback. Вы можете отменять операции, чтобы отключить dexopt.

Если вы отмените фоновую оптимизацию dex, будет использоваться правило повтора по умолчанию (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, объедините код в один обратный вызов.

// Bad example.

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

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

Операция dexopt, выполняемая при установке приложения, не инициируется ART Service. Вместо этого он инициируется менеджером пакетов через вызов dexoptPackage. Поэтому тег BatchDexoptStartCallback не активируется. Чтобы отключить dexopt при установке приложения, запретите менеджеру пакетов вызывать dexoptPackage.

Переопределение фильтра компилятора для определенных пакетов (Android 15 и более поздних версий)

Вы можете переопределить фильтр компилятора для определенных пакетов, зарегистрировав обратный вызов через setAdjustCompilerFilterCallback. Обратный вызов выполняется каждый раз, когда пакет должен быть оптимизирован с помощью dexopt, независимо от того, инициирована ли оптимизация сервисом ART во время загрузки и фоновой оптимизации или вызовом 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 управляется планировщиком заданий, а его идентификатор задания – 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 Service. Вторая строка запускает 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.