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 {@see \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 {@see \Google\ApiCore\RetrySettings::logicalTimeout()} combined with {@see \Google\ApiCore\RetrySettings::with()}.

$timeoutSettings = RetrySettings::logicalTimeout(30000);

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

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

{@see \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
]);