RetryPolicy

@ExperimentalRetryPolicy
interface RetryPolicy

Defines a strategy for retrying upon initialization failures of the CameraProvider. When the initialization task is interrupted by an error or exception during execution, the task will determine whether to be rescheduled based on the specified RetryPolicy.

Several predefined retry policies are available:

  • NEVER: Never retries the initialization.
  • DEFAULT: The default retry policy, which retries initialization up to a maximum timeout of getDefaultRetryTimeoutInMillis, providing a general-purpose approach for handling most errors.
  • RETRY_UNAVAILABLE_CAMERA: The retry policy automatically retries upon encountering errors like the DEFAULT policy, and specifically designed to handle potential device inconsistencies in reporting available camera instances. In cases where the initial camera configuration fails due to the device underreporting (i.e., not accurately disclosing all available camera instances) the policy proactively triggers a reinitialization attempt. If the cameras are not successfully configured within getDefaultRetryTimeoutInMillis, the initialization is considered a failure.

If no RetryPolicy is specified, DEFAULT will be used as the default.

Examples of configuring the RetryPolicy: 

// Configuring {RetryPolicy#RETRY_UNAVAILABLE_CAMERA} to the CameraXConfig
ProcessCameraProvider.configureInstance(
   CameraXConfig.Builder.fromConfig(Camera2Config.defaultConfig())
     .setCameraProviderInitRetryPolicy(RetryPolicy.RETRY_UNAVAILABLE_CAMERA)
     .build()
);
...

Configuring a customized RetryPolicy: 

ProcessCameraProvider.configureInstance(CameraXConfig.Builder.fromConfig(
        Camera2Config.defaultConfig()).setCameraProviderInitRetryPolicy(
        executionState -> {
            if (executionState.getExecutedTimeInMillis() > 10000L
                    || executionState.getNumOfAttempts() > 10
                    || executionState.getStatus() == ExecutionState.STATUS_CONFIGURATION_FAIL) {
                return RetryConfig.NOT_RETRY;
            } else if (executionState.getStatus() == ExecutionState.STATUS_CAMERA_UNAVAILABLE) {
                return RetryConfig.DEFAULT_DELAY_RETRY;
            } else {
                Log.d("CameraX", "Unknown error occur: " + executionState.getCause());
                return RetryConfig.MINI_DELAY_RETRY;
            }
        }).build());
...
 In the second example, the custom retry policy retries the initialization up to 10 times or for a maximum of 10 seconds. If an unknown error occurs, the retry policy delays the next retry after a delay defined by MINI_DELAY_RETRY. The retry process stops if the status is STATUS_CONFIGURATION_FAIL. For STATUS_CAMERA_UNAVAILABLE, the retry policy applies DEFAULT_DELAY_RETRY.

Summary

Nested types

A builder class for customizing RetryPolicy behavior.

Provides insights into the current execution state of the camera initialization process.

Represents the outcome of a RetryPolicy decision.

A builder class for creating and customizing RetryConfig objects.

Constants
const RetryPolicy

This retry policy increases initialization success by automatically retrying upon encountering errors.
const RetryPolicy

A retry policy that prevents any retry attempts and immediately halts the initialization upon encountering an error.
const RetryPolicy

This retry policy automatically retries upon encountering errors and specifically designed to handle potential device inconsistencies in reporting available camera instances.

Public functions
java-static Long

Retrieves the default timeout value, in milliseconds, used for initialization retries.
Long

Returns the maximum allowed retry duration in milliseconds.
RetryPolicy.RetryConfig

Called to request a decision on whether to retry the initialization process.

Constants

DEFAULT

Added in 1.4.0
const val DEFAULT: RetryPolicy

This retry policy increases initialization success by automatically retrying upon encountering errors.

By default, it continues retrying for a maximum of getDefaultRetryTimeoutInMillis milliseconds. To adjust the timeout duration to specific requirements, utilize RetryPolicy.Builder.

Example: Create a policy based on DEFAULT with a 10-second timeout: 

RetryPolicy customTimeoutPolicy =
    new RetryPolicy.Builder(RetryPolicy.DEFAULT).setTimeoutInMillis(10000L).build();

NEVER

Added in 1.4.0
const val NEVER: RetryPolicy

A retry policy that prevents any retry attempts and immediately halts the initialization upon encountering an error.

RETRY_UNAVAILABLE_CAMERA

Added in 1.4.0
const val RETRY_UNAVAILABLE_CAMERA: RetryPolicy

This retry policy automatically retries upon encountering errors and specifically designed to handle potential device inconsistencies in reporting available camera instances. If the initial camera configuration fails due to underreporting, the policy automatically attempts reinitialization.

By default, it perseveres for a maximum of getDefaultRetryTimeoutInMillis milliseconds before conceding initialization as unsuccessful. For finer control over the timeout duration, utilize RetryPolicy.Builder.

Example: Create a policy based on RETRY_UNAVAILABLE_CAMERA with a 10-second timeout: 

RetryPolicy customTimeoutPolicy = new RetryPolicy.Builder(
    RetryPolicy.RETRY_UNAVAILABLE_CAMERA).setTimeoutInMillis(10000L).build();

Public functions

getDefaultRetryTimeoutInMillis

Added in 1.4.0
java-static fun getDefaultRetryTimeoutInMillis(): Long

Retrieves the default timeout value, in milliseconds, used for initialization retries.

Returns
Long

The default timeout duration, expressed in milliseconds. This value determines the maximum time to wait for a successful initialization before considering the process as failed.

getTimeoutInMillis

Added in 1.4.0
fun getTimeoutInMillis(): Long

Returns the maximum allowed retry duration in milliseconds. Initialization will be terminated if retries take longer than this timeout. A value of 0 indicates no timeout is enforced.

The default value is 0 (no timeout).

Returns
Long

The retry timeout in milliseconds.

onRetryDecisionRequested

Added in 1.4.0
fun onRetryDecisionRequested(executionState: RetryPolicy.ExecutionState): RetryPolicy.RetryConfig

Called to request a decision on whether to retry the initialization process.

Parameters
executionState: RetryPolicy.ExecutionState

Information about the current execution state of the camera initialization.
Returns
RetryPolicy.RetryConfig

A RetryConfig indicating whether to retry, along with any associated delay.