Configuração do serviço ART

Antes de começar, confira uma visão geral do serviço ART.

No Android 14 e versões mais recentes, a compilação AOT no dispositivo para apps (também conhecida como dexopt) é processada pelo serviço ART. O ART Service faz parte do módulo ART e pode ser personalizado usando propriedades do sistema e APIs.

Propriedades do sistema

O serviço do ART é compatível com todas as opções relevantes do dex2oat.

Além disso, o ART Service oferece suporte às seguintes propriedades do sistema:

pm.dexopt.<reason>

É um conjunto de propriedades do sistema que determinam os filtros de compilador padrão para todos os motivos de compilação predefinidos descritos em Cenários do Dexopt.

Para mais informações, consulte Filtros do compilador.

Os valores padrão são:

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 (padrão: speed)

Esse é o filtro de fallback do compilador para apps usados por outros apps.

Em princípio, o ART Service faz a compilação guiada por perfil (speed-profile) para todos os apps quando possível, normalmente durante o dexopt em segundo plano. No entanto, existem alguns apps que são usados por outros apps (por <uses-library> ou carregados dinamicamente usando Context#createPackageContext com CONTEXT_INCLUDE_CODE). Esses apps não podem usar perfis locais por motivos de privacidade.

Para esse tipo de app, se a compilação guiada por perfil for solicitada, o serviço ART primeiro vai tentar usar um perfil de nuvem. Se não houver um perfil do Cloud Profiler, o ART Service vai usar o filtro do compilador especificado por pm.dexopt.shared.

Se a compilação solicitada não for guiada por perfil, essa propriedade não terá efeito.

pm.dexopt.<reason>.concurrency (padrão: 1)

Esse é o número de invocações do dex2oat por determinados motivos de compilação predefinidos (first-boot, boot-after-ota, boot-after-mainline-update e bg-dexopt).

O efeito dessa opção é combinado com as opções de uso de recursos do dex2oat (dalvik.vm.*dex2oat-threads, dalvik.vm.*dex2oat-cpu-set e os perfis de tarefa):

  • dalvik.vm.*dex2oat-threads controla o número de linhas de execução para cada invocação dex2oat, enquanto pm.dexopt.<reason>.concurrency controla o número de invocações dex2oat. Ou seja, o número máximo de threads simultâneos é o produto das duas propriedades do sistema.
  • dalvik.vm.*dex2oat-cpu-set e os perfis de tarefa sempre limitam o uso do núcleo da CPU, independentemente do número máximo de linhas de execução simultâneas (discutido acima).

Uma única invocação dex2oat pode não utilizar totalmente todos os núcleos de CPU, independentemente de dalvik.vm.*dex2oat-threads. Portanto, aumentar o número de invocações do dex2oat (pm.dexopt.<reason>.concurrency) pode usar melhor os núcleos da CPU para acelerar o progresso geral do dexopt. Isso é particularmente útil durante a inicialização.

No entanto, ter muitas invocações dex2oat pode fazer com que o dispositivo fique sem memória, embora isso possa ser mitigado definindo dalvik.vm.dex2oat-swap como true para permitir o uso de um arquivo de troca. Muitas invocações também podem causar mudanças de contexto desnecessárias. Portanto, esse número precisa ser ajustado com cuidado para cada produto.

pm.dexopt.downgrade_after_inactive_days (padrão: não definido)

Se essa opção estiver definida, o ART Service só vai fazer a dexopt em apps usados no número de dias especificado.

Além disso, se o armazenamento estiver quase cheio, durante a dexopt em segundo plano, o ART Service vai fazer downgrade do filtro do compilador de apps que não foram usados nos últimos dias para liberar espaço. O motivo do compilador para isso é inactive, e o filtro do compilador é determinado por pm.dexopt.inactive. O limite de espaço para acionar esse recurso é o limite de espaço baixo do Storage Manager (configurável pelas configurações globais sys_storage_threshold_percentage e sys_storage_threshold_max_bytes, padrão: 500 MB) mais 500 MB.

Se você personalizar a lista de pacotes usando ArtManagerLocal#setBatchDexoptStartCallback, os pacotes na lista fornecida pelo BatchDexoptStartCallback para o bg-dexopt nunca vão passar por downgrade.

pm.dexopt.disable_bg_dexopt (padrão: false)

Isso é apenas para testes. Ele impede que o serviço ART programe o job dexopt em segundo plano.

Se o job dexopt em segundo plano já estiver programado, mas ainda não tiver sido executado, essa opção não terá efeito. Ou seja, o job ainda será executado.

Uma sequência recomendada de comandos para impedir que o job dexopt em segundo plano seja executado é:

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

A primeira linha impede que o job dexopt em segundo plano seja programado, caso ainda não esteja. A segunda linha cancela a programação do job de dexopt em segundo plano, se já estiver programado, e cancela o job de dexopt em segundo plano imediatamente, se estiver em execução.

APIs do ART Service

O ART Service expõe APIs Java para personalização. As APIs são definidas em ArtManagerLocal. Consulte o Javadoc em art/libartservice/service/java/com/android/server/art/ArtManagerLocal.java para usos (fonte do Android 14, fonte de desenvolvimento não lançada).

ArtManagerLocal é um singleton mantido por LocalManagerRegistry. Uma função auxiliar com.android.server.pm.DexOptHelper#getArtManagerLocal ajuda você a fazer isso.

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

A maioria das APIs exige uma instância de PackageManagerLocal.FilteredSnapshot, que contém as informações de todos os apps. Para isso, chame PackageManagerLocal#withFilteredSnapshot, em que PackageManagerLocal também é um singleton mantido por LocalManagerRegistry e pode ser recebido de com.android.server.pm.PackageManagerServiceUtils#getPackageManagerLocal.

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

Veja a seguir alguns casos de uso típicos das APIs.

Acionar dexopt para um app

É possível acionar a dexopt para qualquer app a qualquer momento chamando ArtManagerLocal#dexoptPackage.

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

Também é possível transmitir seu próprio motivo de dexopt. Se você fizer isso, a classe de prioridade e o filtro do compilador precisarão ser definidos explicitamente.

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

Cancelar dexopt

Se uma operação for iniciada por uma chamada dexoptPackage, será possível transmitir um sinal de cancelamento, que permite cancelar a operação em algum momento. Isso pode ser útil quando você executa o dexopt de forma assíncrona.

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

Também é possível cancelar a dexopt em segundo plano, que é iniciada pelo serviço ART.

getArtManagerLocal().cancelBackgroundDexoptJob();

Receber resultados do dexopt

Se uma operação for iniciada por uma chamada dexoptPackage, será possível receber o resultado do valor de retorno.

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

// Process the result here.
...

O ART Service também inicia operações dexopt em muitos cenários, como dexopt em segundo plano. Para detectar todos os resultados de dexopt, seja a operação iniciada por uma chamada dexoptPackage ou pelo serviço ART, use ArtManagerLocal#addDexoptDoneCallback.

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

O primeiro argumento determina se apenas as atualizações serão incluídas no resultado. Se você quiser detectar apenas pacotes atualizados pelo dexopt, defina como verdadeiro.

O segundo argumento é o executor do callback. Para executar o callback na mesma linha de execução que executa o dexopt, use Runnable::run. Se você não quiser que o retorno de chamada bloqueie o dexopt, use um executor assíncrono.

É possível adicionar vários callbacks, e o ART Service vai executar todos eles em sequência. Todos os callbacks vão permanecer ativos para todas as chamadas futuras, a menos que você os remova.

Se você quiser remover um callback, mantenha a referência dele ao adicioná-lo e use 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);

