Antes de começar, confira uma visão geral de alto nível do Serviço de ART.
A partir do Android 14, a compilação AOT no dispositivo para apps (também conhecida como dexopt) é processada pelo serviço do ART. O serviço do ART faz parte do módulo do ART e pode ser personalizado por propriedades do sistema e APIs.
Propriedades do sistema
O serviço ART oferece suporte a todas as opções do dex2oat relevantes.
Além disso, o serviço do ART oferece suporte às seguintes propriedades do sistema:
pm.dexopt.<reason>
É um conjunto de propriedades do sistema que determina os filtros padrão do compilador para todos os motivos de compilação predefinidos descritos nos cenários do Dexopt.
Para mais informações, consulte Filtros do compilador.
Os valores padrão 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: velocidade)
Esse é o filtro de compilador alternativo para apps usados por outros apps.
Em princípio, o serviço do ART 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, alguns
apps são usados por outros (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 do ART vai tentar usar um perfil de nuvem primeiro. Se um perfil de nuvem não existir, o serviço ART
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 de 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 tarefas):
dalvik.vm.*dex2oat-threadscontrola o número de linhas de execução para cada invocação do dex2oat, enquantopm.dexopt.<reason>.concurrencycontrola o número de invocações do dex2oat. Ou seja, o número máximo de linhas de execução simultâneas é 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 de dex2oat pode não utilizar totalmente todos os núcleos da CPU, independentemente
de dalvik.vm.*dex2oat-threads. Portanto, aumentar o número de invocações de
dex2oat (pm.dexopt.<reason>.concurrency) pode utilizar melhor os núcleos da CPU para
acelerar o progresso geral do dexopt. Isso é especialmente útil durante
a inicialização.
No entanto, ter muitas invocações de dex2oat pode fazer com que o dispositivo fique sem
memória, mesmo que 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 cuidadosamente
de acordo com cada produto.
pm.dexopt.downgrade_after_inactive_days (padrão: não definido)
Se essa opção estiver definida, o serviço ART só vai desabilitar apps usados nos últimos dias.
Além disso, se o armazenamento estiver quase vazio, durante a dexopt em segundo plano, o serviço do ART
vai fazer o 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 baixo espaço do gerenciador de armazenamento (configurável por meio das 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 com
ArtManagerLocal#setBatchDexoptStartCallback, os pacotes na lista fornecida
por BatchDexoptStartCallback para bg-dexopt nunca serão rebaixados.
pm.dexopt.disable_bg_dexopt (padrão: false)
Isso é apenas para testes. Isso impede que o serviço ART programe o job dedexopt em segundo plano.
Se o job de 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 a execução do job dexopt em segundo plano é:
setprop pm.dexopt.disable_bg_dexopt true
pm bg-dexopt-job --disable
A primeira linha impede que o job de dexopt em segundo plano seja programado, se ainda não tiver sido programado. A segunda linha desprograma o job dexopt em segundo plano, se ele já estiver programado, e cancela o job dexopt em segundo plano imediatamente, se ele estiver em execução.
APIs do serviço do ART
O serviço ART 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 a
obtê-lo.
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 ter acesso a ele, 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;
Confira a seguir alguns casos de uso típicos das APIs.
Acionar o dexopt para um app
É possível acionar o 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());
}
Você também pode 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();
Você também pode cancelar o dexopt em segundo plano, que é iniciado pelo serviço ART.
getArtManagerLocal().cancelBackgroundDexoptJob();
Conferir os resultados de dexopt
Se uma operação for iniciada por uma chamada dexoptPackage, você poderá receber o resultado
do valor de retorno.
DexoptResult result;
try (var snapshot = getPackageManagerLocal().withFilteredSnapshot()) {
result = getArtManagerLocal().dexoptPackage(...);
}
// Process the result here.
...
O serviço do ART também inicia operações dexopt em muitos cenários, como
dexopt em segundo plano. Para detectar todos os resultados do 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 "true".
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
callback bloqueie o dexopt, use um executor assíncrono.
É possível adicionar vários callbacks, e o serviço do ART vai executá-los sequencialmente. Todos os callbacks permanecerão ativos para todas as chamadas futuras, a menos que você os remova.
Se você quiser remover um callback, mantenha a referência dele ao
adicionar 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 serviço do ART inicia as operações dexopt durante a inicialização e a
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, remover, classificar e até mesmo usar uma lista completamente diferente.
Seu callback precisa ignorar os motivos desconhecidos, porque mais motivos 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 de 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 uma 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 de dexopt iniciada pelo serviço ART 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 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);
Você pode 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 de dexopt realizada na instalação do app não é iniciada pelo
ART Service. Em vez disso, ele é iniciado pelo gerenciador de pacotes por uma
chamada dexoptPackage. Portanto, ele não aciona
BatchDexoptStartCallback. Para desativar o dexopt na instalação do app, evite que o
gerenciador de pacotes chame dexoptPackage.
Substituir o filtro do compilador para determinados pacotes (Android 15+ e versões mais recentes)
É possível substituir o filtro do compilador para determinados pacotes registrando um
callback com setAdjustCompilerFilterCallback. O callback é chamado
sempre que um pacote é dexopt, não importa se ele é 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 ajustes, o callback precisará retornar
originalCompilerFilter.
getArtManagerLocal().setAdjustCompilerFilterCallback(
Runnable::run,
(packageName, originalCompilerFilter, reason) -> {
if (isVeryImportantPackage(packageName)) {
return "speed-profile";
}
return originalCompilerFilter;
});
Só é possível definir uma AdjustCompilerFilterCallback. Se você quiser usar
AdjustCompilerFilterCallback para substituir o filtro do compilador para vários
pacotes, combine o código em um 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 do ART também oferece suporte a outras personalizações.
Definir o limite térmico para dexopt em segundo plano
O Job Scheduler executa o controle térmico do job dexopt em segundo plano.
O job é cancelado imediatamente quando a temperatura atinge
THERMAL_STATUS_MODERATE. O limite de
THERMAL_STATUS_MODERATE é configurável.
Determinar se o dexopt em segundo plano está em execução
O job dexopt em segundo plano é gerenciado pelo JobScheduler, e o ID dele é
27873780. Para determinar se o job está em execução, use as APIs Job Scheduler.
// Good example.
var jobScheduler =
Objects.requireNonNull(mContext.getSystemService(JobScheduler.class));
int reason = jobScheduler.getPendingJobReason(27873780);
if (reason == 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 de formato binário, e o nome do arquivo precisa ser
o nome do APK + .prof. Por exemplo:
base.apk.prof
O nome do arquivo .dm precisa ser o mesmo 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 verifique 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 tempo de execução (ou seja, aqueles em
/data/misc/profiles), se houver, para garantir que o perfil ao lado do APK seja
o único perfil que o serviço do ART possa usar. A segunda linha executa dexopt
com speed-profile e transmite -v para mostrar o resultado detalhado.
Se o perfil estiver sendo usado, você 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 típicos para o serviço do ART 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 somas de verificação dos arquivos
.dexno APK.