class RetrySettings (View source)

The RetrySettings class is used to configure retrying and timeouts for RPCs.

This class can be passed as an optional parameter to RPC methods, or as part of an optional array in the constructor of a client object. In addition, many RPCs and API clients accept a PHP array in place of a RetrySettings object. This can be used to change particular retry parameters without needing to construct a complete RetrySettings object.

Constructing a RetrySettings object

See the RetrySettings constructor for documentation about parameters that can be passed to RetrySettings.

Example of creating a RetrySettings object using the constructor:

$retrySettings = new RetrySettings([
    'initialRetryDelayMillis' => 100,
    'retryDelayMultiplier' => 1.3,
    'maxRetryDelayMillis' => 60000,
    'initialRpcTimeoutMillis' => 20000,
    'rpcTimeoutMultiplier' => 1.0,
    'maxRpcTimeoutMillis' => 20000,
    'totalTimeoutMillis' => 600000,
    'retryableCodes' => [ApiStatus::DEADLINE_EXCEEDED, ApiStatus::UNAVAILABLE],
]);

It is also possible to create a new RetrySettings object from an existing object using the {\Google\ApiCore\RetrySettings::with()} method.

Example modifying an existing RetrySettings object using with():

$newRetrySettings = $retrySettings->with([
    'totalTimeoutMillis' => 700000,
]);

Modifying the retry behavior of an RPC method

RetrySettings objects can be used to control retries for many RPC methods in google-cloud-php. The examples below make use of the GroupServiceClient from the Monitoring V3 API, but they can be applied to other APIs in the google-cloud-php repository.

It is possible to specify the retry behavior to be used by an RPC via the retrySettings field in the optionalArgs parameter. The retrySettings field can contain either a RetrySettings object, or a PHP array containing the particular retry parameters to be updated.

Example of disabling retries for a single call to the listGroups method, and setting a custom timeout:

$result = $client->listGroups($name, [
    'retrySettings' => [
        'retriesEnabled' => false,
        'noRetriesRpcTimeoutMillis' => 5000,
    ]
]);

Example of creating a new RetrySettings object and using it to override the retry settings for a call to the listGroups method:

$customRetrySettings = new RetrySettings([
    'initialRetryDelayMillis' => 100,
    'retryDelayMultiplier' => 1.3,
    'maxRetryDelayMillis' => 60000,
    'initialRpcTimeoutMillis' => 20000,
    'rpcTimeoutMultiplier' => 1.0,
    'maxRpcTimeoutMillis' => 20000,
    'totalTimeoutMillis' => 600000,
    'retryableCodes' => [ApiStatus::DEADLINE_EXCEEDED, ApiStatus::UNAVAILABLE],
]);

$result = $client->listGroups($name, [
    'retrySettings' => $customRetrySettings
]);

Modifying the default retry behavior for RPC methods on a Client object

It is also possible to specify the retry behavior for RPC methods when constructing a client object using the 'retrySettingsArray'. The examples below again make use of the GroupServiceClient from the Monitoring V3 API, but they can be applied to other APIs in the google-cloud-php repository.

The GroupServiceClient object accepts an optional retrySettingsArray parameter, which can be used to specify retry behavior for RPC methods on the client. The retrySettingsArray accepts a PHP array in which keys are the names of RPC methods on the client, and values are either a RetrySettings object or a PHP array containing the particular retry parameters to be updated.

Example updating the retry settings for four methods of GroupServiceClient:

use Google\Cloud\Monitoring\V3\GroupServiceClient;

$customRetrySettings = new RetrySettings([
    'initialRetryDelayMillis' => 100,
    'retryDelayMultiplier' => 1.3,
    'maxRetryDelayMillis' => 60000,
    'initialRpcTimeoutMillis' => 20000,
    'rpcTimeoutMultiplier' => 1.0,
    'maxRpcTimeoutMillis' => 20000,
    'totalTimeoutMillis' => 600000,
    'retryableCodes' => [ApiStatus::DEADLINE_EXCEEDED, ApiStatus::UNAVAILABLE],
]);

