ProfileInstaller

class ProfileInstaller


Install ahead of time tracing profiles to configure ART to precompile bundled libraries. This will automatically be called by ProfileInstallerInitializer and you should never call this unless you have disabled the initializer in your manifest. This reads profiles from the assets directory, where they must be embedded during the build process. This will have no effect if there is not a profile embedded in the current APK.

Summary

Nested types

An object which can be passed to the ProfileInstaller which will receive information during the installation process which can be used for logging and telemetry.

Constants

const Int

Indicates that when tryInstallSync was run, no existing profile was found in the "cur" directory.

const Int

Indicates that when tryInstallSync was run, an existing profile was found in the "cur" directory.

const Int

Indicates that the profile is compressed and a version of bundletool newer than 1.13.2 needs to be used to build the app.

const Int

Indicates that when tryInstallSync was run, no existing profile was found in the "cur" directory.

const Int

Indicates that when tryInstallSync was run, an existing profile was found in the "cur" directory.

const Int

Indicates that no installation occurred because it was determined that the baseline profile had already been installed previously.

const Int

Indicates that no baseline profile was bundled with the APK, and as a result, no installation could take place.

const Int

Indicates that the benchmark operation failed

const Int

Indicates that the benchmark operation was successful

const Int

Indicates that the benchmark operation was unknown, likely meaning profileinstaller needs to update to support the operation

const Int

Indicates that a skip file was successfully deleted and profile installation will resume.

const Int

Indicates that the format required by this SDK version is not supported by this version of the ProfileInstaller library.

const Int

Indicates that a skip file was successfully written and profile installation will be skipped.

const Int

Indicates that the profile got installed and written to disk successfully.

const Int

Indicates that an IO Exception took place during install.

const Int

Indicates that the device requires a metadata file in order to install the profile successfully, but there was not one included in the APK.

const Int

Indicates that the installation was aborted because the app was found to not have adequate permissions to write the profile to disk.

const Int

Indicates that a parsing exception occurred during install.

const Int

Indicates that this process was signalled to save it's profile information

const Int

Indicates that this process was not able to signal itself to save profile information

const Int

Indicates that the current SDK level is such that installing a profile is not supported by ART.

Public functions

java-static Unit

Try to write the profile from assets into the ART aot profile directory.

java-static Unit
@WorkerThread
writeProfile(
    context: Context,
    executor: Executor,
    diagnostics: ProfileInstaller.DiagnosticsCallback
)

Try to write the profile from assets into the ART aot profile directory.

Constants

DIAGNOSTIC_CURRENT_PROFILE_DOES_NOT_EXIST

Added in 1.0.0
const val DIAGNOSTIC_CURRENT_PROFILE_DOES_NOT_EXIST = 2: Int

Indicates that when tryInstallSync was run, no existing profile was found in the "cur" directory.

DIAGNOSTIC_CURRENT_PROFILE_EXISTS

Added in 1.0.0
const val DIAGNOSTIC_CURRENT_PROFILE_EXISTS = 1: Int

Indicates that when tryInstallSync was run, an existing profile was found in the "cur" directory. The associated [data] passed in for this call will be the size, in bytes, of the profile that was found.

DIAGNOSTIC_PROFILE_IS_COMPRESSED

Added in 1.3.0
const val DIAGNOSTIC_PROFILE_IS_COMPRESSED = 5: Int

Indicates that the profile is compressed and a version of bundletool newer than 1.13.2 needs to be used to build the app.

DIAGNOSTIC_REF_PROFILE_DOES_NOT_EXIST

Added in 1.0.0
const val DIAGNOSTIC_REF_PROFILE_DOES_NOT_EXIST = 4: Int

Indicates that when tryInstallSync was run, no existing profile was found in the "cur" directory.

DIAGNOSTIC_REF_PROFILE_EXISTS

Added in 1.0.0
const val DIAGNOSTIC_REF_PROFILE_EXISTS = 3: Int

Indicates that when tryInstallSync was run, an existing profile was found in the "cur" directory. The associated [data] passed in for this call will be the size, in bytes, of the profile that was found.

RESULT_ALREADY_INSTALLED

Added in 1.0.0
const val RESULT_ALREADY_INSTALLED = 2: Int

Indicates that no installation occurred because it was determined that the baseline profile had already been installed previously.

RESULT_BASELINE_PROFILE_NOT_FOUND

Added in 1.0.0
const val RESULT_BASELINE_PROFILE_NOT_FOUND = 6: Int

Indicates that no baseline profile was bundled with the APK, and as a result, no installation could take place.

RESULT_BENCHMARK_OPERATION_FAILURE

Added in 1.3.0
const val RESULT_BENCHMARK_OPERATION_FAILURE = 15: Int

Indicates that the benchmark operation failed

RESULT_BENCHMARK_OPERATION_SUCCESS

Added in 1.3.0
const val RESULT_BENCHMARK_OPERATION_SUCCESS = 14: Int

