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 {@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
    ],
]);
CloneableInstantiable
Methods
public __construct(array $settings)
 

Constructs an instance.

    public static constructDefault()
    public getInitialRetryDelayMillis()
     
    • return int The initial retry delay in milliseconds. If $this->retriesEnabled() is false, this setting is unused.
    public getInitialRpcTimeoutMillis()
     
    • return 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.
    public getMaxRetryDelayMillis()
     
    • return int The maximum retry delay in milliseconds. If $this->retriesEnabled() is false, this setting is unused.
    public getMaxRpcTimeoutMillis()
     
    • return 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.
    public getNoRetriesRpcTimeoutMillis()
     
    • return int The timeout of the rpc call to be used if $retriesEnabled is false, in milliseconds.
    public getRetryableCodes()
     
    • return int[] Status codes to retry
    public getRetryDelayMultiplier()
     
    • return float The retry delay multiplier. If $this->retriesEnabled() is false, this setting is unused.
    public getRpcTimeoutMultiplier()
     
    • return float The rpc timeout multiplier. If $this->retriesEnabled() is false, this setting is unused.
    public getTotalTimeoutMillis()
     
    • return 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.
    public static load( $serviceName, $clientConfig, $disableRetries = false)
     

    Constructs an array mapping method names to CallSettings.

    public retriesEnabled()
     
    • return bool Returns true if retries are enabled, otherwise returns false.
    public static validate( $arr, $requiredKeys)
     
    • return array Returns $arr for fluent use
    public static validateNotNull( $arr, $requiredKeys)
     
    • return array Returns $arr for fluent use
    public 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.

    Properties
    private $initialRetryDelayMillis
    private $initialRpcTimeoutMillis
    private $maxRetryDelayMillis
    private $maxRpcTimeoutMillis
    private $noRetriesRpcTimeoutMillis
    private $retriesEnabled
    private $retryableCodes
    private $retryDelayMultiplier
    private $rpcTimeoutMultiplier
    private $totalTimeoutMillis
    Methods
    private static convertArrayFromSnakeCase( $settings)
    private static validateFileExists( $filePath)
    private static validateImpl( $arr, $requiredKeys, $allowNull)
    Methods
    public static constructDefault()
    private static convertArrayFromSnakeCase( $settings)
    public static load( $serviceName, $clientConfig, $disableRetries = false)
     

    Constructs an array mapping method names to CallSettings.

    public static validate( $arr, $requiredKeys)
     
    • return array Returns $arr for fluent use
    private static validateFileExists( $filePath)
    private static validateImpl( $arr, $requiredKeys, $allowNull)
    public static validateNotNull( $arr, $requiredKeys)
     
    • return array Returns $arr for fluent use
    © 2020 Bruce Wells
    Search Namespaces \ Classes
    ConfigurationNumbers (0-9.) only