/*!

@page pubsub-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 pubsub-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 will 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.

@see google::cloud::pubsub::RetryPolicyOption
@see google::cloud::pubsub::RetryPolicy
@see google::cloud::pubsub::LimitedTimeRetryPolicy
@see google::cloud::pubsub::LimitedErrorCountRetryPolicy
@see google::cloud::pubsub::SchemaServiceRetryPolicyOption
@see google::cloud::pubsub::SchemaServiceRetryPolicy
@see google::cloud::pubsub::SchemaServiceLimitedTimeRetryPolicy
@see google::cloud::pubsub::SchemaServiceLimitedErrorCountRetryPolicy

@section pubsub-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.

@see google::cloud::pubsub::BackoffPolicyOption
@see google::cloud::pubsub::SchemaServiceBackoffPolicyOption

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

[`SchemaServiceClient`] supports the
[`SchemaServiceConnectionIdempotencyPolicyOption`] to control which requests are
[idempotent], and therefore retryable.  In all other cases the Pub/Sub library
retries the operations.

For `SchemaServiceClient` only one built-in idempotency policy is provided by
the library: [`SchemaServiceConnectionIdempotencyPolicy`].

[`SchemaServiceClient`]: @ref google::cloud::pubsub::SchemaServiceClient
[`SchemaServiceConnectionIdempotencyPolicyOption`]: @ref google::cloud::pubsub::SchemaServiceConnectionIdempotencyPolicyOption
[`SchemaServiceConnectionIdempotencyPolicy`]: @ref google::cloud::pubsub::SchemaServiceConnectionIdempotencyPolicy

@section pubsub-override-retry-example Example

For example, this will override the retry policies for `pubsub::Publisher`:

@snippet samples.cc publisher-retry-settings

While this will override the retry policies for `pubusb::Subscriber`:

@snippet samples.cc subscriber-retry-settings

Follow these links to find examples for other classes:

- [\c SchemaServiceClient](@ref pubsub::SchemaServiceClient-retry-snippet)

@section pubsub-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
[idempotent]: https://en.wikipedia.org/wiki/Idempotence

*/

/*! @page pubsub::SchemaServiceClient-retry-snippet Override pubsub::SchemaServiceClient Retry Policies

This shows how to override the retry policies for pubsub::SchemaServiceClient:

@snippet google/cloud/pubsub/samples/schema_client_samples.cc set-retry-policy

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

@snippet google/cloud/pubsub/samples/schema_client_samples.cc custom-idempotency-policy

*/
