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

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

@snippet agents_client_samples.cc set-retry-policy

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

@snippet agents_client_samples.cc custom-idempotency-policy

This will override the polling policies for `dialogflow_es::AgentsClient`

@snippet agents_client_samples.cc set-polling-policy


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

- [\c dialogflow_es::AgentsClient](@ref dialogflow_es::AgentsClient-retry-snippet)
- [\c dialogflow_es::AnswerRecordsClient](@ref dialogflow_es::AnswerRecordsClient-retry-snippet)
- [\c dialogflow_es::ContextsClient](@ref dialogflow_es::ContextsClient-retry-snippet)
- [\c dialogflow_es::ConversationDatasetsClient](@ref dialogflow_es::ConversationDatasetsClient-retry-snippet)
- [\c dialogflow_es::ConversationModelsClient](@ref dialogflow_es::ConversationModelsClient-retry-snippet)
- [\c dialogflow_es::ConversationProfilesClient](@ref dialogflow_es::ConversationProfilesClient-retry-snippet)
- [\c dialogflow_es::ConversationsClient](@ref dialogflow_es::ConversationsClient-retry-snippet)
- [\c dialogflow_es::DocumentsClient](@ref dialogflow_es::DocumentsClient-retry-snippet)
- [\c dialogflow_es::EncryptionSpecServiceClient](@ref dialogflow_es::EncryptionSpecServiceClient-retry-snippet)
- [\c dialogflow_es::EntityTypesClient](@ref dialogflow_es::EntityTypesClient-retry-snippet)
- [\c dialogflow_es::EnvironmentsClient](@ref dialogflow_es::EnvironmentsClient-retry-snippet)
- [\c dialogflow_es::FulfillmentsClient](@ref dialogflow_es::FulfillmentsClient-retry-snippet)
- [\c dialogflow_es::GeneratorsClient](@ref dialogflow_es::GeneratorsClient-retry-snippet)
- [\c dialogflow_es::IntentsClient](@ref dialogflow_es::IntentsClient-retry-snippet)
- [\c dialogflow_es::KnowledgeBasesClient](@ref dialogflow_es::KnowledgeBasesClient-retry-snippet)
- [\c dialogflow_es::ParticipantsClient](@ref dialogflow_es::ParticipantsClient-retry-snippet)
- [\c dialogflow_es::SessionEntityTypesClient](@ref dialogflow_es::SessionEntityTypesClient-retry-snippet)
- [\c dialogflow_es::SessionsClient](@ref dialogflow_es::SessionsClient-retry-snippet)
- [\c dialogflow_es::VersionsClient](@ref dialogflow_es::VersionsClient-retry-snippet)

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

@section dialogflow_es-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 dialogflow_es::AgentsClient-retry-snippet Override dialogflow_es::AgentsClient Retry Policies

This shows how to override the retry policies for dialogflow_es::AgentsClient:

@snippet google/cloud/dialogflow_es/samples/agents_client_samples.cc set-retry-policy

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

@snippet google/cloud/dialogflow_es/samples/agents_client_samples.cc custom-idempotency-policy

*/

/*! @page dialogflow_es::AnswerRecordsClient-retry-snippet Override dialogflow_es::AnswerRecordsClient Retry Policies

This shows how to override the retry policies for dialogflow_es::AnswerRecordsClient:

@snippet google/cloud/dialogflow_es/samples/answer_records_client_samples.cc set-retry-policy

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

@snippet google/cloud/dialogflow_es/samples/answer_records_client_samples.cc custom-idempotency-policy

*/

/*! @page dialogflow_es::ContextsClient-retry-snippet Override dialogflow_es::ContextsClient Retry Policies

This shows how to override the retry policies for dialogflow_es::ContextsClient:

@snippet google/cloud/dialogflow_es/samples/contexts_client_samples.cc set-retry-policy

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

@snippet google/cloud/dialogflow_es/samples/contexts_client_samples.cc custom-idempotency-policy

*/

/*! @page dialogflow_es::ConversationDatasetsClient-retry-snippet Override dialogflow_es::ConversationDatasetsClient Retry Policies

This shows how to override the retry policies for dialogflow_es::ConversationDatasetsClient:

@snippet google/cloud/dialogflow_es/samples/conversation_datasets_client_samples.cc set-retry-policy

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

@snippet google/cloud/dialogflow_es/samples/conversation_datasets_client_samples.cc custom-idempotency-policy

*/

/*! @page dialogflow_es::ConversationModelsClient-retry-snippet Override dialogflow_es::ConversationModelsClient Retry Policies

This shows how to override the retry policies for dialogflow_es::ConversationModelsClient:

@snippet google/cloud/dialogflow_es/samples/conversation_models_client_samples.cc set-retry-policy

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

@snippet google/cloud/dialogflow_es/samples/conversation_models_client_samples.cc custom-idempotency-policy

*/

/*! @page dialogflow_es::ConversationProfilesClient-retry-snippet Override dialogflow_es::ConversationProfilesClient Retry Policies

This shows how to override the retry policies for dialogflow_es::ConversationProfilesClient:

@snippet google/cloud/dialogflow_es/samples/conversation_profiles_client_samples.cc set-retry-policy

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

@snippet google/cloud/dialogflow_es/samples/conversation_profiles_client_samples.cc custom-idempotency-policy

*/