$updatedCustomRetrySettings = $customRetrySettings->with([
    'totalTimeoutMillis' => 700000
]);

$client = new GroupServiceClient([
    'retrySettingsArray' => [
        'listGroups' => ['retriesEnabled' => false],
        'getGroup' => [
            'initialRpcTimeoutMillis' => 10000,
            'maxRpcTimeoutMillis' => 30000,
            'totalTimeoutMillis' => 60000,
        ],
        'deleteGroup' => $customRetrySettings,
        'updateGroup' => $updatedCustomRetrySettings
    ],
]);

Configure the use of logical timeout

To configure the use of a logical timeout, where a logical timeout is the duration a method is given to complete one or more RPC attempts, with each attempt using only the time remaining in the logical timeout, use {\Google\ApiCore\RetrySettings::logicalTimeout()} combined with {[\Google\ApiCore\RetrySettings::with()}.

$timeoutSettings](../../Google/ApiCore/RetrySettings.html) = RetrySettings::logicalTimeout(30000);

$customRetrySettings = $customRetrySettings->with($timeoutSettings);

$result = $client->listGroups($name, [
    'retrySettings' => $customRetrySettings
]);

{\Google\ApiCore\RetrySettings::logicalTimeout()} can also be used on a method call independent of a RetrySettings instance.

$timeoutSettings = RetrySettings::logicalTimeout(30000);

$result = $client->listGroups($name, [
    'retrySettings' => $timeoutSettings
]);

Traits

Constants

DEFAULT_MAX_RETRIES

Methods

static array
validate(array $arr, array $requiredKeys)

No description

static array
validateNotNull(array $arr, array $requiredKeys)

No description

__construct(array $settings)

Constructs an instance.

static RetrySettings[]
load(string $serviceName, array $clientConfig, bool $disableRetries = false)

Constructs an array mapping method names to CallSettings.

static 
constructDefault()

No description

with(array $settings)

Creates a new instance of RetrySettings that updates the settings in the existing instance with the settings specified in the $settings parameter.

static array
logicalTimeout(int $timeout)

Creates an associative array of the {\Google\ApiCore\RetrySettings} timeout fields configured with the given timeout specified in the $timeout parameter interpreted as a logical timeout.

bool
retriesEnabled()

No description

int
getNoRetriesRpcTimeoutMillis()

No description

int[]
getRetryableCodes()

No description

int
getInitialRetryDelayMillis()

No description

float
getRetryDelayMultiplier()

No description

int
getMaxRetryDelayMillis()

No description

int
getInitialRpcTimeoutMillis()

No description

float
getRpcTimeoutMultiplier()

No description

int
getMaxRpcTimeoutMillis()

No description

int
getTotalTimeoutMillis()

No description

getMaxRetries()

No description

getRetryFunction()

No description

Details

static array validate(array $arr, array $requiredKeys)

No description

Parameters

array $arr

Associative array

array $requiredKeys

List of keys to check for in $arr

Return Value

array

Returns $arr for fluent use

static array validateNotNull(array $arr, array $requiredKeys)

No description

Parameters

array $arr

Associative array

array $requiredKeys

List of keys to check for in $arr

Return Value

array

Returns $arr for fluent use

__construct(array $settings)

Constructs an instance.

Parameters

array $settings