Personalizar a lista de pacotes e os parâmetros dexopt

O ART Service inicia as operações de dexopt durante a inicialização e o dexopt em segundo plano. Para personalizar a lista de pacotes ou os parâmetros dexopt para essas operações, use 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.
      }
    });

É possível adicionar ou remover itens da lista de pacotes, classificá-la ou até mesmo usar uma lista completamente diferente.

Seu callback precisa ignorar motivos desconhecidos, porque outros podem ser adicionados no futuro.

É possível definir no máximo um BatchDexoptStartCallback. O callback vai permanecer ativo para todas as chamadas futuras, a menos que você o limpe.

Se você quiser limpar o callback, use ArtManagerLocal#clearBatchDexoptStartCallback.

getArtManagerLocal().clearBatchDexoptStartCallback();

Personalizar os parâmetros do job dexopt em segundo plano

Por padrão, o job dexopt em segundo plano é executado uma vez por dia quando o dispositivo está ocioso e carregando. Isso pode ser alterado usando ArtManagerLocal#setScheduleBackgroundDexoptJobCallback.

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

É possível definir no máximo um ScheduleBackgroundDexoptJobCallback. O callback vai permanecer ativo para todas as chamadas futuras, a menos que você o limpe.

Se você quiser limpar o callback, use ArtManagerLocal#clearScheduleBackgroundDexoptJobCallback.

