/*!
@page publicca-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 publicca-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 publicca-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 publicca-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 publicca-override-retry-example Example

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

@snippet public_certificate_authority_client_samples.cc set-retry-policy

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

@snippet public_certificate_authority_client_samples.cc custom-idempotency-policy


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

@section publicca-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 publicca_v1::PublicCertificateAuthorityServiceClient-retry-snippet Override publicca_v1::PublicCertificateAuthorityServiceClient Retry Policies

This shows how to override the retry policies for publicca_v1::PublicCertificateAuthorityServiceClient:

@snippet google/cloud/publicca/v1/samples/public_certificate_authority_client_samples.cc set-retry-policy

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

@snippet google/cloud/publicca/v1/samples/public_certificate_authority_client_samples.cc custom-idempotency-policy

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