/*! @page dialogflow_es::ConversationsClient-retry-snippet Override dialogflow_es::ConversationsClient Retry Policies

This shows how to override the retry policies for dialogflow_es::ConversationsClient:

@snippet google/cloud/dialogflow_es/samples/conversations_client_samples.cc set-retry-policy

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

@snippet google/cloud/dialogflow_es/samples/conversations_client_samples.cc custom-idempotency-policy

*/

/*! @page dialogflow_es::DocumentsClient-retry-snippet Override dialogflow_es::DocumentsClient Retry Policies

This shows how to override the retry policies for dialogflow_es::DocumentsClient:

@snippet google/cloud/dialogflow_es/samples/documents_client_samples.cc set-retry-policy

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

@snippet google/cloud/dialogflow_es/samples/documents_client_samples.cc custom-idempotency-policy

*/

/*! @page dialogflow_es::EncryptionSpecServiceClient-retry-snippet Override dialogflow_es::EncryptionSpecServiceClient Retry Policies

This shows how to override the retry policies for dialogflow_es::EncryptionSpecServiceClient:

@snippet google/cloud/dialogflow_es/samples/encryption_spec_client_samples.cc set-retry-policy

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

@snippet google/cloud/dialogflow_es/samples/encryption_spec_client_samples.cc custom-idempotency-policy

*/

/*! @page dialogflow_es::EntityTypesClient-retry-snippet Override dialogflow_es::EntityTypesClient Retry Policies

This shows how to override the retry policies for dialogflow_es::EntityTypesClient:

@snippet google/cloud/dialogflow_es/samples/entity_types_client_samples.cc set-retry-policy

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

@snippet google/cloud/dialogflow_es/samples/entity_types_client_samples.cc custom-idempotency-policy

*/

/*! @page dialogflow_es::EnvironmentsClient-retry-snippet Override dialogflow_es::EnvironmentsClient Retry Policies

This shows how to override the retry policies for dialogflow_es::EnvironmentsClient:

@snippet google/cloud/dialogflow_es/samples/environments_client_samples.cc set-retry-policy

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

@snippet google/cloud/dialogflow_es/samples/environments_client_samples.cc custom-idempotency-policy

*/

/*! @page dialogflow_es::FulfillmentsClient-retry-snippet Override dialogflow_es::FulfillmentsClient Retry Policies

This shows how to override the retry policies for dialogflow_es::FulfillmentsClient:

@snippet google/cloud/dialogflow_es/samples/fulfillments_client_samples.cc set-retry-policy

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

@snippet google/cloud/dialogflow_es/samples/fulfillments_client_samples.cc custom-idempotency-policy

*/

/*! @page dialogflow_es::GeneratorsClient-retry-snippet Override dialogflow_es::GeneratorsClient Retry Policies

This shows how to override the retry policies for dialogflow_es::GeneratorsClient:

@snippet google/cloud/dialogflow_es/samples/generators_client_samples.cc set-retry-policy

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

@snippet google/cloud/dialogflow_es/samples/generators_client_samples.cc custom-idempotency-policy

*/

/*! @page dialogflow_es::IntentsClient-retry-snippet Override dialogflow_es::IntentsClient Retry Policies

This shows how to override the retry policies for dialogflow_es::IntentsClient:

@snippet google/cloud/dialogflow_es/samples/intents_client_samples.cc set-retry-policy

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

@snippet google/cloud/dialogflow_es/samples/intents_client_samples.cc custom-idempotency-policy

*/

/*! @page dialogflow_es::KnowledgeBasesClient-retry-snippet Override dialogflow_es::KnowledgeBasesClient Retry Policies

This shows how to override the retry policies for dialogflow_es::KnowledgeBasesClient:

@snippet google/cloud/dialogflow_es/samples/knowledge_bases_client_samples.cc set-retry-policy

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

@snippet google/cloud/dialogflow_es/samples/knowledge_bases_client_samples.cc custom-idempotency-policy

*/

/*! @page dialogflow_es::ParticipantsClient-retry-snippet Override dialogflow_es::ParticipantsClient Retry Policies

This shows how to override the retry policies for dialogflow_es::ParticipantsClient:

@snippet google/cloud/dialogflow_es/samples/participants_client_samples.cc set-retry-policy

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

@snippet google/cloud/dialogflow_es/samples/participants_client_samples.cc custom-idempotency-policy

*/

/*! @page dialogflow_es::SessionEntityTypesClient-retry-snippet Override dialogflow_es::SessionEntityTypesClient Retry Policies

This shows how to override the retry policies for dialogflow_es::SessionEntityTypesClient:

@snippet google/cloud/dialogflow_es/samples/session_entity_types_client_samples.cc set-retry-policy

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

@snippet google/cloud/dialogflow_es/samples/session_entity_types_client_samples.cc custom-idempotency-policy

*/

/*! @page dialogflow_es::SessionsClient-retry-snippet Override dialogflow_es::SessionsClient Retry Policies

This shows how to override the retry policies for dialogflow_es::SessionsClient:

@snippet google/cloud/dialogflow_es/samples/sessions_client_samples.cc set-retry-policy

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

@snippet google/cloud/dialogflow_es/samples/sessions_client_samples.cc custom-idempotency-policy

*/

/*! @page dialogflow_es::VersionsClient-retry-snippet Override dialogflow_es::VersionsClient Retry Policies

This shows how to override the retry policies for dialogflow_es::VersionsClient:

@snippet google/cloud/dialogflow_es/samples/versions_client_samples.cc set-retry-policy

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

@snippet google/cloud/dialogflow_es/samples/versions_client_samples.cc custom-idempotency-policy

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