getArtManagerLocal().clearScheduleBackgroundDexoptJobCallback();

Desativar temporariamente o dexopt

Qualquer operação dexopt iniciada pelo ART Service aciona um BatchDexoptStartCallback. Você pode continuar cancelando as operações para desativar o dexopt.

Se a operação cancelada for dexopt em segundo plano, ela vai seguir a política de nova tentativa padrão (30 segundos, exponencial, limitada a 5 horas).

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

É possível ter no máximo um BatchDexoptStartCallback. Se você também quiser usar BatchDexoptStartCallback para personalizar a lista de pacotes ou os parâmetros dexopt, combine o código em um callback.

// Bad example.

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

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

A operação dexopt realizada na instalação do app não é iniciada pelo serviço ART. Em vez disso, ele é iniciado pelo gerenciador de pacotes por uma chamada dexoptPackage. Portanto, ele não aciona BatchDexoptStartCallback. Para desativar a dexopt na instalação do app, impeça que o gerenciador de pacotes chame dexoptPackage.

Substituir o filtro do compilador para determinados pacotes (Android 15 ou mais recente)

É possível substituir o filtro do compilador para determinados pacotes registrando um callback usando setAdjustCompilerFilterCallback. O callback é chamado sempre que um pacote é dexoptado, não importa se o dexopt é iniciado pelo ART Service durante a inicialização e o dexopt em segundo plano ou por uma chamada de API dexoptPackage.

Se um pacote não precisar de ajuste, o callback precisará retornar originalCompilerFilter.

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

Só é possível definir um AdjustCompilerFilterCallback. Se você quiser usar AdjustCompilerFilterCallback para substituir o filtro do compilador em vários pacotes, combine o código em um único callback. O callback permanece ativo para todas as chamadas futuras, a menos que você o limpe.

Se você quiser limpar o callback, use ArtManagerLocal#clearAdjustCompilerFilterCallback.

getArtManagerLocal().clearAdjustCompilerFilterCallback();

Outras personalizações

O serviço ART também oferece suporte a outras personalizações.

Definir o limite térmico para dexopt em segundo plano

O controle térmico do job de dexopt em segundo plano é realizado pelo Job Scheduler. O job é cancelado imediatamente quando a temperatura atinge THERMAL_STATUS_MODERATE. O limite de THERMAL_STATUS_MODERATE é ajustável.

Determinar se a dexopt em segundo plano está em execução

O job dexopt em segundo plano é gerenciado pelo Job Scheduler, e o código da tarefa dele é 27873780. Para determinar se o job está sendo executado no Android 16 e versões mais recentes, use JobScheduler#getPendingJobReasons. No Android 14 e 15, use 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.
  ...
}

Fornecer um perfil para dexopt

Para usar um perfil para orientar o dexopt, coloque um arquivo .prof ou .dm ao lado do APK.

O arquivo .prof precisa ser um arquivo de perfil em formato binário, e o nome do arquivo precisa ser o nome do arquivo do APK + .prof. Por exemplo,

base.apk.prof

O nome do arquivo .dm precisa ser o nome do APK com a extensão substituída por .dm. Por exemplo,

base.dm

Para verificar se o perfil está sendo usado para dexopt, execute dexopt com speed-profile e confira o resultado.

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

A primeira linha limpa todos os perfis produzidos pelo ambiente de execução (ou seja, aqueles em /data/misc/profiles), se houver, para garantir que o perfil ao lado do APK seja o único que o ART Service pode usar. A segunda linha executa o dexopt com speed-profile e transmite -v para mostrar o resultado detalhado.

Se o perfil estiver sendo usado, você vai ver actualCompilerFilter=speed-profile no resultado. Caso contrário, você verá actualCompilerFilter=verify. Por exemplo,

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}

Os motivos comuns para o ART Service não usar o perfil incluem:

  • O perfil tem um nome de arquivo incorreto ou não está ao lado do APK.
  • O perfil está no formato errado.
  • O perfil não corresponde ao APK. As somas de verificação no perfil não correspondem às dos arquivos .dex no APK.