/*!

@page dataproc-override-retry Override Retry, Backoff, and Idempotency Policies

When it is safe to do so, the library automatically retries requests that fail
due to a transient error. The library then uses [exponential backoff] to backoff
before trying again. Which operations are considered safe to retry, which
errors are treated as transient failures, the details of the exponential backoff
algorithm, and for how long the library retries are all configurable via
policies.

This document provides examples showing how to override the default policies.

The policies can be set when the `*Connection` object is created. The library
provides default policies for any policy that is not set. The application can
also override some (or all) policies when the `*Client` object is created. This
can be useful if multiple `*Client` objects share the same `*Connection` object,
but you want different retry behavior in some of the clients. Finally, the
application can override some retry policies when calling a specific member
function.

The library uses three different options to control the retry loop. The options
have per-client names.

@section dataproc-override-retry-retry-policy Configuring the transient errors and retry duration

The `*RetryPolicyOption` controls:

- Which errors are to be treated as transient errors.
- How long the library will keep retrying transient errors.

You can provide your own class for this option. The library also provides two
built-in policies:

- `*LimitedErrorCountRetryPolicy`: stops retrying after a specified number
  of transient errors.
- `*LimitedTimeRetryPolicy`: stops retrying after a specified time.

Note that a library may have more than one version of these classes. Their name
match the `*Client` and `*Connection` object they are intended to be used
with. Some `*Client` objects treat different error codes as transient errors.
In most cases, only [kUnavailable](@ref google::cloud::StatusCode) is treated
as a transient error.

@section dataproc-override-retry-backoff-policy Controlling the backoff algorithm

The `*BackoffPolicyOption` controls how long the client library will wait
before retrying a request that failed with a transient error. You can provide
your own class for this option.

The only built-in backoff policy is
[`ExponentialBackoffPolicy`](@ref google::cloud::ExponentialBackoffPolicy).
This class implements a truncated exponential backoff algorithm, with jitter.
In summary, it doubles the current backoff time after each failure. The actual
backoff time for an RPC is chosen at random, but never exceeds the current
backoff. The current backoff is doubled after each failure, but never exceeds
(or is "truncated") if it reaches a prescribed maximum.

@section dataproc-override-retry-idempotency-policy Controlling which operations are retryable

The `*IdempotencyPolicyOption` controls which requests are retryable, as some
requests are never safe to retry.

Only one built-in idempotency policy is provided by the library. The name
matches the name of the client it is intended for. For example, `FooBarClient`
will use `FooBarIdempotencyPolicy`. This policy is very conservative.

@section dataproc-override-retry-example Example

<!-- inject-retry-snippet-start -->
For example, this will override the retry policies for `dataproc_v1::AutoscalingPolicyServiceClient`:

@snippet autoscaling_policy_client_samples.cc set-retry-policy

This assumes you have created a custom idempotency policy. Such as:

@snippet autoscaling_policy_client_samples.cc custom-idempotency-policy


Follow these links to find examples for other \c *Client classes:

- [\c dataproc_v1::AutoscalingPolicyServiceClient](@ref dataproc_v1::AutoscalingPolicyServiceClient-retry-snippet)
- [\c dataproc_v1::BatchControllerClient](@ref dataproc_v1::BatchControllerClient-retry-snippet)
- [\c dataproc_v1::ClusterControllerClient](@ref dataproc_v1::ClusterControllerClient-retry-snippet)
- [\c dataproc_v1::JobControllerClient](@ref dataproc_v1::JobControllerClient-retry-snippet)
- [\c dataproc_v1::NodeGroupControllerClient](@ref dataproc_v1::NodeGroupControllerClient-retry-snippet)
- [\c dataproc_v1::WorkflowTemplateServiceClient](@ref dataproc_v1::WorkflowTemplateServiceClient-retry-snippet)

<!-- inject-retry-snippet-end -->

@section dataproc-override-retry-more-information More Information

@see google::cloud::Options
@see google::cloud::BackoffPolicy
@see google::cloud::ExponentialBackoffPolicy

[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff

*/

// <!-- inject-retry-pages-start -->

/*! @page dataproc_v1::AutoscalingPolicyServiceClient-retry-snippet Override dataproc_v1::AutoscalingPolicyServiceClient Retry Policies

This shows how to override the retry policies for dataproc_v1::AutoscalingPolicyServiceClient:

@snippet google/cloud/dataproc/v1/samples/autoscaling_policy_client_samples.cc set-retry-policy

Assuming you have created a custom idempotency policy. Such as:

@snippet google/cloud/dataproc/v1/samples/autoscaling_policy_client_samples.cc custom-idempotency-policy

*/

/*! @page dataproc_v1::BatchControllerClient-retry-snippet Override dataproc_v1::BatchControllerClient Retry Policies

This shows how to override the retry policies for dataproc_v1::BatchControllerClient:

@snippet google/cloud/dataproc/v1/samples/batch_controller_client_samples.cc set-retry-policy

Assuming you have created a custom idempotency policy. Such as:

@snippet google/cloud/dataproc/v1/samples/batch_controller_client_samples.cc custom-idempotency-policy

*/

/*! @page dataproc_v1::ClusterControllerClient-retry-snippet Override dataproc_v1::ClusterControllerClient Retry Policies

This shows how to override the retry policies for dataproc_v1::ClusterControllerClient:

@snippet google/cloud/dataproc/v1/samples/cluster_controller_client_samples.cc set-retry-policy

Assuming you have created a custom idempotency policy. Such as:

@snippet google/cloud/dataproc/v1/samples/cluster_controller_client_samples.cc custom-idempotency-policy

*/

/*! @page dataproc_v1::JobControllerClient-retry-snippet Override dataproc_v1::JobControllerClient Retry Policies

This shows how to override the retry policies for dataproc_v1::JobControllerClient:

@snippet google/cloud/dataproc/v1/samples/job_controller_client_samples.cc set-retry-policy

Assuming you have created a custom idempotency policy. Such as:

@snippet google/cloud/dataproc/v1/samples/job_controller_client_samples.cc custom-idempotency-policy

*/

/*! @page dataproc_v1::NodeGroupControllerClient-retry-snippet Override dataproc_v1::NodeGroupControllerClient Retry Policies

This shows how to override the retry policies for dataproc_v1::NodeGroupControllerClient:

@snippet google/cloud/dataproc/v1/samples/node_group_controller_client_samples.cc set-retry-policy

Assuming you have created a custom idempotency policy. Such as:

@snippet google/cloud/dataproc/v1/samples/node_group_controller_client_samples.cc custom-idempotency-policy

*/

/*! @page dataproc_v1::WorkflowTemplateServiceClient-retry-snippet Override dataproc_v1::WorkflowTemplateServiceClient Retry Policies

This shows how to override the retry policies for dataproc_v1::WorkflowTemplateServiceClient:

@snippet google/cloud/dataproc/v1/samples/workflow_template_client_samples.cc set-retry-policy

Assuming you have created a custom idempotency policy. Such as:

@snippet google/cloud/dataproc/v1/samples/workflow_template_client_samples.cc custom-idempotency-policy

*/
// <!-- inject-retry-pages-end -->
