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-threadscontrola o número de linhas de execução para cada invocação dex2oat, enquantopm.dexopt.<reason>.concurrencycontrola 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-sete 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
.dexno APK.