Indicates that the benchmark operation was successful

RESULT_BENCHMARK_OPERATION_UNKNOWN

Added in 1.3.0
const val RESULT_BENCHMARK_OPERATION_UNKNOWN = 16: Int

Indicates that the benchmark operation was unknown, likely meaning profileinstaller needs to update to support the operation

RESULT_DELETE_SKIP_FILE_SUCCESS

Added in 1.2.0
const val RESULT_DELETE_SKIP_FILE_SUCCESS = 11: Int

Indicates that a skip file was successfully deleted and profile installation will resume.

RESULT_DESIRED_FORMAT_UNSUPPORTED

Added in 1.0.0
const val RESULT_DESIRED_FORMAT_UNSUPPORTED = 5: Int

Indicates that the format required by this SDK version is not supported by this version of the ProfileInstaller library.

RESULT_INSTALL_SKIP_FILE_SUCCESS

Added in 1.2.0
const val RESULT_INSTALL_SKIP_FILE_SUCCESS = 10: Int

Indicates that a skip file was successfully written and profile installation will be skipped.

RESULT_INSTALL_SUCCESS

Added in 1.0.0
const val RESULT_INSTALL_SUCCESS = 1: Int

Indicates that the profile got installed and written to disk successfully. Note that this should happen but is not the only condition that indicates "nothing went wrong". Several result codes are indicative of expected behavior.

RESULT_IO_EXCEPTION

Added in 1.0.0
const val RESULT_IO_EXCEPTION = 7: Int

Indicates that an IO Exception took place during install. The associated [data] with this result is the exception.

RESULT_META_FILE_REQUIRED_BUT_NOT_FOUND

Added in 1.1.0
const val RESULT_META_FILE_REQUIRED_BUT_NOT_FOUND = 9: Int

Indicates that the device requires a metadata file in order to install the profile successfully, but there was not one included in the APK. The correct metadata files are produced when using Android Gradle Plugin `7.1.0-alpha05` or newer.

RESULT_NOT_WRITABLE

Added in 1.0.0
const val RESULT_NOT_WRITABLE = 4: Int

Indicates that the installation was aborted because the app was found to not have adequate permissions to write the profile to disk.

RESULT_PARSE_EXCEPTION

Added in 1.0.0
const val RESULT_PARSE_EXCEPTION = 8: Int

Indicates that a parsing exception occurred during install. The associated [data] with this result is the exception.

RESULT_SAVE_PROFILE_SIGNALLED

Added in 1.3.0
const val RESULT_SAVE_PROFILE_SIGNALLED = 12: Int

Indicates that this process was signalled to save it's profile information

RESULT_SAVE_PROFILE_SKIPPED

Added in 1.3.0
const val RESULT_SAVE_PROFILE_SKIPPED = 13: Int

Indicates that this process was not able to signal itself to save profile information

RESULT_UNSUPPORTED_ART_VERSION

Added in 1.0.0
const val RESULT_UNSUPPORTED_ART_VERSION = 3: Int

Indicates that the current SDK level is such that installing a profile is not supported by ART.

Public functions

writeProfile

Added in 1.0.0
@WorkerThread
java-static fun writeProfile(context: Context): Unit

Try to write the profile from assets into the ART aot profile directory. You do not need to call this method if ProfileInstallerInitializer is enabled for your application. If you disable the initializer, you should call this method within 5-10 seconds of app launch, to ensure that art can use the generated profile. This should always be called after the first screen is shown to the user, to avoid delaying application startup to install AOT profiles. It is encouraged that you call this method during every app startup to ensure profiles are written correctly after app upgrades, or if the profile failed to write on the previous launch. Profiles will be correctly formatted based on the current API level of the device, and only installed if profileinstaller can determine that it is safe to do so. If the profile is not written, no action needs to be taken.

Parameters
context: Context

context to read assets from

writeProfile

Added in 1.0.0
@WorkerThread
java-static fun writeProfile(
    context: Context,
    executor: Executor,
    diagnostics: ProfileInstaller.DiagnosticsCallback
): Unit

Try to write the profile from assets into the ART aot profile directory. You do not need to call this method if ProfileInstallerInitializer is enabled for your application. If you disable the initializer, you should call this method within 5-10 seconds of app launch, to ensure that art can use the generated profile. This should always be called after the first screen is shown to the user, to avoid delaying application startup to install AOT profiles. It is encouraged that you call this method during every app startup to ensure profiles are written correctly after app upgrades, or if the profile failed to write on the previous launch. Profiles will be correctly formatted based on the current API level of the device, and only installed if profileinstaller can determine that it is safe to do so. If the profile is not written, no action needs to be taken.

Parameters
context: Context

context to read assets from

executor: Executor

the executor to run the diagnostic events through

diagnostics: ProfileInstaller.DiagnosticsCallback

an object which will receive diagnostic information about the installation