{ Required. Settings for configuring the retry behavior. All parameters are required except $retriesEnabled and $noRetriesRpcTimeoutMillis, which are optional and have defaults determined based on the other settings provided.

@type bool     $retriesEnabled Optional. Enables retries. If not specified, the value is
               determined using the $retryableCodes setting. If $retryableCodes is empty,
               then $retriesEnabled is set to false; otherwise, it is set to true.
@type int      $noRetriesRpcTimeoutMillis Optional. The timeout of the rpc call to be used
               if $retriesEnabled is false, in milliseconds. It not specified, the value
               of $initialRpcTimeoutMillis is used.
@type array    $retryableCodes The Status codes that are retryable. Each status should be
               either one of the string constants defined on {\Google\ApiCore\ApiStatus}
               or an integer constant defined on {\Google\Rpc\Code}.
@type int      $initialRetryDelayMillis The initial delay of retry in milliseconds.
@type int      $retryDelayMultiplier The exponential multiplier of retry delay.
@type int      $maxRetryDelayMillis The max delay of retry in milliseconds.
@type int      $initialRpcTimeoutMillis The initial timeout of rpc call in milliseconds.
@type int      $rpcTimeoutMultiplier The exponential multiplier of rpc timeout.
@type int      $maxRpcTimeoutMillis The max timeout of rpc call in milliseconds.
@type int      $totalTimeoutMillis The max accumulative timeout in total.
@type int      $maxRetries The max retries allowed for an operation.
               Defaults to the value of the DEFAULT_MAX_RETRIES constant.
               This option is experimental.
@type callable $retryFunction This function will be used to decide if we should retry or not.
               Callable signature: `function (Exception $e, array $options): bool`
               This option is experimental.

}

static RetrySettings[] load(string $serviceName, array $clientConfig, bool $disableRetries = false)

Constructs an array mapping method names to CallSettings.

Parameters

string $serviceName

The fully-qualified name of this service, used as a key into the client config file.

array $clientConfig

An array parsed from the standard API client config file.

bool $disableRetries

Disable retries in all loaded RetrySettings objects. Defaults to false.

Return Value

RetrySettings[] $retrySettings

Exceptions

ValidationException

static constructDefault()

No description

RetrySettings with(array $settings)

Creates a new instance of RetrySettings that updates the settings in the existing instance with the settings specified in the $settings parameter.

Parameters

array $settings

{ Settings for configuring the retry behavior. Supports all of the options supported by the constructor; see {\Google\ApiCore\RetrySettings::__construct()}. All parameters are optional - all unset parameters will default to the value in the existing instance. }

Return Value

RetrySettings

static array logicalTimeout(int $timeout)

Creates an associative array of the {\Google\ApiCore\RetrySettings} timeout fields configured with the given timeout specified in the $timeout parameter interpreted as a logical timeout.

Parameters

int $timeout

The timeout in milliseconds to be used as a logical call timeout.

Return Value

array

bool retriesEnabled()

No description

Return Value

bool

Returns true if retries are enabled, otherwise returns false.

int getNoRetriesRpcTimeoutMillis()

No description

Return Value

int

The timeout of the rpc call to be used if $retriesEnabled is false, in milliseconds.

int[] getRetryableCodes()

No description

Return Value

int[]

Status codes to retry

int getInitialRetryDelayMillis()

No description

Return Value

int

The initial retry delay in milliseconds. If $this->retriesEnabled() is false, this setting is unused.

float getRetryDelayMultiplier()

No description

Return Value

float

The retry delay multiplier. If $this->retriesEnabled() is false, this setting is unused.

int getMaxRetryDelayMillis()

No description

Return Value

int

The maximum retry delay in milliseconds. If $this->retriesEnabled() is false, this setting is unused.

int getInitialRpcTimeoutMillis()

No description

Return Value

int

The initial rpc timeout in milliseconds. If $this->retriesEnabled() is false, this setting is unused - use noRetriesRpcTimeoutMillis to set the timeout in that case.

float getRpcTimeoutMultiplier()

No description

Return Value

float

The rpc timeout multiplier. If $this->retriesEnabled() is false, this setting is unused.

int getMaxRpcTimeoutMillis()

No description

Return Value

int

The maximum rpc timeout in milliseconds. If $this->retriesEnabled() is false, this setting is unused - use noRetriesRpcTimeoutMillis to set the timeout in that case.

int getTotalTimeoutMillis()

No description

Return Value

int

The total time in milliseconds to spend on the call, including all retry attempts and delays between attempts. If $this->retriesEnabled() is false, this setting is unused - use noRetriesRpcTimeoutMillis to set the timeout in that case.

getMaxRetries()

No description

getRetryFunction()

No description