RetrySettings

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
]);