diff --git a/ci/generate-markdown/update-library-landing-dox.sh b/ci/generate-markdown/update-library-landing-dox.sh index 6b6a23fd89a8c..33e0f19afa839 100755 --- a/ci/generate-markdown/update-library-landing-dox.sh +++ b/ci/generate-markdown/update-library-landing-dox.sh @@ -38,6 +38,7 @@ readonly EXPECTED=( "environment-variables.dox" "override-authentication.dox" "override-endpoint.dox" + "override-retry-policies.dox" ) for file in "${EXPECTED[@]}"; do if [[ ! -r "${DOCDIR}/${file}" ]]; then @@ -49,6 +50,7 @@ readonly MAIN_DOX="${DOCDIR}/main.dox" readonly ENVIRONMENT_DOX="${DOCDIR}/environment-variables.dox" readonly OVERRIDE_AUTHENTICATION_DOX="${DOCDIR}/override-authentication.dox" readonly OVERRIDE_ENDPOINT_DOX="${DOCDIR}/override-endpoint.dox" +readonly OVERRIDE_RETRY_POLICIES_DOX="${DOCDIR}/override-retry-policies.dox" inject_start="" inject_end="" @@ -189,3 +191,55 @@ _EOF_ done sed -n '//,$p' "${OVERRIDE_ENDPOINT_DOX}" ) | sponge "${OVERRIDE_ENDPOINT_DOX}" + +( + sed '//q' "${OVERRIDE_RETRY_POLICIES_DOX}" + if [[ ${#samples_cc[@]} -gt 0 ]]; then + sample_cc="${samples_cc[0]}" + client_name="${clients[${sample_cc}]}" + cat <<_EOF_ +For example, this will override the retry policies for \`${client_name}\`: + +@snippet $(basename "${sample_cc}") set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet $(basename "${sample_cc}") custom-idempotency-policy + +_EOF_ + if [[ ${#samples_cc[@]} -gt 1 ]]; then + echo + echo "Follow these links to find examples for other \\c *Client classes:" + echo + for sample_cc in "${samples_cc[@]}"; do + client_name="${clients[${sample_cc}]}" + # shellcheck disable=SC2016 + printf -- '- [\c %s](@ref %s-retry-snippet)\n' "${client_name}" "${client_name}" + done + fi + fi + echo + sed -n '//,$p' "${OVERRIDE_RETRY_POLICIES_DOX}" +) | sponge "${OVERRIDE_RETRY_POLICIES_DOX}" + +( + sed '//q' "${OVERRIDE_RETRY_POLICIES_DOX}" + for sample_cc in "${samples_cc[@]}"; do + client_name="${clients[${sample_cc}]}" + cat <<_EOF_ + +/*! @page ${client_name}-retry-snippet Override ${client_name} Retry Policies + +This shows how to override the retry policies for ${client_name}: + +@snippet ${sample_cc} set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet ${sample_cc} custom-idempotency-policy + +*/ +_EOF_ + done + sed -n '//,$p' "${OVERRIDE_RETRY_POLICIES_DOX}" +) | sponge "${OVERRIDE_RETRY_POLICIES_DOX}" diff --git a/generator/internal/scaffold_generator.cc b/generator/internal/scaffold_generator.cc index 76b840b3b44d4..1cb3974f9bd35 100644 --- a/generator/internal/scaffold_generator.cc +++ b/generator/internal/scaffold_generator.cc @@ -300,6 +300,7 @@ void GenerateScaffold( {"doc/environment-variables.dox", GenerateDoxygenEnvironmentPage}, {"doc/override-authentication.dox", GenerateOverrideAuthenticationPage}, {"doc/override-endpoint.dox", GenerateOverrideEndpointPage}, + {"doc/override-retry-policies.dox", GenerateOverrideRetryPoliciesPage}, {"doc/options.dox", GenerateDoxygenOptionsPage}, {"quickstart/README.md", GenerateQuickstartReadme}, {"quickstart/quickstart.cc", GenerateQuickstartSkeleton}, @@ -700,12 +701,6 @@ which should give you a taste of the $title$ C++ client library API. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -713,11 +708,12 @@ can override the default policies. endpoint. - @ref $library$-override-authentication - describes how to change the authentication credentials used by the library. +- @ref $library$-override-retry - describes how to change the default retry + policies. - @ref $library$-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/$site_root$ -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ )"""; @@ -838,6 +834,97 @@ client library to change this default. printer.Print(variables, kText); } +void GenerateOverrideRetryPoliciesPage( + std::ostream& os, std::map const& variables) { + auto constexpr kText = R"""(/*! +@page $library$-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 $library$-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. + +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 $library$-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 $library$-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 $library$-override-retry-example Example + + + + +@section $library$-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 + +*/ + +// +// +)"""; + google::protobuf::io::OstreamOutputStream output(&os); + google::protobuf::io::Printer printer(&output, '$'); + printer.Print(variables, kText); +} + void GenerateDoxygenOptionsPage( std::ostream& os, std::map const& variables) { auto constexpr kText = R"""(/*! diff --git a/generator/internal/scaffold_generator.h b/generator/internal/scaffold_generator.h index 23282fcb3e57d..0c237a4c7c677 100644 --- a/generator/internal/scaffold_generator.h +++ b/generator/internal/scaffold_generator.h @@ -128,6 +128,8 @@ void GenerateOverrideAuthenticationPage( std::ostream& os, std::map const& variables); void GenerateOverrideEndpointPage( std::ostream& os, std::map const& variables); +void GenerateOverrideRetryPoliciesPage( + std::ostream& os, std::map const& variables); void GenerateQuickstartReadme( std::ostream& os, std::map const& variables); void GenerateQuickstartSkeleton( diff --git a/generator/internal/scaffold_generator_test.cc b/generator/internal/scaffold_generator_test.cc index ca6210fa7862f..279ce700768b9 100644 --- a/generator/internal/scaffold_generator_test.cc +++ b/generator/internal/scaffold_generator_test.cc @@ -283,6 +283,8 @@ to Provides a placeholder to write this test. endpoint. - @ref test-override-authentication - describes how to change the authentication credentials used by the library. +- @ref test-override-retry - describes how to change the default retry + policies. )""")); } @@ -335,6 +337,16 @@ TEST_F(ScaffoldGenerator, OverrideEndpointPage) { )"""))); } +TEST_F(ScaffoldGenerator, OverrideRetryPoliciesPage) { + auto const vars = ScaffoldVars(path(), MockIndex(), service(), false); + std::ostringstream os; + GenerateOverrideRetryPoliciesPage(os, vars); + auto const actual = std::move(os).str(); + EXPECT_THAT(actual, AllOf(HasSubstr(R"""( +@page test-override-retry Override Retry, Backoff, and Idempotency Policies +)"""))); +} + TEST_F(ScaffoldGenerator, QuickstartReadme) { auto const vars = ScaffoldVars(path(), MockIndex(), service(), false); std::ostringstream os; diff --git a/google/cloud/accessapproval/doc/main.dox b/google/cloud/accessapproval/doc/main.dox index 3dfc00406279e..5cb98c9726725 100644 --- a/google/cloud/accessapproval/doc/main.dox +++ b/google/cloud/accessapproval/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,8 +36,9 @@ can override the default policies. endpoint. - @ref accessapproval-override-authentication - describes how to change the authentication credentials used by the library. +- @ref accessapproval-override-retry - describes how to change the default retry + policies. - @ref accessapproval-env - describes environment variables that can configure the behavior of the library. -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/accessapproval/doc/override-retry-policies.dox b/google/cloud/accessapproval/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..1a0453b4f02aa --- /dev/null +++ b/google/cloud/accessapproval/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page accessapproval-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 accessapproval-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. + +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 accessapproval-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 accessapproval-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 accessapproval-override-retry-example Example + + +For example, this will override the retry policies for `accessapproval_v1::AccessApprovalClient`: + +@snippet access_approval_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet access_approval_client_samples.cc custom-idempotency-policy + + + + +@section accessapproval-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 + +*/ + +// + +/*! @page accessapproval_v1::AccessApprovalClient-retry-snippet Override accessapproval_v1::AccessApprovalClient Retry Policies + +This shows how to override the retry policies for accessapproval_v1::AccessApprovalClient: + +@snippet google/cloud/accessapproval/v1/samples/access_approval_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/accessapproval/v1/samples/access_approval_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/accesscontextmanager/doc/main.dox b/google/cloud/accesscontextmanager/doc/main.dox index 1e8b7a77b73c5..4bdfa6358ed51 100644 --- a/google/cloud/accesscontextmanager/doc/main.dox +++ b/google/cloud/accesscontextmanager/doc/main.dox @@ -28,12 +28,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -41,9 +35,10 @@ can override the default policies. endpoint. - @ref accesscontextmanager-override-authentication - describes how to change the authentication credentials used by the library. +- @ref accesscontextmanager-override-retry - describes how to change the default retry + policies. - @ref accesscontextmanager-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/access-context-manager -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/accesscontextmanager/doc/override-retry-policies.dox b/google/cloud/accesscontextmanager/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..b77e199cd22f1 --- /dev/null +++ b/google/cloud/accesscontextmanager/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page accesscontextmanager-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 accesscontextmanager-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. + +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 accesscontextmanager-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 accesscontextmanager-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 accesscontextmanager-override-retry-example Example + + +For example, this will override the retry policies for `accesscontextmanager_v1::AccessContextManagerClient`: + +@snippet access_context_manager_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet access_context_manager_client_samples.cc custom-idempotency-policy + + + + +@section accesscontextmanager-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 + +*/ + +// + +/*! @page accesscontextmanager_v1::AccessContextManagerClient-retry-snippet Override accesscontextmanager_v1::AccessContextManagerClient Retry Policies + +This shows how to override the retry policies for accesscontextmanager_v1::AccessContextManagerClient: + +@snippet google/cloud/accesscontextmanager/v1/samples/access_context_manager_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/accesscontextmanager/v1/samples/access_context_manager_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/advisorynotifications/doc/main.dox b/google/cloud/advisorynotifications/doc/main.dox index a76ad47ef06b7..efd20e8f4910a 100644 --- a/google/cloud/advisorynotifications/doc/main.dox +++ b/google/cloud/advisorynotifications/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,9 +36,10 @@ can override the default policies. endpoint. - @ref advisorynotifications-override-authentication - describes how to change the authentication credentials used by the library. +- @ref advisorynotifications-override-retry - describes how to change the default retry + policies. - @ref advisorynotifications-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/advisory-notifications -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/advisorynotifications/doc/override-retry-policies.dox b/google/cloud/advisorynotifications/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..5e13caa1f2e5f --- /dev/null +++ b/google/cloud/advisorynotifications/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page advisorynotifications-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 advisorynotifications-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. + +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 advisorynotifications-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 advisorynotifications-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 advisorynotifications-override-retry-example Example + + +For example, this will override the retry policies for `advisorynotifications_v1::AdvisoryNotificationsServiceClient`: + +@snippet advisory_notifications_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet advisory_notifications_client_samples.cc custom-idempotency-policy + + + + +@section advisorynotifications-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 + +*/ + +// + +/*! @page advisorynotifications_v1::AdvisoryNotificationsServiceClient-retry-snippet Override advisorynotifications_v1::AdvisoryNotificationsServiceClient Retry Policies + +This shows how to override the retry policies for advisorynotifications_v1::AdvisoryNotificationsServiceClient: + +@snippet google/cloud/advisorynotifications/v1/samples/advisory_notifications_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/advisorynotifications/v1/samples/advisory_notifications_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/aiplatform/doc/main.dox b/google/cloud/aiplatform/doc/main.dox index d07c0f3bd5006..55fe2d0cb5f44 100644 --- a/google/cloud/aiplatform/doc/main.dox +++ b/google/cloud/aiplatform/doc/main.dox @@ -51,12 +51,6 @@ application. - [\c aiplatform_v1::VizierServiceClient](@ref google::cloud::aiplatform_v1::VizierServiceClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -64,10 +58,11 @@ can override the default policies. endpoint. - @ref aiplatform-override-authentication - describes how to change the authentication credentials used by the library. +- @ref aiplatform-override-retry - describes how to change the default retry + policies. - @ref aiplatform-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/vertex-ai -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/aiplatform/doc/override-retry-policies.dox b/google/cloud/aiplatform/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..99e1ada8f60d0 --- /dev/null +++ b/google/cloud/aiplatform/doc/override-retry-policies.dox @@ -0,0 +1,317 @@ +/*! + +@page aiplatform-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 aiplatform-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. + +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 aiplatform-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 aiplatform-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 aiplatform-override-retry-example Example + + +For example, this will override the retry policies for `aiplatform_v1::DatasetServiceClient`: + +@snippet dataset_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet dataset_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c aiplatform_v1::DatasetServiceClient](@ref aiplatform_v1::DatasetServiceClient-retry-snippet) +- [\c aiplatform_v1::EndpointServiceClient](@ref aiplatform_v1::EndpointServiceClient-retry-snippet) +- [\c aiplatform_v1::FeaturestoreServiceClient](@ref aiplatform_v1::FeaturestoreServiceClient-retry-snippet) +- [\c aiplatform_v1::FeaturestoreOnlineServingServiceClient](@ref aiplatform_v1::FeaturestoreOnlineServingServiceClient-retry-snippet) +- [\c aiplatform_v1::IndexServiceClient](@ref aiplatform_v1::IndexServiceClient-retry-snippet) +- [\c aiplatform_v1::IndexEndpointServiceClient](@ref aiplatform_v1::IndexEndpointServiceClient-retry-snippet) +- [\c aiplatform_v1::JobServiceClient](@ref aiplatform_v1::JobServiceClient-retry-snippet) +- [\c aiplatform_v1::MatchServiceClient](@ref aiplatform_v1::MatchServiceClient-retry-snippet) +- [\c aiplatform_v1::MetadataServiceClient](@ref aiplatform_v1::MetadataServiceClient-retry-snippet) +- [\c aiplatform_v1::MigrationServiceClient](@ref aiplatform_v1::MigrationServiceClient-retry-snippet) +- [\c aiplatform_v1::ModelServiceClient](@ref aiplatform_v1::ModelServiceClient-retry-snippet) +- [\c aiplatform_v1::ModelGardenServiceClient](@ref aiplatform_v1::ModelGardenServiceClient-retry-snippet) +- [\c aiplatform_v1::PipelineServiceClient](@ref aiplatform_v1::PipelineServiceClient-retry-snippet) +- [\c aiplatform_v1::PredictionServiceClient](@ref aiplatform_v1::PredictionServiceClient-retry-snippet) +- [\c aiplatform_v1::SpecialistPoolServiceClient](@ref aiplatform_v1::SpecialistPoolServiceClient-retry-snippet) +- [\c aiplatform_v1::TensorboardServiceClient](@ref aiplatform_v1::TensorboardServiceClient-retry-snippet) +- [\c aiplatform_v1::VizierServiceClient](@ref aiplatform_v1::VizierServiceClient-retry-snippet) + + + +@section aiplatform-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 + +*/ + +// + +/*! @page aiplatform_v1::DatasetServiceClient-retry-snippet Override aiplatform_v1::DatasetServiceClient Retry Policies + +This shows how to override the retry policies for aiplatform_v1::DatasetServiceClient: + +@snippet google/cloud/aiplatform/v1/samples/dataset_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/aiplatform/v1/samples/dataset_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page aiplatform_v1::EndpointServiceClient-retry-snippet Override aiplatform_v1::EndpointServiceClient Retry Policies + +This shows how to override the retry policies for aiplatform_v1::EndpointServiceClient: + +@snippet google/cloud/aiplatform/v1/samples/endpoint_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/aiplatform/v1/samples/endpoint_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page aiplatform_v1::FeaturestoreServiceClient-retry-snippet Override aiplatform_v1::FeaturestoreServiceClient Retry Policies + +This shows how to override the retry policies for aiplatform_v1::FeaturestoreServiceClient: + +@snippet google/cloud/aiplatform/v1/samples/featurestore_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/aiplatform/v1/samples/featurestore_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page aiplatform_v1::FeaturestoreOnlineServingServiceClient-retry-snippet Override aiplatform_v1::FeaturestoreOnlineServingServiceClient Retry Policies + +This shows how to override the retry policies for aiplatform_v1::FeaturestoreOnlineServingServiceClient: + +@snippet google/cloud/aiplatform/v1/samples/featurestore_online_serving_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/aiplatform/v1/samples/featurestore_online_serving_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page aiplatform_v1::IndexServiceClient-retry-snippet Override aiplatform_v1::IndexServiceClient Retry Policies + +This shows how to override the retry policies for aiplatform_v1::IndexServiceClient: + +@snippet google/cloud/aiplatform/v1/samples/index_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/aiplatform/v1/samples/index_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page aiplatform_v1::IndexEndpointServiceClient-retry-snippet Override aiplatform_v1::IndexEndpointServiceClient Retry Policies + +This shows how to override the retry policies for aiplatform_v1::IndexEndpointServiceClient: + +@snippet google/cloud/aiplatform/v1/samples/index_endpoint_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/aiplatform/v1/samples/index_endpoint_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page aiplatform_v1::JobServiceClient-retry-snippet Override aiplatform_v1::JobServiceClient Retry Policies + +This shows how to override the retry policies for aiplatform_v1::JobServiceClient: + +@snippet google/cloud/aiplatform/v1/samples/job_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/aiplatform/v1/samples/job_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page aiplatform_v1::MatchServiceClient-retry-snippet Override aiplatform_v1::MatchServiceClient Retry Policies + +This shows how to override the retry policies for aiplatform_v1::MatchServiceClient: + +@snippet google/cloud/aiplatform/v1/samples/match_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/aiplatform/v1/samples/match_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page aiplatform_v1::MetadataServiceClient-retry-snippet Override aiplatform_v1::MetadataServiceClient Retry Policies + +This shows how to override the retry policies for aiplatform_v1::MetadataServiceClient: + +@snippet google/cloud/aiplatform/v1/samples/metadata_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/aiplatform/v1/samples/metadata_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page aiplatform_v1::MigrationServiceClient-retry-snippet Override aiplatform_v1::MigrationServiceClient Retry Policies + +This shows how to override the retry policies for aiplatform_v1::MigrationServiceClient: + +@snippet google/cloud/aiplatform/v1/samples/migration_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/aiplatform/v1/samples/migration_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page aiplatform_v1::ModelServiceClient-retry-snippet Override aiplatform_v1::ModelServiceClient Retry Policies + +This shows how to override the retry policies for aiplatform_v1::ModelServiceClient: + +@snippet google/cloud/aiplatform/v1/samples/model_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/aiplatform/v1/samples/model_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page aiplatform_v1::ModelGardenServiceClient-retry-snippet Override aiplatform_v1::ModelGardenServiceClient Retry Policies + +This shows how to override the retry policies for aiplatform_v1::ModelGardenServiceClient: + +@snippet google/cloud/aiplatform/v1/samples/model_garden_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/aiplatform/v1/samples/model_garden_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page aiplatform_v1::PipelineServiceClient-retry-snippet Override aiplatform_v1::PipelineServiceClient Retry Policies + +This shows how to override the retry policies for aiplatform_v1::PipelineServiceClient: + +@snippet google/cloud/aiplatform/v1/samples/pipeline_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/aiplatform/v1/samples/pipeline_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page aiplatform_v1::PredictionServiceClient-retry-snippet Override aiplatform_v1::PredictionServiceClient Retry Policies + +This shows how to override the retry policies for aiplatform_v1::PredictionServiceClient: + +@snippet google/cloud/aiplatform/v1/samples/prediction_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/aiplatform/v1/samples/prediction_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page aiplatform_v1::SpecialistPoolServiceClient-retry-snippet Override aiplatform_v1::SpecialistPoolServiceClient Retry Policies + +This shows how to override the retry policies for aiplatform_v1::SpecialistPoolServiceClient: + +@snippet google/cloud/aiplatform/v1/samples/specialist_pool_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/aiplatform/v1/samples/specialist_pool_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page aiplatform_v1::TensorboardServiceClient-retry-snippet Override aiplatform_v1::TensorboardServiceClient Retry Policies + +This shows how to override the retry policies for aiplatform_v1::TensorboardServiceClient: + +@snippet google/cloud/aiplatform/v1/samples/tensorboard_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/aiplatform/v1/samples/tensorboard_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page aiplatform_v1::VizierServiceClient-retry-snippet Override aiplatform_v1::VizierServiceClient Retry Policies + +This shows how to override the retry policies for aiplatform_v1::VizierServiceClient: + +@snippet google/cloud/aiplatform/v1/samples/vizier_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/aiplatform/v1/samples/vizier_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/alloydb/doc/main.dox b/google/cloud/alloydb/doc/main.dox index 898d337be0feb..1d1e7754d93a3 100644 --- a/google/cloud/alloydb/doc/main.dox +++ b/google/cloud/alloydb/doc/main.dox @@ -40,12 +40,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -53,9 +47,10 @@ can override the default policies. endpoint. - @ref alloydb-override-authentication - describes how to change the authentication credentials used by the library. +- @ref alloydb-override-retry - describes how to change the default retry + policies. - @ref alloydb-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/alloydb -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/alloydb/doc/override-retry-policies.dox b/google/cloud/alloydb/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..dfb34d428a203 --- /dev/null +++ b/google/cloud/alloydb/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page alloydb-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 alloydb-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. + +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 alloydb-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 alloydb-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 alloydb-override-retry-example Example + + +For example, this will override the retry policies for `alloydb_v1::AlloyDBAdminClient`: + +@snippet alloy_db_admin_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet alloy_db_admin_client_samples.cc custom-idempotency-policy + + + + +@section alloydb-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 + +*/ + +// + +/*! @page alloydb_v1::AlloyDBAdminClient-retry-snippet Override alloydb_v1::AlloyDBAdminClient Retry Policies + +This shows how to override the retry policies for alloydb_v1::AlloyDBAdminClient: + +@snippet google/cloud/alloydb/v1/samples/alloy_db_admin_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/alloydb/v1/samples/alloy_db_admin_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/apigateway/doc/main.dox b/google/cloud/apigateway/doc/main.dox index c5b08654d4b84..a9dad22c7f513 100644 --- a/google/cloud/apigateway/doc/main.dox +++ b/google/cloud/apigateway/doc/main.dox @@ -28,12 +28,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -41,9 +35,10 @@ can override the default policies. endpoint. - @ref apigateway-override-authentication - describes how to change the authentication credentials used by the library. +- @ref apigateway-override-retry - describes how to change the default retry + policies. - @ref apigateway-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/api-gateway -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/apigateway/doc/override-retry-policies.dox b/google/cloud/apigateway/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..6e5cae578beae --- /dev/null +++ b/google/cloud/apigateway/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page apigateway-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 apigateway-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. + +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 apigateway-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 apigateway-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 apigateway-override-retry-example Example + + +For example, this will override the retry policies for `apigateway_v1::ApiGatewayServiceClient`: + +@snippet api_gateway_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet api_gateway_client_samples.cc custom-idempotency-policy + + + + +@section apigateway-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 + +*/ + +// + +/*! @page apigateway_v1::ApiGatewayServiceClient-retry-snippet Override apigateway_v1::ApiGatewayServiceClient Retry Policies + +This shows how to override the retry policies for apigateway_v1::ApiGatewayServiceClient: + +@snippet google/cloud/apigateway/v1/samples/api_gateway_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/apigateway/v1/samples/api_gateway_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/apigeeconnect/doc/main.dox b/google/cloud/apigeeconnect/doc/main.dox index 634351bbbc336..a1b47268210bc 100644 --- a/google/cloud/apigeeconnect/doc/main.dox +++ b/google/cloud/apigeeconnect/doc/main.dox @@ -32,12 +32,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -45,9 +39,10 @@ can override the default policies. endpoint. - @ref apigeeconnect-override-authentication - describes how to change the authentication credentials used by the library. +- @ref apigeeconnect-override-retry - describes how to change the default retry + policies. - @ref apigeeconnect-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/apigee/docs/hybrid/ -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/apigeeconnect/doc/override-retry-policies.dox b/google/cloud/apigeeconnect/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..7a786af6f9125 --- /dev/null +++ b/google/cloud/apigeeconnect/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page apigeeconnect-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 apigeeconnect-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. + +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 apigeeconnect-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 apigeeconnect-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 apigeeconnect-override-retry-example Example + + +For example, this will override the retry policies for `apigeeconnect_v1::ConnectionServiceClient`: + +@snippet connection_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet connection_client_samples.cc custom-idempotency-policy + + + + +@section apigeeconnect-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 + +*/ + +// + +/*! @page apigeeconnect_v1::ConnectionServiceClient-retry-snippet Override apigeeconnect_v1::ConnectionServiceClient Retry Policies + +This shows how to override the retry policies for apigeeconnect_v1::ConnectionServiceClient: + +@snippet google/cloud/apigeeconnect/v1/samples/connection_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/apigeeconnect/v1/samples/connection_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/apikeys/doc/main.dox b/google/cloud/apikeys/doc/main.dox index 31d6304032294..dbefffa31227c 100644 --- a/google/cloud/apikeys/doc/main.dox +++ b/google/cloud/apikeys/doc/main.dox @@ -28,12 +28,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -41,9 +35,10 @@ can override the default policies. endpoint. - @ref apikeys-override-authentication - describes how to change the authentication credentials used by the library. +- @ref apikeys-override-retry - describes how to change the default retry + policies. - @ref apikeys-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/api-keys -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/apikeys/doc/override-retry-policies.dox b/google/cloud/apikeys/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..3e2dc6f0632cd --- /dev/null +++ b/google/cloud/apikeys/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page apikeys-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 apikeys-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. + +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 apikeys-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 apikeys-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 apikeys-override-retry-example Example + + +For example, this will override the retry policies for `apikeys_v2::ApiKeysClient`: + +@snippet api_keys_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet api_keys_client_samples.cc custom-idempotency-policy + + + + +@section apikeys-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 + +*/ + +// + +/*! @page apikeys_v2::ApiKeysClient-retry-snippet Override apikeys_v2::ApiKeysClient Retry Policies + +This shows how to override the retry policies for apikeys_v2::ApiKeysClient: + +@snippet google/cloud/apikeys/v2/samples/api_keys_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/apikeys/v2/samples/api_keys_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/appengine/doc/main.dox b/google/cloud/appengine/doc/main.dox index ca20a7d087ce9..50c961ee24dc3 100644 --- a/google/cloud/appengine/doc/main.dox +++ b/google/cloud/appengine/doc/main.dox @@ -40,12 +40,6 @@ application. - [\c appengine_v1::VersionsClient](@ref google::cloud::appengine_v1::VersionsClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -53,9 +47,10 @@ can override the default policies. endpoint. - @ref appengine-override-authentication - describes how to change the authentication credentials used by the library. +- @ref appengine-override-retry - describes how to change the default retry + policies. - @ref appengine-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/appengine/docs/admin-api -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/appengine/doc/override-retry-policies.dox b/google/cloud/appengine/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..98981f2927600 --- /dev/null +++ b/google/cloud/appengine/doc/override-retry-policies.dox @@ -0,0 +1,200 @@ +/*! + +@page appengine-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 appengine-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. + +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 appengine-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 appengine-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 appengine-override-retry-example Example + + +For example, this will override the retry policies for `appengine_v1::ApplicationsClient`: + +@snippet applications_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet applications_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c appengine_v1::ApplicationsClient](@ref appengine_v1::ApplicationsClient-retry-snippet) +- [\c appengine_v1::AuthorizedCertificatesClient](@ref appengine_v1::AuthorizedCertificatesClient-retry-snippet) +- [\c appengine_v1::AuthorizedDomainsClient](@ref appengine_v1::AuthorizedDomainsClient-retry-snippet) +- [\c appengine_v1::DomainMappingsClient](@ref appengine_v1::DomainMappingsClient-retry-snippet) +- [\c appengine_v1::FirewallClient](@ref appengine_v1::FirewallClient-retry-snippet) +- [\c appengine_v1::InstancesClient](@ref appengine_v1::InstancesClient-retry-snippet) +- [\c appengine_v1::ServicesClient](@ref appengine_v1::ServicesClient-retry-snippet) +- [\c appengine_v1::VersionsClient](@ref appengine_v1::VersionsClient-retry-snippet) + + + +@section appengine-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 + +*/ + +// + +/*! @page appengine_v1::ApplicationsClient-retry-snippet Override appengine_v1::ApplicationsClient Retry Policies + +This shows how to override the retry policies for appengine_v1::ApplicationsClient: + +@snippet google/cloud/appengine/v1/samples/applications_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/appengine/v1/samples/applications_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page appengine_v1::AuthorizedCertificatesClient-retry-snippet Override appengine_v1::AuthorizedCertificatesClient Retry Policies + +This shows how to override the retry policies for appengine_v1::AuthorizedCertificatesClient: + +@snippet google/cloud/appengine/v1/samples/authorized_certificates_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/appengine/v1/samples/authorized_certificates_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page appengine_v1::AuthorizedDomainsClient-retry-snippet Override appengine_v1::AuthorizedDomainsClient Retry Policies + +This shows how to override the retry policies for appengine_v1::AuthorizedDomainsClient: + +@snippet google/cloud/appengine/v1/samples/authorized_domains_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/appengine/v1/samples/authorized_domains_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page appengine_v1::DomainMappingsClient-retry-snippet Override appengine_v1::DomainMappingsClient Retry Policies + +This shows how to override the retry policies for appengine_v1::DomainMappingsClient: + +@snippet google/cloud/appengine/v1/samples/domain_mappings_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/appengine/v1/samples/domain_mappings_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page appengine_v1::FirewallClient-retry-snippet Override appengine_v1::FirewallClient Retry Policies + +This shows how to override the retry policies for appengine_v1::FirewallClient: + +@snippet google/cloud/appengine/v1/samples/firewall_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/appengine/v1/samples/firewall_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page appengine_v1::InstancesClient-retry-snippet Override appengine_v1::InstancesClient Retry Policies + +This shows how to override the retry policies for appengine_v1::InstancesClient: + +@snippet google/cloud/appengine/v1/samples/instances_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/appengine/v1/samples/instances_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page appengine_v1::ServicesClient-retry-snippet Override appengine_v1::ServicesClient Retry Policies + +This shows how to override the retry policies for appengine_v1::ServicesClient: + +@snippet google/cloud/appengine/v1/samples/services_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/appengine/v1/samples/services_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page appengine_v1::VersionsClient-retry-snippet Override appengine_v1::VersionsClient Retry Policies + +This shows how to override the retry policies for appengine_v1::VersionsClient: + +@snippet google/cloud/appengine/v1/samples/versions_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/appengine/v1/samples/versions_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/artifactregistry/doc/main.dox b/google/cloud/artifactregistry/doc/main.dox index 05a79ebb4747d..390f0e183519b 100644 --- a/google/cloud/artifactregistry/doc/main.dox +++ b/google/cloud/artifactregistry/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,9 +36,10 @@ can override the default policies. endpoint. - @ref artifactregistry-override-authentication - describes how to change the authentication credentials used by the library. +- @ref artifactregistry-override-retry - describes how to change the default retry + policies. - @ref artifactregistry-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/artifact-registry -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/artifactregistry/doc/override-retry-policies.dox b/google/cloud/artifactregistry/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..bfad02203a347 --- /dev/null +++ b/google/cloud/artifactregistry/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page artifactregistry-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 artifactregistry-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. + +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 artifactregistry-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 artifactregistry-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 artifactregistry-override-retry-example Example + + +For example, this will override the retry policies for `artifactregistry_v1::ArtifactRegistryClient`: + +@snippet artifact_registry_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet artifact_registry_client_samples.cc custom-idempotency-policy + + + + +@section artifactregistry-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 + +*/ + +// + +/*! @page artifactregistry_v1::ArtifactRegistryClient-retry-snippet Override artifactregistry_v1::ArtifactRegistryClient Retry Policies + +This shows how to override the retry policies for artifactregistry_v1::ArtifactRegistryClient: + +@snippet google/cloud/artifactregistry/v1/samples/artifact_registry_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/artifactregistry/v1/samples/artifact_registry_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/asset/doc/main.dox b/google/cloud/asset/doc/main.dox index e6f1c4d70bedf..d66f92eedbab9 100644 --- a/google/cloud/asset/doc/main.dox +++ b/google/cloud/asset/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,9 +36,10 @@ can override the default policies. endpoint. - @ref asset-override-authentication - describes how to change the authentication credentials used by the library. +- @ref asset-override-retry - describes how to change the default retry + policies. - @ref asset-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/asset-inventory -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/asset/doc/override-retry-policies.dox b/google/cloud/asset/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..321cee69c4b91 --- /dev/null +++ b/google/cloud/asset/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page asset-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 asset-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. + +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 asset-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 asset-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 asset-override-retry-example Example + + +For example, this will override the retry policies for `asset_v1::AssetServiceClient`: + +@snippet asset_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet asset_client_samples.cc custom-idempotency-policy + + + + +@section asset-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 + +*/ + +// + +/*! @page asset_v1::AssetServiceClient-retry-snippet Override asset_v1::AssetServiceClient Retry Policies + +This shows how to override the retry policies for asset_v1::AssetServiceClient: + +@snippet google/cloud/asset/v1/samples/asset_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/asset/v1/samples/asset_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/assuredworkloads/doc/main.dox b/google/cloud/assuredworkloads/doc/main.dox index e8b6684bddce5..b55d9c585e2c9 100644 --- a/google/cloud/assuredworkloads/doc/main.dox +++ b/google/cloud/assuredworkloads/doc/main.dox @@ -30,12 +30,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -43,8 +37,9 @@ can override the default policies. endpoint. - @ref assuredworkloads-override-authentication - describes how to change the authentication credentials used by the library. +- @ref assuredworkloads-override-retry - describes how to change the default retry + policies. - @ref assuredworkloads-env - describes environment variables that can configure the behavior of the library. -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/assuredworkloads/doc/override-retry-policies.dox b/google/cloud/assuredworkloads/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..65f382ced03d7 --- /dev/null +++ b/google/cloud/assuredworkloads/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page assuredworkloads-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 assuredworkloads-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. + +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 assuredworkloads-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 assuredworkloads-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 assuredworkloads-override-retry-example Example + + +For example, this will override the retry policies for `assuredworkloads_v1::AssuredWorkloadsServiceClient`: + +@snippet assured_workloads_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet assured_workloads_client_samples.cc custom-idempotency-policy + + + + +@section assuredworkloads-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 + +*/ + +// + +/*! @page assuredworkloads_v1::AssuredWorkloadsServiceClient-retry-snippet Override assuredworkloads_v1::AssuredWorkloadsServiceClient Retry Policies + +This shows how to override the retry policies for assuredworkloads_v1::AssuredWorkloadsServiceClient: + +@snippet google/cloud/assuredworkloads/v1/samples/assured_workloads_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/assuredworkloads/v1/samples/assured_workloads_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/automl/doc/main.dox b/google/cloud/automl/doc/main.dox index 32c160d815811..ca1b3f5ab0429 100644 --- a/google/cloud/automl/doc/main.dox +++ b/google/cloud/automl/doc/main.dox @@ -35,12 +35,6 @@ application. - [\c automl_v1::PredictionServiceClient](@ref google::cloud::automl_v1::PredictionServiceClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -48,9 +42,10 @@ can override the default policies. endpoint. - @ref automl-override-authentication - describes how to change the authentication credentials used by the library. +- @ref automl-override-retry - describes how to change the default retry + policies. - @ref automl-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/automl -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/automl/doc/override-retry-policies.dox b/google/cloud/automl/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..83101d2c1b6f8 --- /dev/null +++ b/google/cloud/automl/doc/override-retry-policies.dox @@ -0,0 +1,122 @@ +/*! + +@page automl-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 automl-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. + +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 automl-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 automl-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 automl-override-retry-example Example + + +For example, this will override the retry policies for `automl_v1::AutoMlClient`: + +@snippet auto_ml_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet auto_ml_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c automl_v1::AutoMlClient](@ref automl_v1::AutoMlClient-retry-snippet) +- [\c automl_v1::PredictionServiceClient](@ref automl_v1::PredictionServiceClient-retry-snippet) + + + +@section automl-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 + +*/ + +// + +/*! @page automl_v1::AutoMlClient-retry-snippet Override automl_v1::AutoMlClient Retry Policies + +This shows how to override the retry policies for automl_v1::AutoMlClient: + +@snippet google/cloud/automl/v1/samples/auto_ml_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/automl/v1/samples/auto_ml_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page automl_v1::PredictionServiceClient-retry-snippet Override automl_v1::PredictionServiceClient Retry Policies + +This shows how to override the retry policies for automl_v1::PredictionServiceClient: + +@snippet google/cloud/automl/v1/samples/prediction_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/automl/v1/samples/prediction_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/baremetalsolution/doc/main.dox b/google/cloud/baremetalsolution/doc/main.dox index df4a727e5e4a4..2a9dd94ceee66 100644 --- a/google/cloud/baremetalsolution/doc/main.dox +++ b/google/cloud/baremetalsolution/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,9 +36,10 @@ can override the default policies. endpoint. - @ref baremetalsolution-override-authentication - describes how to change the authentication credentials used by the library. +- @ref baremetalsolution-override-retry - describes how to change the default retry + policies. - @ref baremetalsolution-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/bare-metal -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/baremetalsolution/doc/override-retry-policies.dox b/google/cloud/baremetalsolution/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..41db7b05ff1bc --- /dev/null +++ b/google/cloud/baremetalsolution/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page baremetalsolution-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 baremetalsolution-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. + +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 baremetalsolution-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 baremetalsolution-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 baremetalsolution-override-retry-example Example + + +For example, this will override the retry policies for `baremetalsolution_v2::BareMetalSolutionClient`: + +@snippet bare_metal_solution_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet bare_metal_solution_client_samples.cc custom-idempotency-policy + + + + +@section baremetalsolution-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 + +*/ + +// + +/*! @page baremetalsolution_v2::BareMetalSolutionClient-retry-snippet Override baremetalsolution_v2::BareMetalSolutionClient Retry Policies + +This shows how to override the retry policies for baremetalsolution_v2::BareMetalSolutionClient: + +@snippet google/cloud/baremetalsolution/v2/samples/bare_metal_solution_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/baremetalsolution/v2/samples/bare_metal_solution_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/batch/doc/main.dox b/google/cloud/batch/doc/main.dox index 7497919f2c7f2..328511e328ef9 100644 --- a/google/cloud/batch/doc/main.dox +++ b/google/cloud/batch/doc/main.dox @@ -27,12 +27,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -40,9 +34,10 @@ can override the default policies. endpoint. - @ref batch-override-authentication - describes how to change the authentication credentials used by the library. +- @ref batch-override-retry - describes how to change the default retry + policies. - @ref batch-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/batch -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/batch/doc/override-retry-policies.dox b/google/cloud/batch/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..5391451bd76d7 --- /dev/null +++ b/google/cloud/batch/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page batch-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 batch-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. + +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 batch-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 batch-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 batch-override-retry-example Example + + +For example, this will override the retry policies for `batch_v1::BatchServiceClient`: + +@snippet batch_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet batch_client_samples.cc custom-idempotency-policy + + + + +@section batch-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 + +*/ + +// + +/*! @page batch_v1::BatchServiceClient-retry-snippet Override batch_v1::BatchServiceClient Retry Policies + +This shows how to override the retry policies for batch_v1::BatchServiceClient: + +@snippet google/cloud/batch/v1/samples/batch_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/batch/v1/samples/batch_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/beyondcorp/doc/main.dox b/google/cloud/beyondcorp/doc/main.dox index 929f347841533..da9b340c864cc 100644 --- a/google/cloud/beyondcorp/doc/main.dox +++ b/google/cloud/beyondcorp/doc/main.dox @@ -40,12 +40,6 @@ application. - [\c beyondcorp_clientgateways_v1::ClientGatewaysServiceClient](@ref google::cloud::beyondcorp_clientgateways_v1::ClientGatewaysServiceClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -53,9 +47,10 @@ can override the default policies. endpoint. - @ref beyondcorp-override-authentication - describes how to change the authentication credentials used by the library. +- @ref beyondcorp-override-retry - describes how to change the default retry + policies. - @ref beyondcorp-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/beyondcorp -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/beyondcorp/doc/override-retry-policies.dox b/google/cloud/beyondcorp/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..c14efd1a180ba --- /dev/null +++ b/google/cloud/beyondcorp/doc/override-retry-policies.dox @@ -0,0 +1,161 @@ +/*! + +@page beyondcorp-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 beyondcorp-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. + +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 beyondcorp-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 beyondcorp-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 beyondcorp-override-retry-example Example + + +For example, this will override the retry policies for `beyondcorp_appconnections_v1::AppConnectionsServiceClient`: + +@snippet app_connections_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet app_connections_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c beyondcorp_appconnections_v1::AppConnectionsServiceClient](@ref beyondcorp_appconnections_v1::AppConnectionsServiceClient-retry-snippet) +- [\c beyondcorp_appconnectors_v1::AppConnectorsServiceClient](@ref beyondcorp_appconnectors_v1::AppConnectorsServiceClient-retry-snippet) +- [\c beyondcorp_appgateways_v1::AppGatewaysServiceClient](@ref beyondcorp_appgateways_v1::AppGatewaysServiceClient-retry-snippet) +- [\c beyondcorp_clientconnectorservices_v1::ClientConnectorServicesServiceClient](@ref beyondcorp_clientconnectorservices_v1::ClientConnectorServicesServiceClient-retry-snippet) +- [\c beyondcorp_clientgateways_v1::ClientGatewaysServiceClient](@ref beyondcorp_clientgateways_v1::ClientGatewaysServiceClient-retry-snippet) + + + +@section beyondcorp-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 + +*/ + +// + +/*! @page beyondcorp_appconnections_v1::AppConnectionsServiceClient-retry-snippet Override beyondcorp_appconnections_v1::AppConnectionsServiceClient Retry Policies + +This shows how to override the retry policies for beyondcorp_appconnections_v1::AppConnectionsServiceClient: + +@snippet google/cloud/beyondcorp/appconnections/v1/samples/app_connections_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/beyondcorp/appconnections/v1/samples/app_connections_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page beyondcorp_appconnectors_v1::AppConnectorsServiceClient-retry-snippet Override beyondcorp_appconnectors_v1::AppConnectorsServiceClient Retry Policies + +This shows how to override the retry policies for beyondcorp_appconnectors_v1::AppConnectorsServiceClient: + +@snippet google/cloud/beyondcorp/appconnectors/v1/samples/app_connectors_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/beyondcorp/appconnectors/v1/samples/app_connectors_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page beyondcorp_appgateways_v1::AppGatewaysServiceClient-retry-snippet Override beyondcorp_appgateways_v1::AppGatewaysServiceClient Retry Policies + +This shows how to override the retry policies for beyondcorp_appgateways_v1::AppGatewaysServiceClient: + +@snippet google/cloud/beyondcorp/appgateways/v1/samples/app_gateways_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/beyondcorp/appgateways/v1/samples/app_gateways_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page beyondcorp_clientconnectorservices_v1::ClientConnectorServicesServiceClient-retry-snippet Override beyondcorp_clientconnectorservices_v1::ClientConnectorServicesServiceClient Retry Policies + +This shows how to override the retry policies for beyondcorp_clientconnectorservices_v1::ClientConnectorServicesServiceClient: + +@snippet google/cloud/beyondcorp/clientconnectorservices/v1/samples/client_connector_services_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/beyondcorp/clientconnectorservices/v1/samples/client_connector_services_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page beyondcorp_clientgateways_v1::ClientGatewaysServiceClient-retry-snippet Override beyondcorp_clientgateways_v1::ClientGatewaysServiceClient Retry Policies + +This shows how to override the retry policies for beyondcorp_clientgateways_v1::ClientGatewaysServiceClient: + +@snippet google/cloud/beyondcorp/clientgateways/v1/samples/client_gateways_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/beyondcorp/clientgateways/v1/samples/client_gateways_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/bigquery/doc/main.dox b/google/cloud/bigquery/doc/main.dox index 386dcba443a54..5a7ca80da5994 100644 --- a/google/cloud/bigquery/doc/main.dox +++ b/google/cloud/bigquery/doc/main.dox @@ -48,6 +48,8 @@ application. endpoint. - @ref bigquery-override-authentication - describes how to change the authentication credentials used by the library. +- @ref bigquery-override-retry - describes how to change the default retry + policies. - @ref bigquery-env - describes environment variables that can configure the behavior of the library. - @ref bigquery-read-mock diff --git a/google/cloud/bigquery/doc/override-retry-policies.dox b/google/cloud/bigquery/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..7c598c244f742 --- /dev/null +++ b/google/cloud/bigquery/doc/override-retry-policies.dox @@ -0,0 +1,213 @@ +/*! + +@page bigquery-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 bigquery-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. + +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 bigquery-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 bigquery-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 bigquery-override-retry-example Example + + +For example, this will override the retry policies for `bigquery_analyticshub_v1::AnalyticsHubServiceClient`: + +@snippet analytics_hub_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet analytics_hub_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c bigquery_analyticshub_v1::AnalyticsHubServiceClient](@ref bigquery_analyticshub_v1::AnalyticsHubServiceClient-retry-snippet) +- [\c bigquery_biglake_v1::MetastoreServiceClient](@ref bigquery_biglake_v1::MetastoreServiceClient-retry-snippet) +- [\c bigquery_connection_v1::ConnectionServiceClient](@ref bigquery_connection_v1::ConnectionServiceClient-retry-snippet) +- [\c bigquery_datapolicies_v1::DataPolicyServiceClient](@ref bigquery_datapolicies_v1::DataPolicyServiceClient-retry-snippet) +- [\c bigquery_datatransfer_v1::DataTransferServiceClient](@ref bigquery_datatransfer_v1::DataTransferServiceClient-retry-snippet) +- [\c bigquery_migration_v2::MigrationServiceClient](@ref bigquery_migration_v2::MigrationServiceClient-retry-snippet) +- [\c bigquery_reservation_v1::ReservationServiceClient](@ref bigquery_reservation_v1::ReservationServiceClient-retry-snippet) +- [\c bigquery_storage_v1::BigQueryReadClient](@ref bigquery_storage_v1::BigQueryReadClient-retry-snippet) +- [\c bigquery_storage_v1::BigQueryWriteClient](@ref bigquery_storage_v1::BigQueryWriteClient-retry-snippet) + + + +@section bigquery-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 + +*/ + +// + +/*! @page bigquery_analyticshub_v1::AnalyticsHubServiceClient-retry-snippet Override bigquery_analyticshub_v1::AnalyticsHubServiceClient Retry Policies + +This shows how to override the retry policies for bigquery_analyticshub_v1::AnalyticsHubServiceClient: + +@snippet google/cloud/bigquery/analyticshub/v1/samples/analytics_hub_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/bigquery/analyticshub/v1/samples/analytics_hub_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page bigquery_biglake_v1::MetastoreServiceClient-retry-snippet Override bigquery_biglake_v1::MetastoreServiceClient Retry Policies + +This shows how to override the retry policies for bigquery_biglake_v1::MetastoreServiceClient: + +@snippet google/cloud/bigquery/biglake/v1/samples/metastore_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/bigquery/biglake/v1/samples/metastore_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page bigquery_connection_v1::ConnectionServiceClient-retry-snippet Override bigquery_connection_v1::ConnectionServiceClient Retry Policies + +This shows how to override the retry policies for bigquery_connection_v1::ConnectionServiceClient: + +@snippet google/cloud/bigquery/connection/v1/samples/connection_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/bigquery/connection/v1/samples/connection_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page bigquery_datapolicies_v1::DataPolicyServiceClient-retry-snippet Override bigquery_datapolicies_v1::DataPolicyServiceClient Retry Policies + +This shows how to override the retry policies for bigquery_datapolicies_v1::DataPolicyServiceClient: + +@snippet google/cloud/bigquery/datapolicies/v1/samples/data_policy_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/bigquery/datapolicies/v1/samples/data_policy_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page bigquery_datatransfer_v1::DataTransferServiceClient-retry-snippet Override bigquery_datatransfer_v1::DataTransferServiceClient Retry Policies + +This shows how to override the retry policies for bigquery_datatransfer_v1::DataTransferServiceClient: + +@snippet google/cloud/bigquery/datatransfer/v1/samples/data_transfer_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/bigquery/datatransfer/v1/samples/data_transfer_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page bigquery_migration_v2::MigrationServiceClient-retry-snippet Override bigquery_migration_v2::MigrationServiceClient Retry Policies + +This shows how to override the retry policies for bigquery_migration_v2::MigrationServiceClient: + +@snippet google/cloud/bigquery/migration/v2/samples/migration_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/bigquery/migration/v2/samples/migration_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page bigquery_reservation_v1::ReservationServiceClient-retry-snippet Override bigquery_reservation_v1::ReservationServiceClient Retry Policies + +This shows how to override the retry policies for bigquery_reservation_v1::ReservationServiceClient: + +@snippet google/cloud/bigquery/reservation/v1/samples/reservation_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/bigquery/reservation/v1/samples/reservation_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page bigquery_storage_v1::BigQueryReadClient-retry-snippet Override bigquery_storage_v1::BigQueryReadClient Retry Policies + +This shows how to override the retry policies for bigquery_storage_v1::BigQueryReadClient: + +@snippet google/cloud/bigquery/storage/v1/samples/bigquery_read_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/bigquery/storage/v1/samples/bigquery_read_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page bigquery_storage_v1::BigQueryWriteClient-retry-snippet Override bigquery_storage_v1::BigQueryWriteClient Retry Policies + +This shows how to override the retry policies for bigquery_storage_v1::BigQueryWriteClient: + +@snippet google/cloud/bigquery/storage/v1/samples/bigquery_write_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/bigquery/storage/v1/samples/bigquery_write_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/billing/doc/main.dox b/google/cloud/billing/doc/main.dox index 8b15f7f14a080..7683e8d40b7dd 100644 --- a/google/cloud/billing/doc/main.dox +++ b/google/cloud/billing/doc/main.dox @@ -36,12 +36,6 @@ application. - [\c billing_v1::CloudCatalogClient](@ref google::cloud::billing_v1::CloudCatalogClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -49,8 +43,9 @@ can override the default policies. endpoint. - @ref billing-override-authentication - describes how to change the authentication credentials used by the library. +- @ref billing-override-retry - describes how to change the default retry + policies. - @ref billing-env - describes environment variables that can configure the behavior of the library. -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/billing/doc/override-retry-policies.dox b/google/cloud/billing/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..64d9b4ff81795 --- /dev/null +++ b/google/cloud/billing/doc/override-retry-policies.dox @@ -0,0 +1,135 @@ +/*! + +@page billing-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 billing-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. + +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 billing-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 billing-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 billing-override-retry-example Example + + +For example, this will override the retry policies for `billing_budgets_v1::BudgetServiceClient`: + +@snippet budget_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet budget_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c billing_budgets_v1::BudgetServiceClient](@ref billing_budgets_v1::BudgetServiceClient-retry-snippet) +- [\c billing_v1::CloudBillingClient](@ref billing_v1::CloudBillingClient-retry-snippet) +- [\c billing_v1::CloudCatalogClient](@ref billing_v1::CloudCatalogClient-retry-snippet) + + + +@section billing-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 + +*/ + +// + +/*! @page billing_budgets_v1::BudgetServiceClient-retry-snippet Override billing_budgets_v1::BudgetServiceClient Retry Policies + +This shows how to override the retry policies for billing_budgets_v1::BudgetServiceClient: + +@snippet google/cloud/billing/budgets/v1/samples/budget_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/billing/budgets/v1/samples/budget_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page billing_v1::CloudBillingClient-retry-snippet Override billing_v1::CloudBillingClient Retry Policies + +This shows how to override the retry policies for billing_v1::CloudBillingClient: + +@snippet google/cloud/billing/v1/samples/cloud_billing_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/billing/v1/samples/cloud_billing_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page billing_v1::CloudCatalogClient-retry-snippet Override billing_v1::CloudCatalogClient Retry Policies + +This shows how to override the retry policies for billing_v1::CloudCatalogClient: + +@snippet google/cloud/billing/v1/samples/cloud_catalog_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/billing/v1/samples/cloud_catalog_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/binaryauthorization/doc/main.dox b/google/cloud/binaryauthorization/doc/main.dox index 234b5d619b98e..0adb46382f6d8 100644 --- a/google/cloud/binaryauthorization/doc/main.dox +++ b/google/cloud/binaryauthorization/doc/main.dox @@ -36,12 +36,6 @@ application. - [\c binaryauthorization_v1::ValidationHelperV1Client](@ref google::cloud::binaryauthorization_v1::ValidationHelperV1Client) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -49,9 +43,10 @@ can override the default policies. endpoint. - @ref binaryauthorization-override-authentication - describes how to change the authentication credentials used by the library. +- @ref binaryauthorization-override-retry - describes how to change the default retry + policies. - @ref binaryauthorization-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/binary-authorization -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/binaryauthorization/doc/override-retry-policies.dox b/google/cloud/binaryauthorization/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..db317f0447759 --- /dev/null +++ b/google/cloud/binaryauthorization/doc/override-retry-policies.dox @@ -0,0 +1,135 @@ +/*! + +@page binaryauthorization-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 binaryauthorization-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. + +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 binaryauthorization-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 binaryauthorization-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 binaryauthorization-override-retry-example Example + + +For example, this will override the retry policies for `binaryauthorization_v1::BinauthzManagementServiceV1Client`: + +@snippet binauthz_management_service_v1_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet binauthz_management_service_v1_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c binaryauthorization_v1::BinauthzManagementServiceV1Client](@ref binaryauthorization_v1::BinauthzManagementServiceV1Client-retry-snippet) +- [\c binaryauthorization_v1::SystemPolicyV1Client](@ref binaryauthorization_v1::SystemPolicyV1Client-retry-snippet) +- [\c binaryauthorization_v1::ValidationHelperV1Client](@ref binaryauthorization_v1::ValidationHelperV1Client-retry-snippet) + + + +@section binaryauthorization-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 + +*/ + +// + +/*! @page binaryauthorization_v1::BinauthzManagementServiceV1Client-retry-snippet Override binaryauthorization_v1::BinauthzManagementServiceV1Client Retry Policies + +This shows how to override the retry policies for binaryauthorization_v1::BinauthzManagementServiceV1Client: + +@snippet google/cloud/binaryauthorization/v1/samples/binauthz_management_service_v1_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/binaryauthorization/v1/samples/binauthz_management_service_v1_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page binaryauthorization_v1::SystemPolicyV1Client-retry-snippet Override binaryauthorization_v1::SystemPolicyV1Client Retry Policies + +This shows how to override the retry policies for binaryauthorization_v1::SystemPolicyV1Client: + +@snippet google/cloud/binaryauthorization/v1/samples/system_policy_v1_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/binaryauthorization/v1/samples/system_policy_v1_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page binaryauthorization_v1::ValidationHelperV1Client-retry-snippet Override binaryauthorization_v1::ValidationHelperV1Client Retry Policies + +This shows how to override the retry policies for binaryauthorization_v1::ValidationHelperV1Client: + +@snippet google/cloud/binaryauthorization/v1/samples/validation_helper_v1_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/binaryauthorization/v1/samples/validation_helper_v1_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/certificatemanager/doc/main.dox b/google/cloud/certificatemanager/doc/main.dox index e5f20d363ebfe..d137038760b36 100644 --- a/google/cloud/certificatemanager/doc/main.dox +++ b/google/cloud/certificatemanager/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,9 +36,10 @@ can override the default policies. endpoint. - @ref certificatemanager-override-authentication - describes how to change the authentication credentials used by the library. +- @ref certificatemanager-override-retry - describes how to change the default retry + policies. - @ref certificatemanager-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/certificate-manager -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/certificatemanager/doc/override-retry-policies.dox b/google/cloud/certificatemanager/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..7d6dcbba041c0 --- /dev/null +++ b/google/cloud/certificatemanager/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page certificatemanager-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 certificatemanager-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. + +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 certificatemanager-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 certificatemanager-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 certificatemanager-override-retry-example Example + + +For example, this will override the retry policies for `certificatemanager_v1::CertificateManagerClient`: + +@snippet certificate_manager_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet certificate_manager_client_samples.cc custom-idempotency-policy + + + + +@section certificatemanager-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 + +*/ + +// + +/*! @page certificatemanager_v1::CertificateManagerClient-retry-snippet Override certificatemanager_v1::CertificateManagerClient Retry Policies + +This shows how to override the retry policies for certificatemanager_v1::CertificateManagerClient: + +@snippet google/cloud/certificatemanager/v1/samples/certificate_manager_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/certificatemanager/v1/samples/certificate_manager_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/channel/doc/main.dox b/google/cloud/channel/doc/main.dox index 962fed12dfe23..84076b3cf0903 100644 --- a/google/cloud/channel/doc/main.dox +++ b/google/cloud/channel/doc/main.dox @@ -30,12 +30,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -43,9 +37,10 @@ can override the default policies. endpoint. - @ref channel-override-authentication - describes how to change the authentication credentials used by the library. +- @ref channel-override-retry - describes how to change the default retry + policies. - @ref channel-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/channel -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/channel/doc/override-retry-policies.dox b/google/cloud/channel/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..3a12723ffb05b --- /dev/null +++ b/google/cloud/channel/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page channel-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 channel-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. + +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 channel-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 channel-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 channel-override-retry-example Example + + +For example, this will override the retry policies for `channel_v1::CloudChannelServiceClient`: + +@snippet cloud_channel_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet cloud_channel_client_samples.cc custom-idempotency-policy + + + + +@section channel-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 + +*/ + +// + +/*! @page channel_v1::CloudChannelServiceClient-retry-snippet Override channel_v1::CloudChannelServiceClient Retry Policies + +This shows how to override the retry policies for channel_v1::CloudChannelServiceClient: + +@snippet google/cloud/channel/v1/samples/cloud_channel_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/channel/v1/samples/cloud_channel_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/cloudbuild/doc/main.dox b/google/cloud/cloudbuild/doc/main.dox index 28e6efbf9ebdf..f54804e5bd644 100644 --- a/google/cloud/cloudbuild/doc/main.dox +++ b/google/cloud/cloudbuild/doc/main.dox @@ -34,12 +34,6 @@ application. - [\c cloudbuild_v2::RepositoryManagerClient](@ref google::cloud::cloudbuild_v2::RepositoryManagerClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -47,9 +41,10 @@ can override the default policies. endpoint. - @ref cloudbuild-override-authentication - describes how to change the authentication credentials used by the library. +- @ref cloudbuild-override-retry - describes how to change the default retry + policies. - @ref cloudbuild-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/build -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/cloudbuild/doc/override-retry-policies.dox b/google/cloud/cloudbuild/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..4ebebca13938a --- /dev/null +++ b/google/cloud/cloudbuild/doc/override-retry-policies.dox @@ -0,0 +1,122 @@ +/*! + +@page cloudbuild-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 cloudbuild-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. + +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 cloudbuild-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 cloudbuild-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 cloudbuild-override-retry-example Example + + +For example, this will override the retry policies for `cloudbuild_v1::CloudBuildClient`: + +@snippet cloud_build_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet cloud_build_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c cloudbuild_v1::CloudBuildClient](@ref cloudbuild_v1::CloudBuildClient-retry-snippet) +- [\c cloudbuild_v2::RepositoryManagerClient](@ref cloudbuild_v2::RepositoryManagerClient-retry-snippet) + + + +@section cloudbuild-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 + +*/ + +// + +/*! @page cloudbuild_v1::CloudBuildClient-retry-snippet Override cloudbuild_v1::CloudBuildClient Retry Policies + +This shows how to override the retry policies for cloudbuild_v1::CloudBuildClient: + +@snippet google/cloud/cloudbuild/v1/samples/cloud_build_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/cloudbuild/v1/samples/cloud_build_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page cloudbuild_v2::RepositoryManagerClient-retry-snippet Override cloudbuild_v2::RepositoryManagerClient Retry Policies + +This shows how to override the retry policies for cloudbuild_v2::RepositoryManagerClient: + +@snippet google/cloud/cloudbuild/v2/samples/repository_manager_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/cloudbuild/v2/samples/repository_manager_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/composer/doc/main.dox b/google/cloud/composer/doc/main.dox index 4cf25aee5cc16..4f5ba31277643 100644 --- a/google/cloud/composer/doc/main.dox +++ b/google/cloud/composer/doc/main.dox @@ -34,12 +34,6 @@ application. - [\c composer_v1::ImageVersionsClient](@ref google::cloud::composer_v1::ImageVersionsClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -47,9 +41,10 @@ can override the default policies. endpoint. - @ref composer-override-authentication - describes how to change the authentication credentials used by the library. +- @ref composer-override-retry - describes how to change the default retry + policies. - @ref composer-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/composer -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/composer/doc/override-retry-policies.dox b/google/cloud/composer/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..007d18ad6e698 --- /dev/null +++ b/google/cloud/composer/doc/override-retry-policies.dox @@ -0,0 +1,122 @@ +/*! + +@page composer-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 composer-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. + +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 composer-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 composer-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 composer-override-retry-example Example + + +For example, this will override the retry policies for `composer_v1::EnvironmentsClient`: + +@snippet environments_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet environments_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c composer_v1::EnvironmentsClient](@ref composer_v1::EnvironmentsClient-retry-snippet) +- [\c composer_v1::ImageVersionsClient](@ref composer_v1::ImageVersionsClient-retry-snippet) + + + +@section composer-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 + +*/ + +// + +/*! @page composer_v1::EnvironmentsClient-retry-snippet Override composer_v1::EnvironmentsClient Retry Policies + +This shows how to override the retry policies for composer_v1::EnvironmentsClient: + +@snippet google/cloud/composer/v1/samples/environments_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/composer/v1/samples/environments_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page composer_v1::ImageVersionsClient-retry-snippet Override composer_v1::ImageVersionsClient Retry Policies + +This shows how to override the retry policies for composer_v1::ImageVersionsClient: + +@snippet google/cloud/composer/v1/samples/image_versions_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/composer/v1/samples/image_versions_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/compute/doc/main.dox b/google/cloud/compute/doc/main.dox index 9736b8bdbee5b..369785b7c4754 100644 --- a/google/cloud/compute/doc/main.dox +++ b/google/cloud/compute/doc/main.dox @@ -36,12 +36,6 @@ application. - [\c compute_disks_v1::DisksClient](@ref google::cloud::compute_disks_v1::DisksClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -49,6 +43,8 @@ can override the default policies. endpoint. - @ref compute-override-authentication - describes how to change the authentication credentials used by the library. +- @ref compute-override-retry - describes how to change the default retry + policies. - @ref compute-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/compute diff --git a/google/cloud/compute/doc/override-retry-policies.dox b/google/cloud/compute/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..1409d8f78b44b --- /dev/null +++ b/google/cloud/compute/doc/override-retry-policies.dox @@ -0,0 +1,119 @@ +/*! + +@page compute-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 compute-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. + +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 compute-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 compute-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 compute-override-retry-example Example + + +For example, this will override the retry policies for `iam_admin_v1::IAMClient`: + +@snippet iam_client_samples.cc set-retry-policy + +Follow these links to find examples for other \c *Client classes: + +- [\c iam_admin_v1::IAMClient](@ref iam_admin_v1::IAMClient-retry-snippet) +- [\c iam_credentials_v1::IAMCredentialsClient](@ref iam_credentials_v1::IAMCredentialsClient-retry-snippet) +- [\c iam_v1::IAMPolicyClient](@ref iam_v1::IAMPolicyClient-retry-snippet) +- [\c iam_v2::PoliciesClient](@ref iam_v2::PoliciesClient-retry-snippet) + + + +@section compute-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 + +*/ + +// + +/*! @page iam_admin_v1::IAMClient-retry-snippet Override iam_admin_v1::IAMClient Retry Policies + +@snippet google/cloud/iam/admin/v1/samples/iam_client_samples.cc set-retry-policy + +*/ + +/*! @page iam_credentials_v1::IAMCredentialsClient-retry-snippet Override iam_credentials_v1::IAMCredentialsClient Retry Policies + +@snippet google/cloud/iam/credentials/v1/samples/iam_credentials_client_samples.cc set-retry-policy + +*/ + +/*! @page iam_v1::IAMPolicyClient-retry-snippet Override iam_v1::IAMPolicyClient Retry Policies + +@snippet google/cloud/iam/v1/samples/iam_policy_client_samples.cc set-retry-policy + +*/ + +/*! @page iam_v2::PoliciesClient-retry-snippet Override iam_v2::PoliciesClient Retry Policies + +@snippet google/cloud/iam/v2/samples/policies_client_samples.cc set-retry-policy + +*/ +// diff --git a/google/cloud/confidentialcomputing/doc/main.dox b/google/cloud/confidentialcomputing/doc/main.dox index 0aa69d720ec8c..14f94f9706ba8 100644 --- a/google/cloud/confidentialcomputing/doc/main.dox +++ b/google/cloud/confidentialcomputing/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,9 +36,10 @@ can override the default policies. endpoint. - @ref confidentialcomputing-override-authentication - describes how to change the authentication credentials used by the library. +- @ref confidentialcomputing-override-retry - describes how to change the default retry + policies. - @ref confidentialcomputing-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/confidential-computing -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/confidentialcomputing/doc/override-retry-policies.dox b/google/cloud/confidentialcomputing/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..3e472a3ddb208 --- /dev/null +++ b/google/cloud/confidentialcomputing/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page confidentialcomputing-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 confidentialcomputing-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. + +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 confidentialcomputing-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 confidentialcomputing-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 confidentialcomputing-override-retry-example Example + + +For example, this will override the retry policies for `confidentialcomputing_v1::ConfidentialComputingClient`: + +@snippet confidential_computing_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet confidential_computing_client_samples.cc custom-idempotency-policy + + + + +@section confidentialcomputing-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 + +*/ + +// + +/*! @page confidentialcomputing_v1::ConfidentialComputingClient-retry-snippet Override confidentialcomputing_v1::ConfidentialComputingClient Retry Policies + +This shows how to override the retry policies for confidentialcomputing_v1::ConfidentialComputingClient: + +@snippet google/cloud/confidentialcomputing/v1/samples/confidential_computing_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/confidentialcomputing/v1/samples/confidential_computing_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/connectors/doc/main.dox b/google/cloud/connectors/doc/main.dox index dcd356ef7880c..dce317cd6d610 100644 --- a/google/cloud/connectors/doc/main.dox +++ b/google/cloud/connectors/doc/main.dox @@ -30,12 +30,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -43,9 +37,10 @@ can override the default policies. endpoint. - @ref connectors-override-authentication - describes how to change the authentication credentials used by the library. +- @ref connectors-override-retry - describes how to change the default retry + policies. - @ref connectors-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/apigee/docs/api-platform/connectors/about-connectors -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/connectors/doc/override-retry-policies.dox b/google/cloud/connectors/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..ca9749910dd9c --- /dev/null +++ b/google/cloud/connectors/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page connectors-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 connectors-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. + +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 connectors-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 connectors-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 connectors-override-retry-example Example + + +For example, this will override the retry policies for `connectors_v1::ConnectorsClient`: + +@snippet connectors_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet connectors_client_samples.cc custom-idempotency-policy + + + + +@section connectors-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 + +*/ + +// + +/*! @page connectors_v1::ConnectorsClient-retry-snippet Override connectors_v1::ConnectorsClient Retry Policies + +This shows how to override the retry policies for connectors_v1::ConnectorsClient: + +@snippet google/cloud/connectors/v1/samples/connectors_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/connectors/v1/samples/connectors_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/contactcenterinsights/doc/main.dox b/google/cloud/contactcenterinsights/doc/main.dox index c0dc841123731..df147ef712301 100644 --- a/google/cloud/contactcenterinsights/doc/main.dox +++ b/google/cloud/contactcenterinsights/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,9 +36,10 @@ can override the default policies. endpoint. - @ref contactcenterinsights-override-authentication - describes how to change the authentication credentials used by the library. +- @ref contactcenterinsights-override-retry - describes how to change the default retry + policies. - @ref contactcenterinsights-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/contact-center/insights/docs -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/contactcenterinsights/doc/override-retry-policies.dox b/google/cloud/contactcenterinsights/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..a476365b6fe46 --- /dev/null +++ b/google/cloud/contactcenterinsights/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page contactcenterinsights-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 contactcenterinsights-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. + +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 contactcenterinsights-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 contactcenterinsights-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 contactcenterinsights-override-retry-example Example + + +For example, this will override the retry policies for `contactcenterinsights_v1::ContactCenterInsightsClient`: + +@snippet contact_center_insights_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet contact_center_insights_client_samples.cc custom-idempotency-policy + + + + +@section contactcenterinsights-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 + +*/ + +// + +/*! @page contactcenterinsights_v1::ContactCenterInsightsClient-retry-snippet Override contactcenterinsights_v1::ContactCenterInsightsClient Retry Policies + +This shows how to override the retry policies for contactcenterinsights_v1::ContactCenterInsightsClient: + +@snippet google/cloud/contactcenterinsights/v1/samples/contact_center_insights_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/contactcenterinsights/v1/samples/contact_center_insights_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/container/doc/main.dox b/google/cloud/container/doc/main.dox index c21ccbe640549..68a54651e4b5e 100644 --- a/google/cloud/container/doc/main.dox +++ b/google/cloud/container/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,9 +36,10 @@ can override the default policies. endpoint. - @ref container-override-authentication - describes how to change the authentication credentials used by the library. +- @ref container-override-retry - describes how to change the default retry + policies. - @ref container-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/kubernetes-engine/docs/ -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/container/doc/override-retry-policies.dox b/google/cloud/container/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..667fcf7242c4b --- /dev/null +++ b/google/cloud/container/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page container-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 container-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. + +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 container-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 container-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 container-override-retry-example Example + + +For example, this will override the retry policies for `container_v1::ClusterManagerClient`: + +@snippet cluster_manager_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet cluster_manager_client_samples.cc custom-idempotency-policy + + + + +@section container-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 + +*/ + +// + +/*! @page container_v1::ClusterManagerClient-retry-snippet Override container_v1::ClusterManagerClient Retry Policies + +This shows how to override the retry policies for container_v1::ClusterManagerClient: + +@snippet google/cloud/container/v1/samples/cluster_manager_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/container/v1/samples/cluster_manager_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/containeranalysis/doc/main.dox b/google/cloud/containeranalysis/doc/main.dox index 2f53c475764ab..0ffba8539e997 100644 --- a/google/cloud/containeranalysis/doc/main.dox +++ b/google/cloud/containeranalysis/doc/main.dox @@ -36,12 +36,6 @@ application. - [\c containeranalysis_v1::GrafeasClient](@ref google::cloud::containeranalysis_v1::GrafeasClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -49,9 +43,10 @@ can override the default policies. endpoint. - @ref containeranalysis-override-authentication - describes how to change the authentication credentials used by the library. +- @ref containeranalysis-override-retry - describes how to change the default retry + policies. - @ref containeranalysis-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/container-analysis -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/containeranalysis/doc/override-retry-policies.dox b/google/cloud/containeranalysis/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..d45e2530416b8 --- /dev/null +++ b/google/cloud/containeranalysis/doc/override-retry-policies.dox @@ -0,0 +1,122 @@ +/*! + +@page containeranalysis-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 containeranalysis-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. + +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 containeranalysis-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 containeranalysis-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 containeranalysis-override-retry-example Example + + +For example, this will override the retry policies for `containeranalysis_v1::ContainerAnalysisClient`: + +@snippet container_analysis_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet container_analysis_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c containeranalysis_v1::ContainerAnalysisClient](@ref containeranalysis_v1::ContainerAnalysisClient-retry-snippet) +- [\c containeranalysis_v1::GrafeasClient](@ref containeranalysis_v1::GrafeasClient-retry-snippet) + + + +@section containeranalysis-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 + +*/ + +// + +/*! @page containeranalysis_v1::ContainerAnalysisClient-retry-snippet Override containeranalysis_v1::ContainerAnalysisClient Retry Policies + +This shows how to override the retry policies for containeranalysis_v1::ContainerAnalysisClient: + +@snippet google/cloud/containeranalysis/v1/samples/container_analysis_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/containeranalysis/v1/samples/container_analysis_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page containeranalysis_v1::GrafeasClient-retry-snippet Override containeranalysis_v1::GrafeasClient Retry Policies + +This shows how to override the retry policies for containeranalysis_v1::GrafeasClient: + +@snippet google/cloud/containeranalysis/v1/samples/grafeas_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/containeranalysis/v1/samples/grafeas_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/contentwarehouse/doc/main.dox b/google/cloud/contentwarehouse/doc/main.dox index dc05d14d798fb..b19235d709220 100644 --- a/google/cloud/contentwarehouse/doc/main.dox +++ b/google/cloud/contentwarehouse/doc/main.dox @@ -40,12 +40,6 @@ application. - [\c contentwarehouse_v1::SynonymSetServiceClient](@ref google::cloud::contentwarehouse_v1::SynonymSetServiceClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -53,10 +47,11 @@ can override the default policies. endpoint. - @ref contentwarehouse-override-authentication - describes how to change the authentication credentials used by the library. +- @ref contentwarehouse-override-retry - describes how to change the default retry + policies. - @ref contentwarehouse-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/document-warehouse/ -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/contentwarehouse/doc/override-retry-policies.dox b/google/cloud/contentwarehouse/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..e85db47037db7 --- /dev/null +++ b/google/cloud/contentwarehouse/doc/override-retry-policies.dox @@ -0,0 +1,161 @@ +/*! + +@page contentwarehouse-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 contentwarehouse-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. + +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 contentwarehouse-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 contentwarehouse-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 contentwarehouse-override-retry-example Example + + +For example, this will override the retry policies for `contentwarehouse_v1::DocumentServiceClient`: + +@snippet document_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet document_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c contentwarehouse_v1::DocumentServiceClient](@ref contentwarehouse_v1::DocumentServiceClient-retry-snippet) +- [\c contentwarehouse_v1::DocumentLinkServiceClient](@ref contentwarehouse_v1::DocumentLinkServiceClient-retry-snippet) +- [\c contentwarehouse_v1::DocumentSchemaServiceClient](@ref contentwarehouse_v1::DocumentSchemaServiceClient-retry-snippet) +- [\c contentwarehouse_v1::RuleSetServiceClient](@ref contentwarehouse_v1::RuleSetServiceClient-retry-snippet) +- [\c contentwarehouse_v1::SynonymSetServiceClient](@ref contentwarehouse_v1::SynonymSetServiceClient-retry-snippet) + + + +@section contentwarehouse-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 + +*/ + +// + +/*! @page contentwarehouse_v1::DocumentServiceClient-retry-snippet Override contentwarehouse_v1::DocumentServiceClient Retry Policies + +This shows how to override the retry policies for contentwarehouse_v1::DocumentServiceClient: + +@snippet google/cloud/contentwarehouse/v1/samples/document_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/contentwarehouse/v1/samples/document_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page contentwarehouse_v1::DocumentLinkServiceClient-retry-snippet Override contentwarehouse_v1::DocumentLinkServiceClient Retry Policies + +This shows how to override the retry policies for contentwarehouse_v1::DocumentLinkServiceClient: + +@snippet google/cloud/contentwarehouse/v1/samples/document_link_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/contentwarehouse/v1/samples/document_link_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page contentwarehouse_v1::DocumentSchemaServiceClient-retry-snippet Override contentwarehouse_v1::DocumentSchemaServiceClient Retry Policies + +This shows how to override the retry policies for contentwarehouse_v1::DocumentSchemaServiceClient: + +@snippet google/cloud/contentwarehouse/v1/samples/document_schema_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/contentwarehouse/v1/samples/document_schema_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page contentwarehouse_v1::RuleSetServiceClient-retry-snippet Override contentwarehouse_v1::RuleSetServiceClient Retry Policies + +This shows how to override the retry policies for contentwarehouse_v1::RuleSetServiceClient: + +@snippet google/cloud/contentwarehouse/v1/samples/rule_set_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/contentwarehouse/v1/samples/rule_set_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page contentwarehouse_v1::SynonymSetServiceClient-retry-snippet Override contentwarehouse_v1::SynonymSetServiceClient Retry Policies + +This shows how to override the retry policies for contentwarehouse_v1::SynonymSetServiceClient: + +@snippet google/cloud/contentwarehouse/v1/samples/synonym_set_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/contentwarehouse/v1/samples/synonym_set_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/datacatalog/doc/main.dox b/google/cloud/datacatalog/doc/main.dox index ec39312f39079..8be4054a8b8fc 100644 --- a/google/cloud/datacatalog/doc/main.dox +++ b/google/cloud/datacatalog/doc/main.dox @@ -36,12 +36,6 @@ application. - [\c datacatalog_v1::PolicyTagManagerSerializationClient](@ref google::cloud::datacatalog_v1::PolicyTagManagerSerializationClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -49,9 +43,10 @@ can override the default policies. endpoint. - @ref datacatalog-override-authentication - describes how to change the authentication credentials used by the library. +- @ref datacatalog-override-retry - describes how to change the default retry + policies. - @ref datacatalog-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/data-catalog -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/datacatalog/doc/override-retry-policies.dox b/google/cloud/datacatalog/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..f7b8a83db2dfe --- /dev/null +++ b/google/cloud/datacatalog/doc/override-retry-policies.dox @@ -0,0 +1,148 @@ +/*! + +@page datacatalog-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 datacatalog-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. + +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 datacatalog-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 datacatalog-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 datacatalog-override-retry-example Example + + +For example, this will override the retry policies for `datacatalog_lineage_v1::LineageClient`: + +@snippet lineage_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet lineage_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c datacatalog_lineage_v1::LineageClient](@ref datacatalog_lineage_v1::LineageClient-retry-snippet) +- [\c datacatalog_v1::DataCatalogClient](@ref datacatalog_v1::DataCatalogClient-retry-snippet) +- [\c datacatalog_v1::PolicyTagManagerClient](@ref datacatalog_v1::PolicyTagManagerClient-retry-snippet) +- [\c datacatalog_v1::PolicyTagManagerSerializationClient](@ref datacatalog_v1::PolicyTagManagerSerializationClient-retry-snippet) + + + +@section datacatalog-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 + +*/ + +// + +/*! @page datacatalog_lineage_v1::LineageClient-retry-snippet Override datacatalog_lineage_v1::LineageClient Retry Policies + +This shows how to override the retry policies for datacatalog_lineage_v1::LineageClient: + +@snippet google/cloud/datacatalog/lineage/v1/samples/lineage_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/datacatalog/lineage/v1/samples/lineage_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page datacatalog_v1::DataCatalogClient-retry-snippet Override datacatalog_v1::DataCatalogClient Retry Policies + +This shows how to override the retry policies for datacatalog_v1::DataCatalogClient: + +@snippet google/cloud/datacatalog/v1/samples/data_catalog_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/datacatalog/v1/samples/data_catalog_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page datacatalog_v1::PolicyTagManagerClient-retry-snippet Override datacatalog_v1::PolicyTagManagerClient Retry Policies + +This shows how to override the retry policies for datacatalog_v1::PolicyTagManagerClient: + +@snippet google/cloud/datacatalog/v1/samples/policy_tag_manager_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/datacatalog/v1/samples/policy_tag_manager_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page datacatalog_v1::PolicyTagManagerSerializationClient-retry-snippet Override datacatalog_v1::PolicyTagManagerSerializationClient Retry Policies + +This shows how to override the retry policies for datacatalog_v1::PolicyTagManagerSerializationClient: + +@snippet google/cloud/datacatalog/v1/samples/policy_tag_manager_serialization_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/datacatalog/v1/samples/policy_tag_manager_serialization_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/datafusion/doc/main.dox b/google/cloud/datafusion/doc/main.dox index dd4dad45e82f6..cd26c0220bff1 100644 --- a/google/cloud/datafusion/doc/main.dox +++ b/google/cloud/datafusion/doc/main.dox @@ -31,12 +31,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -44,10 +38,11 @@ can override the default policies. endpoint. - @ref datafusion-override-authentication - describes how to change the authentication credentials used by the library. +- @ref datafusion-override-retry - describes how to change the default retry + policies. - @ref datafusion-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/data-fusion -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/datafusion/doc/override-retry-policies.dox b/google/cloud/datafusion/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..19faf6bf78088 --- /dev/null +++ b/google/cloud/datafusion/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page datafusion-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 datafusion-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. + +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 datafusion-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 datafusion-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 datafusion-override-retry-example Example + + +For example, this will override the retry policies for `datafusion_v1::DataFusionClient`: + +@snippet data_fusion_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet data_fusion_client_samples.cc custom-idempotency-policy + + + + +@section datafusion-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 + +*/ + +// + +/*! @page datafusion_v1::DataFusionClient-retry-snippet Override datafusion_v1::DataFusionClient Retry Policies + +This shows how to override the retry policies for datafusion_v1::DataFusionClient: + +@snippet google/cloud/datafusion/v1/samples/data_fusion_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/datafusion/v1/samples/data_fusion_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/datamigration/doc/main.dox b/google/cloud/datamigration/doc/main.dox index 892254dfcb415..1c57bac55a320 100644 --- a/google/cloud/datamigration/doc/main.dox +++ b/google/cloud/datamigration/doc/main.dox @@ -28,12 +28,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -41,9 +35,10 @@ can override the default policies. endpoint. - @ref datamigration-override-authentication - describes how to change the authentication credentials used by the library. +- @ref datamigration-override-retry - describes how to change the default retry + policies. - @ref datamigration-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/database-migration -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/datamigration/doc/override-retry-policies.dox b/google/cloud/datamigration/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..15201553af073 --- /dev/null +++ b/google/cloud/datamigration/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page datamigration-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 datamigration-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. + +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 datamigration-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 datamigration-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 datamigration-override-retry-example Example + + +For example, this will override the retry policies for `datamigration_v1::DataMigrationServiceClient`: + +@snippet data_migration_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet data_migration_client_samples.cc custom-idempotency-policy + + + + +@section datamigration-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 + +*/ + +// + +/*! @page datamigration_v1::DataMigrationServiceClient-retry-snippet Override datamigration_v1::DataMigrationServiceClient Retry Policies + +This shows how to override the retry policies for datamigration_v1::DataMigrationServiceClient: + +@snippet google/cloud/datamigration/v1/samples/data_migration_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/datamigration/v1/samples/data_migration_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/dataplex/doc/main.dox b/google/cloud/dataplex/doc/main.dox index adb28764578d2..4aa3895f4ae13 100644 --- a/google/cloud/dataplex/doc/main.dox +++ b/google/cloud/dataplex/doc/main.dox @@ -36,12 +36,6 @@ application. - [\c dataplex_v1::MetadataServiceClient](@ref google::cloud::dataplex_v1::MetadataServiceClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -49,9 +43,10 @@ can override the default policies. endpoint. - @ref dataplex-override-authentication - describes how to change the authentication credentials used by the library. +- @ref dataplex-override-retry - describes how to change the default retry + policies. - @ref dataplex-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/dataplex -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/dataplex/doc/override-retry-policies.dox b/google/cloud/dataplex/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..0f22b46d4cdbc --- /dev/null +++ b/google/cloud/dataplex/doc/override-retry-policies.dox @@ -0,0 +1,135 @@ +/*! + +@page dataplex-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 dataplex-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. + +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 dataplex-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 dataplex-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 dataplex-override-retry-example Example + + +For example, this will override the retry policies for `dataplex_v1::ContentServiceClient`: + +@snippet content_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet content_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c dataplex_v1::ContentServiceClient](@ref dataplex_v1::ContentServiceClient-retry-snippet) +- [\c dataplex_v1::DataplexServiceClient](@ref dataplex_v1::DataplexServiceClient-retry-snippet) +- [\c dataplex_v1::MetadataServiceClient](@ref dataplex_v1::MetadataServiceClient-retry-snippet) + + + +@section dataplex-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 + +*/ + +// + +/*! @page dataplex_v1::ContentServiceClient-retry-snippet Override dataplex_v1::ContentServiceClient Retry Policies + +This shows how to override the retry policies for dataplex_v1::ContentServiceClient: + +@snippet google/cloud/dataplex/v1/samples/content_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/dataplex/v1/samples/content_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page dataplex_v1::DataplexServiceClient-retry-snippet Override dataplex_v1::DataplexServiceClient Retry Policies + +This shows how to override the retry policies for dataplex_v1::DataplexServiceClient: + +@snippet google/cloud/dataplex/v1/samples/dataplex_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/dataplex/v1/samples/dataplex_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page dataplex_v1::MetadataServiceClient-retry-snippet Override dataplex_v1::MetadataServiceClient Retry Policies + +This shows how to override the retry policies for dataplex_v1::MetadataServiceClient: + +@snippet google/cloud/dataplex/v1/samples/metadata_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/dataplex/v1/samples/metadata_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/dataproc/doc/main.dox b/google/cloud/dataproc/doc/main.dox index ef77e433832f6..c241f4f4d447d 100644 --- a/google/cloud/dataproc/doc/main.dox +++ b/google/cloud/dataproc/doc/main.dox @@ -40,12 +40,6 @@ application. - [\c dataproc_v1::WorkflowTemplateServiceClient](@ref google::cloud::dataproc_v1::WorkflowTemplateServiceClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -53,9 +47,10 @@ can override the default policies. endpoint. - @ref dataproc-override-authentication - describes how to change the authentication credentials used by the library. +- @ref dataproc-override-retry - describes how to change the default retry + policies. - @ref dataproc-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/dataproc -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/dataproc/doc/override-retry-policies.dox b/google/cloud/dataproc/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..1bc6be4b289bf --- /dev/null +++ b/google/cloud/dataproc/doc/override-retry-policies.dox @@ -0,0 +1,161 @@ +/*! + +@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 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. + +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 + + +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::WorkflowTemplateServiceClient](@ref dataproc_v1::WorkflowTemplateServiceClient-retry-snippet) + + + +@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 + +*/ + +// + +/*! @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::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 + +*/ +// diff --git a/google/cloud/datastream/doc/main.dox b/google/cloud/datastream/doc/main.dox index 6de5317b9afd6..32548e06561a5 100644 --- a/google/cloud/datastream/doc/main.dox +++ b/google/cloud/datastream/doc/main.dox @@ -31,12 +31,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -44,9 +38,10 @@ can override the default policies. endpoint. - @ref datastream-override-authentication - describes how to change the authentication credentials used by the library. +- @ref datastream-override-retry - describes how to change the default retry + policies. - @ref datastream-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/datastream -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/datastream/doc/override-retry-policies.dox b/google/cloud/datastream/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..8865d12313897 --- /dev/null +++ b/google/cloud/datastream/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page datastream-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 datastream-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. + +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 datastream-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 datastream-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 datastream-override-retry-example Example + + +For example, this will override the retry policies for `datastream_v1::DatastreamClient`: + +@snippet datastream_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet datastream_client_samples.cc custom-idempotency-policy + + + + +@section datastream-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 + +*/ + +// + +/*! @page datastream_v1::DatastreamClient-retry-snippet Override datastream_v1::DatastreamClient Retry Policies + +This shows how to override the retry policies for datastream_v1::DatastreamClient: + +@snippet google/cloud/datastream/v1/samples/datastream_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/datastream/v1/samples/datastream_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/deploy/doc/main.dox b/google/cloud/deploy/doc/main.dox index 1b777a1f28a76..16b13cc334959 100644 --- a/google/cloud/deploy/doc/main.dox +++ b/google/cloud/deploy/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,9 +36,10 @@ can override the default policies. endpoint. - @ref deploy-override-authentication - describes how to change the authentication credentials used by the library. +- @ref deploy-override-retry - describes how to change the default retry + policies. - @ref deploy-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/deploy -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/deploy/doc/override-retry-policies.dox b/google/cloud/deploy/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..b42e0b058eaae --- /dev/null +++ b/google/cloud/deploy/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page deploy-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 deploy-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. + +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 deploy-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 deploy-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 deploy-override-retry-example Example + + +For example, this will override the retry policies for `deploy_v1::CloudDeployClient`: + +@snippet cloud_deploy_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet cloud_deploy_client_samples.cc custom-idempotency-policy + + + + +@section deploy-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 + +*/ + +// + +/*! @page deploy_v1::CloudDeployClient-retry-snippet Override deploy_v1::CloudDeployClient Retry Policies + +This shows how to override the retry policies for deploy_v1::CloudDeployClient: + +@snippet google/cloud/deploy/v1/samples/cloud_deploy_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/deploy/v1/samples/cloud_deploy_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/dialogflow_cx/doc/main.dox b/google/cloud/dialogflow_cx/doc/main.dox index 631941ba5b3b3..e698cc650e031 100644 --- a/google/cloud/dialogflow_cx/doc/main.dox +++ b/google/cloud/dialogflow_cx/doc/main.dox @@ -51,12 +51,6 @@ application. - [\c dialogflow_cx::WebhooksClient](@ref google::cloud::dialogflow_cx::WebhooksClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -64,9 +58,10 @@ can override the default policies. endpoint. - @ref dialogflow_cx-override-authentication - describes how to change the authentication credentials used by the library. +- @ref dialogflow_cx-override-retry - describes how to change the default retry + policies. - @ref dialogflow_cx-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/dialogflow/cx/docs -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/dialogflow_cx/doc/override-retry-policies.dox b/google/cloud/dialogflow_cx/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..cda9aac03eec7 --- /dev/null +++ b/google/cloud/dialogflow_cx/doc/override-retry-policies.dox @@ -0,0 +1,304 @@ +/*! + +@page dialogflow_cx-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_cx-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. + +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_cx-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_cx-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_cx-override-retry-example Example + + +For example, this will override the retry policies for `dialogflow_cx::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 + + +Follow these links to find examples for other \c *Client classes: + +- [\c dialogflow_cx::AgentsClient](@ref dialogflow_cx::AgentsClient-retry-snippet) +- [\c dialogflow_cx::ChangelogsClient](@ref dialogflow_cx::ChangelogsClient-retry-snippet) +- [\c dialogflow_cx::DeploymentsClient](@ref dialogflow_cx::DeploymentsClient-retry-snippet) +- [\c dialogflow_cx::EntityTypesClient](@ref dialogflow_cx::EntityTypesClient-retry-snippet) +- [\c dialogflow_cx::EnvironmentsClient](@ref dialogflow_cx::EnvironmentsClient-retry-snippet) +- [\c dialogflow_cx::ExperimentsClient](@ref dialogflow_cx::ExperimentsClient-retry-snippet) +- [\c dialogflow_cx::FlowsClient](@ref dialogflow_cx::FlowsClient-retry-snippet) +- [\c dialogflow_cx::IntentsClient](@ref dialogflow_cx::IntentsClient-retry-snippet) +- [\c dialogflow_cx::PagesClient](@ref dialogflow_cx::PagesClient-retry-snippet) +- [\c dialogflow_cx::SecuritySettingsServiceClient](@ref dialogflow_cx::SecuritySettingsServiceClient-retry-snippet) +- [\c dialogflow_cx::SessionEntityTypesClient](@ref dialogflow_cx::SessionEntityTypesClient-retry-snippet) +- [\c dialogflow_cx::SessionsClient](@ref dialogflow_cx::SessionsClient-retry-snippet) +- [\c dialogflow_cx::TestCasesClient](@ref dialogflow_cx::TestCasesClient-retry-snippet) +- [\c dialogflow_cx::TransitionRouteGroupsClient](@ref dialogflow_cx::TransitionRouteGroupsClient-retry-snippet) +- [\c dialogflow_cx::VersionsClient](@ref dialogflow_cx::VersionsClient-retry-snippet) +- [\c dialogflow_cx::WebhooksClient](@ref dialogflow_cx::WebhooksClient-retry-snippet) + + + +@section dialogflow_cx-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 + +*/ + +// + +/*! @page dialogflow_cx::AgentsClient-retry-snippet Override dialogflow_cx::AgentsClient Retry Policies + +This shows how to override the retry policies for dialogflow_cx::AgentsClient: + +@snippet google/cloud/dialogflow_cx/samples/agents_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/dialogflow_cx/samples/agents_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page dialogflow_cx::ChangelogsClient-retry-snippet Override dialogflow_cx::ChangelogsClient Retry Policies + +This shows how to override the retry policies for dialogflow_cx::ChangelogsClient: + +@snippet google/cloud/dialogflow_cx/samples/changelogs_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/dialogflow_cx/samples/changelogs_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page dialogflow_cx::DeploymentsClient-retry-snippet Override dialogflow_cx::DeploymentsClient Retry Policies + +This shows how to override the retry policies for dialogflow_cx::DeploymentsClient: + +@snippet google/cloud/dialogflow_cx/samples/deployments_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/dialogflow_cx/samples/deployments_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page dialogflow_cx::EntityTypesClient-retry-snippet Override dialogflow_cx::EntityTypesClient Retry Policies + +This shows how to override the retry policies for dialogflow_cx::EntityTypesClient: + +@snippet google/cloud/dialogflow_cx/samples/entity_types_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/dialogflow_cx/samples/entity_types_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page dialogflow_cx::EnvironmentsClient-retry-snippet Override dialogflow_cx::EnvironmentsClient Retry Policies + +This shows how to override the retry policies for dialogflow_cx::EnvironmentsClient: + +@snippet google/cloud/dialogflow_cx/samples/environments_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/dialogflow_cx/samples/environments_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page dialogflow_cx::ExperimentsClient-retry-snippet Override dialogflow_cx::ExperimentsClient Retry Policies + +This shows how to override the retry policies for dialogflow_cx::ExperimentsClient: + +@snippet google/cloud/dialogflow_cx/samples/experiments_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/dialogflow_cx/samples/experiments_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page dialogflow_cx::FlowsClient-retry-snippet Override dialogflow_cx::FlowsClient Retry Policies + +This shows how to override the retry policies for dialogflow_cx::FlowsClient: + +@snippet google/cloud/dialogflow_cx/samples/flows_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/dialogflow_cx/samples/flows_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page dialogflow_cx::IntentsClient-retry-snippet Override dialogflow_cx::IntentsClient Retry Policies + +This shows how to override the retry policies for dialogflow_cx::IntentsClient: + +@snippet google/cloud/dialogflow_cx/samples/intents_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/dialogflow_cx/samples/intents_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page dialogflow_cx::PagesClient-retry-snippet Override dialogflow_cx::PagesClient Retry Policies + +This shows how to override the retry policies for dialogflow_cx::PagesClient: + +@snippet google/cloud/dialogflow_cx/samples/pages_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/dialogflow_cx/samples/pages_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page dialogflow_cx::SecuritySettingsServiceClient-retry-snippet Override dialogflow_cx::SecuritySettingsServiceClient Retry Policies + +This shows how to override the retry policies for dialogflow_cx::SecuritySettingsServiceClient: + +@snippet google/cloud/dialogflow_cx/samples/security_settings_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/dialogflow_cx/samples/security_settings_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page dialogflow_cx::SessionEntityTypesClient-retry-snippet Override dialogflow_cx::SessionEntityTypesClient Retry Policies + +This shows how to override the retry policies for dialogflow_cx::SessionEntityTypesClient: + +@snippet google/cloud/dialogflow_cx/samples/session_entity_types_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/dialogflow_cx/samples/session_entity_types_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page dialogflow_cx::SessionsClient-retry-snippet Override dialogflow_cx::SessionsClient Retry Policies + +This shows how to override the retry policies for dialogflow_cx::SessionsClient: + +@snippet google/cloud/dialogflow_cx/samples/sessions_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/dialogflow_cx/samples/sessions_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page dialogflow_cx::TestCasesClient-retry-snippet Override dialogflow_cx::TestCasesClient Retry Policies + +This shows how to override the retry policies for dialogflow_cx::TestCasesClient: + +@snippet google/cloud/dialogflow_cx/samples/test_cases_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/dialogflow_cx/samples/test_cases_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page dialogflow_cx::TransitionRouteGroupsClient-retry-snippet Override dialogflow_cx::TransitionRouteGroupsClient Retry Policies + +This shows how to override the retry policies for dialogflow_cx::TransitionRouteGroupsClient: + +@snippet google/cloud/dialogflow_cx/samples/transition_route_groups_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/dialogflow_cx/samples/transition_route_groups_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page dialogflow_cx::VersionsClient-retry-snippet Override dialogflow_cx::VersionsClient Retry Policies + +This shows how to override the retry policies for dialogflow_cx::VersionsClient: + +@snippet google/cloud/dialogflow_cx/samples/versions_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/dialogflow_cx/samples/versions_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page dialogflow_cx::WebhooksClient-retry-snippet Override dialogflow_cx::WebhooksClient Retry Policies + +This shows how to override the retry policies for dialogflow_cx::WebhooksClient: + +@snippet google/cloud/dialogflow_cx/samples/webhooks_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/dialogflow_cx/samples/webhooks_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/dialogflow_es/doc/main.dox b/google/cloud/dialogflow_es/doc/main.dox index 458148b5af286..9d7eb7d8d52d1 100644 --- a/google/cloud/dialogflow_es/doc/main.dox +++ b/google/cloud/dialogflow_es/doc/main.dox @@ -52,12 +52,6 @@ application. - [\c dialogflow_es::VersionsClient](@ref google::cloud::dialogflow_es::VersionsClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -65,9 +59,10 @@ can override the default policies. endpoint. - @ref dialogflow_es-override-authentication - describes how to change the authentication credentials used by the library. +- @ref dialogflow_es-override-retry - describes how to change the default retry + policies. - @ref dialogflow_es-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/dialogflow/es/docs -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/dialogflow_es/doc/override-retry-policies.dox b/google/cloud/dialogflow_es/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..63e2032f81ac2 --- /dev/null +++ b/google/cloud/dialogflow_es/doc/override-retry-policies.dox @@ -0,0 +1,317 @@ +/*! + +@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 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. + +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 + + +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 + + +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::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::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) + + + +@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 + +*/ + +// + +/*! @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::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::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 + +*/ +// diff --git a/google/cloud/dlp/doc/main.dox b/google/cloud/dlp/doc/main.dox index fd35eed8a8266..4b2864a962d4f 100644 --- a/google/cloud/dlp/doc/main.dox +++ b/google/cloud/dlp/doc/main.dox @@ -31,12 +31,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -44,9 +38,10 @@ can override the default policies. endpoint. - @ref dlp-override-authentication - describes how to change the authentication credentials used by the library. +- @ref dlp-override-retry - describes how to change the default retry + policies. - @ref dlp-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/dlp/docs/ -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/dlp/doc/override-retry-policies.dox b/google/cloud/dlp/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..d69864d9121d6 --- /dev/null +++ b/google/cloud/dlp/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page dlp-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 dlp-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. + +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 dlp-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 dlp-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 dlp-override-retry-example Example + + +For example, this will override the retry policies for `dlp_v2::DlpServiceClient`: + +@snippet dlp_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet dlp_client_samples.cc custom-idempotency-policy + + + + +@section dlp-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 + +*/ + +// + +/*! @page dlp_v2::DlpServiceClient-retry-snippet Override dlp_v2::DlpServiceClient Retry Policies + +This shows how to override the retry policies for dlp_v2::DlpServiceClient: + +@snippet google/cloud/dlp/v2/samples/dlp_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/dlp/v2/samples/dlp_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/documentai/doc/main.dox b/google/cloud/documentai/doc/main.dox index 89c8b426d8f15..f0324f4c8b4a7 100644 --- a/google/cloud/documentai/doc/main.dox +++ b/google/cloud/documentai/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,9 +36,10 @@ can override the default policies. endpoint. - @ref documentai-override-authentication - describes how to change the authentication credentials used by the library. +- @ref documentai-override-retry - describes how to change the default retry + policies. - @ref documentai-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/document-ai -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/documentai/doc/override-retry-policies.dox b/google/cloud/documentai/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..5eb56a77f07eb --- /dev/null +++ b/google/cloud/documentai/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page documentai-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 documentai-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. + +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 documentai-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 documentai-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 documentai-override-retry-example Example + + +For example, this will override the retry policies for `documentai_v1::DocumentProcessorServiceClient`: + +@snippet document_processor_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet document_processor_client_samples.cc custom-idempotency-policy + + + + +@section documentai-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 + +*/ + +// + +/*! @page documentai_v1::DocumentProcessorServiceClient-retry-snippet Override documentai_v1::DocumentProcessorServiceClient Retry Policies + +This shows how to override the retry policies for documentai_v1::DocumentProcessorServiceClient: + +@snippet google/cloud/documentai/v1/samples/document_processor_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/documentai/v1/samples/document_processor_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/domains/doc/main.dox b/google/cloud/domains/doc/main.dox index 7a35ffe230fb3..74252a7522c10 100644 --- a/google/cloud/domains/doc/main.dox +++ b/google/cloud/domains/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,10 +36,11 @@ can override the default policies. endpoint. - @ref domains-override-authentication - describes how to change the authentication credentials used by the library. +- @ref domains-override-retry - describes how to change the default retry + policies. - @ref domains-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/domains -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/domains/doc/override-retry-policies.dox b/google/cloud/domains/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..049a04ec12617 --- /dev/null +++ b/google/cloud/domains/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page domains-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 domains-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. + +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 domains-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 domains-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 domains-override-retry-example Example + + +For example, this will override the retry policies for `domains_v1::DomainsClient`: + +@snippet domains_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet domains_client_samples.cc custom-idempotency-policy + + + + +@section domains-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 + +*/ + +// + +/*! @page domains_v1::DomainsClient-retry-snippet Override domains_v1::DomainsClient Retry Policies + +This shows how to override the retry policies for domains_v1::DomainsClient: + +@snippet google/cloud/domains/v1/samples/domains_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/domains/v1/samples/domains_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/edgecontainer/doc/main.dox b/google/cloud/edgecontainer/doc/main.dox index f3f4289a2313f..d777811f0cbb0 100644 --- a/google/cloud/edgecontainer/doc/main.dox +++ b/google/cloud/edgecontainer/doc/main.dox @@ -31,12 +31,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -44,9 +38,10 @@ can override the default policies. endpoint. - @ref edgecontainer-override-authentication - describes how to change the authentication credentials used by the library. +- @ref edgecontainer-override-retry - describes how to change the default retry + policies. - @ref edgecontainer-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/distributed-cloud/edge/latest/docs -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/edgecontainer/doc/override-retry-policies.dox b/google/cloud/edgecontainer/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..410f0a3804aaa --- /dev/null +++ b/google/cloud/edgecontainer/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page edgecontainer-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 edgecontainer-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. + +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 edgecontainer-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 edgecontainer-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 edgecontainer-override-retry-example Example + + +For example, this will override the retry policies for `edgecontainer_v1::EdgeContainerClient`: + +@snippet edge_container_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet edge_container_client_samples.cc custom-idempotency-policy + + + + +@section edgecontainer-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 + +*/ + +// + +/*! @page edgecontainer_v1::EdgeContainerClient-retry-snippet Override edgecontainer_v1::EdgeContainerClient Retry Policies + +This shows how to override the retry policies for edgecontainer_v1::EdgeContainerClient: + +@snippet google/cloud/edgecontainer/v1/samples/edge_container_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/edgecontainer/v1/samples/edge_container_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/essentialcontacts/doc/main.dox b/google/cloud/essentialcontacts/doc/main.dox index 01cfdca3c2db3..089608eb2d977 100644 --- a/google/cloud/essentialcontacts/doc/main.dox +++ b/google/cloud/essentialcontacts/doc/main.dox @@ -32,12 +32,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -45,10 +39,11 @@ can override the default policies. endpoint. - @ref essentialcontacts-override-authentication - describes how to change the authentication credentials used by the library. +- @ref essentialcontacts-override-retry - describes how to change the default retry + policies. - @ref essentialcontacts-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/essentialcontacts -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/essentialcontacts/doc/override-retry-policies.dox b/google/cloud/essentialcontacts/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..5b388889a5df9 --- /dev/null +++ b/google/cloud/essentialcontacts/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page essentialcontacts-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 essentialcontacts-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. + +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 essentialcontacts-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 essentialcontacts-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 essentialcontacts-override-retry-example Example + + +For example, this will override the retry policies for `essentialcontacts_v1::EssentialContactsServiceClient`: + +@snippet essential_contacts_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet essential_contacts_client_samples.cc custom-idempotency-policy + + + + +@section essentialcontacts-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 + +*/ + +// + +/*! @page essentialcontacts_v1::EssentialContactsServiceClient-retry-snippet Override essentialcontacts_v1::EssentialContactsServiceClient Retry Policies + +This shows how to override the retry policies for essentialcontacts_v1::EssentialContactsServiceClient: + +@snippet google/cloud/essentialcontacts/v1/samples/essential_contacts_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/essentialcontacts/v1/samples/essential_contacts_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/eventarc/doc/main.dox b/google/cloud/eventarc/doc/main.dox index 6fc444bf00cb4..2192d333c4130 100644 --- a/google/cloud/eventarc/doc/main.dox +++ b/google/cloud/eventarc/doc/main.dox @@ -34,12 +34,6 @@ application. - [\c eventarc_v1::EventarcClient](@ref google::cloud::eventarc_v1::EventarcClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -47,9 +41,10 @@ can override the default policies. endpoint. - @ref eventarc-override-authentication - describes how to change the authentication credentials used by the library. +- @ref eventarc-override-retry - describes how to change the default retry + policies. - @ref eventarc-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/eventarc -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/eventarc/doc/override-retry-policies.dox b/google/cloud/eventarc/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..0ee89f8fe8f28 --- /dev/null +++ b/google/cloud/eventarc/doc/override-retry-policies.dox @@ -0,0 +1,122 @@ +/*! + +@page eventarc-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 eventarc-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. + +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 eventarc-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 eventarc-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 eventarc-override-retry-example Example + + +For example, this will override the retry policies for `eventarc_publishing_v1::PublisherClient`: + +@snippet publisher_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet publisher_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c eventarc_publishing_v1::PublisherClient](@ref eventarc_publishing_v1::PublisherClient-retry-snippet) +- [\c eventarc_v1::EventarcClient](@ref eventarc_v1::EventarcClient-retry-snippet) + + + +@section eventarc-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 + +*/ + +// + +/*! @page eventarc_publishing_v1::PublisherClient-retry-snippet Override eventarc_publishing_v1::PublisherClient Retry Policies + +This shows how to override the retry policies for eventarc_publishing_v1::PublisherClient: + +@snippet google/cloud/eventarc/publishing/v1/samples/publisher_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/eventarc/publishing/v1/samples/publisher_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page eventarc_v1::EventarcClient-retry-snippet Override eventarc_v1::EventarcClient Retry Policies + +This shows how to override the retry policies for eventarc_v1::EventarcClient: + +@snippet google/cloud/eventarc/v1/samples/eventarc_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/eventarc/v1/samples/eventarc_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/filestore/doc/main.dox b/google/cloud/filestore/doc/main.dox index e9a06bc1c5ddd..51569a10a2406 100644 --- a/google/cloud/filestore/doc/main.dox +++ b/google/cloud/filestore/doc/main.dox @@ -28,12 +28,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -41,9 +35,10 @@ can override the default policies. endpoint. - @ref filestore-override-authentication - describes how to change the authentication credentials used by the library. +- @ref filestore-override-retry - describes how to change the default retry + policies. - @ref filestore-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/filestore -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/filestore/doc/override-retry-policies.dox b/google/cloud/filestore/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..47e71b3b3d610 --- /dev/null +++ b/google/cloud/filestore/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page filestore-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 filestore-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. + +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 filestore-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 filestore-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 filestore-override-retry-example Example + + +For example, this will override the retry policies for `filestore_v1::CloudFilestoreManagerClient`: + +@snippet cloud_filestore_manager_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet cloud_filestore_manager_client_samples.cc custom-idempotency-policy + + + + +@section filestore-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 + +*/ + +// + +/*! @page filestore_v1::CloudFilestoreManagerClient-retry-snippet Override filestore_v1::CloudFilestoreManagerClient Retry Policies + +This shows how to override the retry policies for filestore_v1::CloudFilestoreManagerClient: + +@snippet google/cloud/filestore/v1/samples/cloud_filestore_manager_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/filestore/v1/samples/cloud_filestore_manager_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/functions/doc/main.dox b/google/cloud/functions/doc/main.dox index b89a8eaead6b0..64c1b8792ab6b 100644 --- a/google/cloud/functions/doc/main.dox +++ b/google/cloud/functions/doc/main.dox @@ -30,12 +30,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -43,9 +37,10 @@ can override the default policies. endpoint. - @ref functions-override-authentication - describes how to change the authentication credentials used by the library. +- @ref functions-override-retry - describes how to change the default retry + policies. - @ref functions-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/functions -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/functions/doc/override-retry-policies.dox b/google/cloud/functions/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..732ac372db38d --- /dev/null +++ b/google/cloud/functions/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page functions-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 functions-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. + +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 functions-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 functions-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 functions-override-retry-example Example + + +For example, this will override the retry policies for `functions_v1::CloudFunctionsServiceClient`: + +@snippet cloud_functions_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet cloud_functions_client_samples.cc custom-idempotency-policy + + + + +@section functions-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 + +*/ + +// + +/*! @page functions_v1::CloudFunctionsServiceClient-retry-snippet Override functions_v1::CloudFunctionsServiceClient Retry Policies + +This shows how to override the retry policies for functions_v1::CloudFunctionsServiceClient: + +@snippet google/cloud/functions/v1/samples/cloud_functions_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/functions/v1/samples/cloud_functions_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/gameservices/doc/main.dox b/google/cloud/gameservices/doc/main.dox index 851ba7fd2e17d..2c1c4abb03a79 100644 --- a/google/cloud/gameservices/doc/main.dox +++ b/google/cloud/gameservices/doc/main.dox @@ -37,12 +37,6 @@ application. - [\c gameservices_v1::RealmsServiceClient](@ref google::cloud::gameservices_v1::RealmsServiceClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -50,9 +44,10 @@ can override the default policies. endpoint. - @ref gameservices-override-authentication - describes how to change the authentication credentials used by the library. +- @ref gameservices-override-retry - describes how to change the default retry + policies. - @ref gameservices-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/game-servers/docs/ -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/gameservices/doc/override-retry-policies.dox b/google/cloud/gameservices/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..a2bd7656efd15 --- /dev/null +++ b/google/cloud/gameservices/doc/override-retry-policies.dox @@ -0,0 +1,148 @@ +/*! + +@page gameservices-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 gameservices-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. + +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 gameservices-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 gameservices-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 gameservices-override-retry-example Example + + +For example, this will override the retry policies for `gameservices_v1::GameServerClustersServiceClient`: + +@snippet game_server_clusters_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet game_server_clusters_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c gameservices_v1::GameServerClustersServiceClient](@ref gameservices_v1::GameServerClustersServiceClient-retry-snippet) +- [\c gameservices_v1::GameServerConfigsServiceClient](@ref gameservices_v1::GameServerConfigsServiceClient-retry-snippet) +- [\c gameservices_v1::GameServerDeploymentsServiceClient](@ref gameservices_v1::GameServerDeploymentsServiceClient-retry-snippet) +- [\c gameservices_v1::RealmsServiceClient](@ref gameservices_v1::RealmsServiceClient-retry-snippet) + + + +@section gameservices-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 + +*/ + +// + +/*! @page gameservices_v1::GameServerClustersServiceClient-retry-snippet Override gameservices_v1::GameServerClustersServiceClient Retry Policies + +This shows how to override the retry policies for gameservices_v1::GameServerClustersServiceClient: + +@snippet google/cloud/gameservices/v1/samples/game_server_clusters_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/gameservices/v1/samples/game_server_clusters_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page gameservices_v1::GameServerConfigsServiceClient-retry-snippet Override gameservices_v1::GameServerConfigsServiceClient Retry Policies + +This shows how to override the retry policies for gameservices_v1::GameServerConfigsServiceClient: + +@snippet google/cloud/gameservices/v1/samples/game_server_configs_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/gameservices/v1/samples/game_server_configs_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page gameservices_v1::GameServerDeploymentsServiceClient-retry-snippet Override gameservices_v1::GameServerDeploymentsServiceClient Retry Policies + +This shows how to override the retry policies for gameservices_v1::GameServerDeploymentsServiceClient: + +@snippet google/cloud/gameservices/v1/samples/game_server_deployments_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/gameservices/v1/samples/game_server_deployments_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page gameservices_v1::RealmsServiceClient-retry-snippet Override gameservices_v1::RealmsServiceClient Retry Policies + +This shows how to override the retry policies for gameservices_v1::RealmsServiceClient: + +@snippet google/cloud/gameservices/v1/samples/realms_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/gameservices/v1/samples/realms_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/gkebackup/doc/main.dox b/google/cloud/gkebackup/doc/main.dox index ccfdb1f1c8563..c82410fe75d82 100644 --- a/google/cloud/gkebackup/doc/main.dox +++ b/google/cloud/gkebackup/doc/main.dox @@ -30,12 +30,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -43,10 +37,11 @@ can override the default policies. endpoint. - @ref gkebackup-override-authentication - describes how to change the authentication credentials used by the library. +- @ref gkebackup-override-retry - describes how to change the default retry + policies. - @ref gkebackup-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/kubernetes-engine/docs/add-on/backup-for-gke -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/gkebackup/doc/override-retry-policies.dox b/google/cloud/gkebackup/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..08f2cae130309 --- /dev/null +++ b/google/cloud/gkebackup/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page gkebackup-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 gkebackup-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. + +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 gkebackup-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 gkebackup-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 gkebackup-override-retry-example Example + + +For example, this will override the retry policies for `gkebackup_v1::BackupForGKEClient`: + +@snippet backup_for_gke_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet backup_for_gke_client_samples.cc custom-idempotency-policy + + + + +@section gkebackup-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 + +*/ + +// + +/*! @page gkebackup_v1::BackupForGKEClient-retry-snippet Override gkebackup_v1::BackupForGKEClient Retry Policies + +This shows how to override the retry policies for gkebackup_v1::BackupForGKEClient: + +@snippet google/cloud/gkebackup/v1/samples/backup_for_gke_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/gkebackup/v1/samples/backup_for_gke_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/gkehub/doc/main.dox b/google/cloud/gkehub/doc/main.dox index d77e5dcc514ee..f9d7572e787c9 100644 --- a/google/cloud/gkehub/doc/main.dox +++ b/google/cloud/gkehub/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,9 +36,10 @@ can override the default policies. endpoint. - @ref gkehub-override-authentication - describes how to change the authentication credentials used by the library. +- @ref gkehub-override-retry - describes how to change the default retry + policies. - @ref gkehub-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/anthos -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/gkehub/doc/override-retry-policies.dox b/google/cloud/gkehub/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..0eb95ecc97c7e --- /dev/null +++ b/google/cloud/gkehub/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page gkehub-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 gkehub-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. + +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 gkehub-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 gkehub-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 gkehub-override-retry-example Example + + +For example, this will override the retry policies for `gkehub_v1::GkeHubClient`: + +@snippet gke_hub_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet gke_hub_client_samples.cc custom-idempotency-policy + + + + +@section gkehub-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 + +*/ + +// + +/*! @page gkehub_v1::GkeHubClient-retry-snippet Override gkehub_v1::GkeHubClient Retry Policies + +This shows how to override the retry policies for gkehub_v1::GkeHubClient: + +@snippet google/cloud/gkehub/v1/samples/gke_hub_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/gkehub/v1/samples/gke_hub_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/gkemulticloud/doc/main.dox b/google/cloud/gkemulticloud/doc/main.dox index a47de198a3d41..c40663be3c09c 100644 --- a/google/cloud/gkemulticloud/doc/main.dox +++ b/google/cloud/gkemulticloud/doc/main.dox @@ -42,12 +42,6 @@ application. - [\c gkemulticloud_v1::AzureClustersClient](@ref google::cloud::gkemulticloud_v1::AzureClustersClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -55,9 +49,10 @@ can override the default policies. endpoint. - @ref gkemulticloud-override-authentication - describes how to change the authentication credentials used by the library. +- @ref gkemulticloud-override-retry - describes how to change the default retry + policies. - @ref gkemulticloud-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/anthos/clusters/docs/multi-cloud -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/gkemulticloud/doc/override-retry-policies.dox b/google/cloud/gkemulticloud/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..31265840798bb --- /dev/null +++ b/google/cloud/gkemulticloud/doc/override-retry-policies.dox @@ -0,0 +1,135 @@ +/*! + +@page gkemulticloud-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 gkemulticloud-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. + +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 gkemulticloud-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 gkemulticloud-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 gkemulticloud-override-retry-example Example + + +For example, this will override the retry policies for `gkemulticloud_v1::AttachedClustersClient`: + +@snippet attached_clusters_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet attached_clusters_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c gkemulticloud_v1::AttachedClustersClient](@ref gkemulticloud_v1::AttachedClustersClient-retry-snippet) +- [\c gkemulticloud_v1::AwsClustersClient](@ref gkemulticloud_v1::AwsClustersClient-retry-snippet) +- [\c gkemulticloud_v1::AzureClustersClient](@ref gkemulticloud_v1::AzureClustersClient-retry-snippet) + + + +@section gkemulticloud-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 + +*/ + +// + +/*! @page gkemulticloud_v1::AttachedClustersClient-retry-snippet Override gkemulticloud_v1::AttachedClustersClient Retry Policies + +This shows how to override the retry policies for gkemulticloud_v1::AttachedClustersClient: + +@snippet google/cloud/gkemulticloud/v1/samples/attached_clusters_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/gkemulticloud/v1/samples/attached_clusters_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page gkemulticloud_v1::AwsClustersClient-retry-snippet Override gkemulticloud_v1::AwsClustersClient Retry Policies + +This shows how to override the retry policies for gkemulticloud_v1::AwsClustersClient: + +@snippet google/cloud/gkemulticloud/v1/samples/aws_clusters_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/gkemulticloud/v1/samples/aws_clusters_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page gkemulticloud_v1::AzureClustersClient-retry-snippet Override gkemulticloud_v1::AzureClustersClient Retry Policies + +This shows how to override the retry policies for gkemulticloud_v1::AzureClustersClient: + +@snippet google/cloud/gkemulticloud/v1/samples/azure_clusters_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/gkemulticloud/v1/samples/azure_clusters_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/iam/doc/main.dox b/google/cloud/iam/doc/main.dox index 90782076af0e2..3d0cad5a84ecb 100644 --- a/google/cloud/iam/doc/main.dox +++ b/google/cloud/iam/doc/main.dox @@ -43,6 +43,8 @@ application. endpoint. - @ref iam-override-authentication - describes how to change the authentication credentials used by the library. +- @ref iam-override-retry - describes how to change the default retry + policies. - @ref iam-env - describes environment variables that can configure the behavior of the library. - @ref iam-mock - @ref iam-credentials-mock diff --git a/google/cloud/iam/doc/override-retry-policies.dox b/google/cloud/iam/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..863077665b535 --- /dev/null +++ b/google/cloud/iam/doc/override-retry-policies.dox @@ -0,0 +1,148 @@ +/*! + +@page iam-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 iam-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. + +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 iam-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 iam-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 iam-override-retry-example Example + + +For example, this will override the retry policies for `iam_admin_v1::IAMClient`: + +@snippet iam_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet iam_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c iam_admin_v1::IAMClient](@ref iam_admin_v1::IAMClient-retry-snippet) +- [\c iam_credentials_v1::IAMCredentialsClient](@ref iam_credentials_v1::IAMCredentialsClient-retry-snippet) +- [\c iam_v1::IAMPolicyClient](@ref iam_v1::IAMPolicyClient-retry-snippet) +- [\c iam_v2::PoliciesClient](@ref iam_v2::PoliciesClient-retry-snippet) + + + +@section iam-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 + +*/ + +// + +/*! @page iam_admin_v1::IAMClient-retry-snippet Override iam_admin_v1::IAMClient Retry Policies + +This shows how to override the retry policies for iam_admin_v1::IAMClient: + +@snippet google/cloud/iam/admin/v1/samples/iam_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/iam/admin/v1/samples/iam_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page iam_credentials_v1::IAMCredentialsClient-retry-snippet Override iam_credentials_v1::IAMCredentialsClient Retry Policies + +This shows how to override the retry policies for iam_credentials_v1::IAMCredentialsClient: + +@snippet google/cloud/iam/credentials/v1/samples/iam_credentials_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/iam/credentials/v1/samples/iam_credentials_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page iam_v1::IAMPolicyClient-retry-snippet Override iam_v1::IAMPolicyClient Retry Policies + +This shows how to override the retry policies for iam_v1::IAMPolicyClient: + +@snippet google/cloud/iam/v1/samples/iam_policy_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/iam/v1/samples/iam_policy_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page iam_v2::PoliciesClient-retry-snippet Override iam_v2::PoliciesClient Retry Policies + +This shows how to override the retry policies for iam_v2::PoliciesClient: + +@snippet google/cloud/iam/v2/samples/policies_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/iam/v2/samples/policies_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/iap/doc/main.dox b/google/cloud/iap/doc/main.dox index 98b0cd49124c8..d63ddbf55cb50 100644 --- a/google/cloud/iap/doc/main.dox +++ b/google/cloud/iap/doc/main.dox @@ -34,12 +34,6 @@ application. - [\c iap_v1::IdentityAwareProxyOAuthServiceClient](@ref google::cloud::iap_v1::IdentityAwareProxyOAuthServiceClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -47,9 +41,10 @@ can override the default policies. endpoint. - @ref iap-override-authentication - describes how to change the authentication credentials used by the library. +- @ref iap-override-retry - describes how to change the default retry + policies. - @ref iap-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/iap -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/iap/doc/override-retry-policies.dox b/google/cloud/iap/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..c68609627f545 --- /dev/null +++ b/google/cloud/iap/doc/override-retry-policies.dox @@ -0,0 +1,122 @@ +/*! + +@page iap-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 iap-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. + +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 iap-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 iap-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 iap-override-retry-example Example + + +For example, this will override the retry policies for `iap_v1::IdentityAwareProxyAdminServiceClient`: + +@snippet identity_aware_proxy_admin_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet identity_aware_proxy_admin_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c iap_v1::IdentityAwareProxyAdminServiceClient](@ref iap_v1::IdentityAwareProxyAdminServiceClient-retry-snippet) +- [\c iap_v1::IdentityAwareProxyOAuthServiceClient](@ref iap_v1::IdentityAwareProxyOAuthServiceClient-retry-snippet) + + + +@section iap-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 + +*/ + +// + +/*! @page iap_v1::IdentityAwareProxyAdminServiceClient-retry-snippet Override iap_v1::IdentityAwareProxyAdminServiceClient Retry Policies + +This shows how to override the retry policies for iap_v1::IdentityAwareProxyAdminServiceClient: + +@snippet google/cloud/iap/v1/samples/identity_aware_proxy_admin_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/iap/v1/samples/identity_aware_proxy_admin_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page iap_v1::IdentityAwareProxyOAuthServiceClient-retry-snippet Override iap_v1::IdentityAwareProxyOAuthServiceClient Retry Policies + +This shows how to override the retry policies for iap_v1::IdentityAwareProxyOAuthServiceClient: + +@snippet google/cloud/iap/v1/samples/identity_aware_proxy_o_auth_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/iap/v1/samples/identity_aware_proxy_o_auth_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/ids/doc/main.dox b/google/cloud/ids/doc/main.dox index e24a19c4f5bc9..9ce068a7f6dcd 100644 --- a/google/cloud/ids/doc/main.dox +++ b/google/cloud/ids/doc/main.dox @@ -33,12 +33,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -46,9 +40,10 @@ can override the default policies. endpoint. - @ref ids-override-authentication - describes how to change the authentication credentials used by the library. +- @ref ids-override-retry - describes how to change the default retry + policies. - @ref ids-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/ids -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/ids/doc/override-retry-policies.dox b/google/cloud/ids/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..3c081b7536368 --- /dev/null +++ b/google/cloud/ids/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page ids-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 ids-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. + +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 ids-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 ids-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 ids-override-retry-example Example + + +For example, this will override the retry policies for `ids_v1::IDSClient`: + +@snippet ids_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet ids_client_samples.cc custom-idempotency-policy + + + + +@section ids-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 + +*/ + +// + +/*! @page ids_v1::IDSClient-retry-snippet Override ids_v1::IDSClient Retry Policies + +This shows how to override the retry policies for ids_v1::IDSClient: + +@snippet google/cloud/ids/v1/samples/ids_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/ids/v1/samples/ids_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/iot/doc/main.dox b/google/cloud/iot/doc/main.dox index 0d468ae9e9f06..4e2207b53e425 100644 --- a/google/cloud/iot/doc/main.dox +++ b/google/cloud/iot/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,9 +36,10 @@ can override the default policies. endpoint. - @ref iot-override-authentication - describes how to change the authentication credentials used by the library. +- @ref iot-override-retry - describes how to change the default retry + policies. - @ref iot-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/iot -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/iot/doc/override-retry-policies.dox b/google/cloud/iot/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..60e61cbf2f5b8 --- /dev/null +++ b/google/cloud/iot/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page iot-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 iot-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. + +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 iot-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 iot-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 iot-override-retry-example Example + + +For example, this will override the retry policies for `iot_v1::DeviceManagerClient`: + +@snippet device_manager_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet device_manager_client_samples.cc custom-idempotency-policy + + + + +@section iot-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 + +*/ + +// + +/*! @page iot_v1::DeviceManagerClient-retry-snippet Override iot_v1::DeviceManagerClient Retry Policies + +This shows how to override the retry policies for iot_v1::DeviceManagerClient: + +@snippet google/cloud/iot/v1/samples/device_manager_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/iot/v1/samples/device_manager_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/kms/doc/main.dox b/google/cloud/kms/doc/main.dox index 6c5edefe5a2bc..ac0416c2c74e5 100644 --- a/google/cloud/kms/doc/main.dox +++ b/google/cloud/kms/doc/main.dox @@ -38,12 +38,6 @@ application. - [\c kms_v1::KeyManagementServiceClient](@ref google::cloud::kms_v1::KeyManagementServiceClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -51,8 +45,9 @@ can override the default policies. endpoint. - @ref kms-override-authentication - describes how to change the authentication credentials used by the library. +- @ref kms-override-retry - describes how to change the default retry + policies. - @ref kms-env - describes environment variables that can configure the behavior of the library. -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/kms/doc/override-retry-policies.dox b/google/cloud/kms/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..85578694ea5a6 --- /dev/null +++ b/google/cloud/kms/doc/override-retry-policies.dox @@ -0,0 +1,148 @@ +/*! + +@page kms-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 kms-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. + +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 kms-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 kms-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 kms-override-retry-example Example + + +For example, this will override the retry policies for `kms_inventory_v1::KeyDashboardServiceClient`: + +@snippet key_dashboard_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet key_dashboard_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c kms_inventory_v1::KeyDashboardServiceClient](@ref kms_inventory_v1::KeyDashboardServiceClient-retry-snippet) +- [\c kms_inventory_v1::KeyTrackingServiceClient](@ref kms_inventory_v1::KeyTrackingServiceClient-retry-snippet) +- [\c kms_v1::EkmServiceClient](@ref kms_v1::EkmServiceClient-retry-snippet) +- [\c kms_v1::KeyManagementServiceClient](@ref kms_v1::KeyManagementServiceClient-retry-snippet) + + + +@section kms-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 + +*/ + +// + +/*! @page kms_inventory_v1::KeyDashboardServiceClient-retry-snippet Override kms_inventory_v1::KeyDashboardServiceClient Retry Policies + +This shows how to override the retry policies for kms_inventory_v1::KeyDashboardServiceClient: + +@snippet google/cloud/kms/inventory/v1/samples/key_dashboard_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/kms/inventory/v1/samples/key_dashboard_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page kms_inventory_v1::KeyTrackingServiceClient-retry-snippet Override kms_inventory_v1::KeyTrackingServiceClient Retry Policies + +This shows how to override the retry policies for kms_inventory_v1::KeyTrackingServiceClient: + +@snippet google/cloud/kms/inventory/v1/samples/key_tracking_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/kms/inventory/v1/samples/key_tracking_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page kms_v1::EkmServiceClient-retry-snippet Override kms_v1::EkmServiceClient Retry Policies + +This shows how to override the retry policies for kms_v1::EkmServiceClient: + +@snippet google/cloud/kms/v1/samples/ekm_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/kms/v1/samples/ekm_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page kms_v1::KeyManagementServiceClient-retry-snippet Override kms_v1::KeyManagementServiceClient Retry Policies + +This shows how to override the retry policies for kms_v1::KeyManagementServiceClient: + +@snippet google/cloud/kms/v1/samples/key_management_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/kms/v1/samples/key_management_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/language/doc/main.dox b/google/cloud/language/doc/main.dox index 20fd45c1b42a4..6c881a69b50c4 100644 --- a/google/cloud/language/doc/main.dox +++ b/google/cloud/language/doc/main.dox @@ -30,12 +30,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -43,9 +37,10 @@ can override the default policies. endpoint. - @ref language-override-authentication - describes how to change the authentication credentials used by the library. +- @ref language-override-retry - describes how to change the default retry + policies. - @ref language-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/natural-language -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/language/doc/override-retry-policies.dox b/google/cloud/language/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..71e900844d1a3 --- /dev/null +++ b/google/cloud/language/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page language-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 language-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. + +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 language-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 language-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 language-override-retry-example Example + + +For example, this will override the retry policies for `language_v1::LanguageServiceClient`: + +@snippet language_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet language_client_samples.cc custom-idempotency-policy + + + + +@section language-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 + +*/ + +// + +/*! @page language_v1::LanguageServiceClient-retry-snippet Override language_v1::LanguageServiceClient Retry Policies + +This shows how to override the retry policies for language_v1::LanguageServiceClient: + +@snippet google/cloud/language/v1/samples/language_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/language/v1/samples/language_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/logging/doc/main.dox b/google/cloud/logging/doc/main.dox index 7e1d51bf525c5..82ac8da3c79fb 100644 --- a/google/cloud/logging/doc/main.dox +++ b/google/cloud/logging/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,8 +36,9 @@ can override the default policies. endpoint. - @ref logging-override-authentication - describes how to change the authentication credentials used by the library. +- @ref logging-override-retry - describes how to change the default retry + policies. - @ref logging-env - describes environment variables that can configure the behavior of the library. -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/logging/doc/override-retry-policies.dox b/google/cloud/logging/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..b4ba64ee4a9ee --- /dev/null +++ b/google/cloud/logging/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page logging-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 logging-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. + +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 logging-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 logging-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 logging-override-retry-example Example + + +For example, this will override the retry policies for `logging_v2::LoggingServiceV2Client`: + +@snippet logging_service_v2_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet logging_service_v2_client_samples.cc custom-idempotency-policy + + + + +@section logging-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 + +*/ + +// + +/*! @page logging_v2::LoggingServiceV2Client-retry-snippet Override logging_v2::LoggingServiceV2Client Retry Policies + +This shows how to override the retry policies for logging_v2::LoggingServiceV2Client: + +@snippet google/cloud/logging/v2/samples/logging_service_v2_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/logging/v2/samples/logging_service_v2_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/managedidentities/doc/main.dox b/google/cloud/managedidentities/doc/main.dox index 30d8a8991ce6f..e1f2351dbc4df 100644 --- a/google/cloud/managedidentities/doc/main.dox +++ b/google/cloud/managedidentities/doc/main.dox @@ -30,12 +30,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -43,9 +37,10 @@ can override the default policies. endpoint. - @ref managedidentities-override-authentication - describes how to change the authentication credentials used by the library. +- @ref managedidentities-override-retry - describes how to change the default retry + policies. - @ref managedidentities-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/managed-microsoft-ad -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/managedidentities/doc/override-retry-policies.dox b/google/cloud/managedidentities/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..120939f17a8d2 --- /dev/null +++ b/google/cloud/managedidentities/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page managedidentities-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 managedidentities-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. + +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 managedidentities-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 managedidentities-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 managedidentities-override-retry-example Example + + +For example, this will override the retry policies for `managedidentities_v1::ManagedIdentitiesServiceClient`: + +@snippet managed_identities_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet managed_identities_client_samples.cc custom-idempotency-policy + + + + +@section managedidentities-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 + +*/ + +// + +/*! @page managedidentities_v1::ManagedIdentitiesServiceClient-retry-snippet Override managedidentities_v1::ManagedIdentitiesServiceClient Retry Policies + +This shows how to override the retry policies for managedidentities_v1::ManagedIdentitiesServiceClient: + +@snippet google/cloud/managedidentities/v1/samples/managed_identities_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/managedidentities/v1/samples/managed_identities_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/memcache/doc/main.dox b/google/cloud/memcache/doc/main.dox index 924d93630646b..92fe1c27075a1 100644 --- a/google/cloud/memcache/doc/main.dox +++ b/google/cloud/memcache/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,9 +36,10 @@ can override the default policies. endpoint. - @ref memcache-override-authentication - describes how to change the authentication credentials used by the library. +- @ref memcache-override-retry - describes how to change the default retry + policies. - @ref memcache-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/memorystore/docs/memcached -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/memcache/doc/override-retry-policies.dox b/google/cloud/memcache/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..ff1e69c9b16d4 --- /dev/null +++ b/google/cloud/memcache/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page memcache-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 memcache-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. + +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 memcache-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 memcache-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 memcache-override-retry-example Example + + +For example, this will override the retry policies for `memcache_v1::CloudMemcacheClient`: + +@snippet cloud_memcache_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet cloud_memcache_client_samples.cc custom-idempotency-policy + + + + +@section memcache-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 + +*/ + +// + +/*! @page memcache_v1::CloudMemcacheClient-retry-snippet Override memcache_v1::CloudMemcacheClient Retry Policies + +This shows how to override the retry policies for memcache_v1::CloudMemcacheClient: + +@snippet google/cloud/memcache/v1/samples/cloud_memcache_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/memcache/v1/samples/cloud_memcache_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/metastore/doc/main.dox b/google/cloud/metastore/doc/main.dox index 0a0841ee21bd0..6696f3a2b399e 100644 --- a/google/cloud/metastore/doc/main.dox +++ b/google/cloud/metastore/doc/main.dox @@ -36,12 +36,6 @@ application. - [\c metastore_v1::DataprocMetastoreFederationClient](@ref google::cloud::metastore_v1::DataprocMetastoreFederationClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -49,10 +43,11 @@ can override the default policies. endpoint. - @ref metastore-override-authentication - describes how to change the authentication credentials used by the library. +- @ref metastore-override-retry - describes how to change the default retry + policies. - @ref metastore-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/metastore -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/metastore/doc/override-retry-policies.dox b/google/cloud/metastore/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..fd4d857dc93cf --- /dev/null +++ b/google/cloud/metastore/doc/override-retry-policies.dox @@ -0,0 +1,122 @@ +/*! + +@page metastore-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 metastore-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. + +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 metastore-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 metastore-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 metastore-override-retry-example Example + + +For example, this will override the retry policies for `metastore_v1::DataprocMetastoreClient`: + +@snippet dataproc_metastore_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet dataproc_metastore_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c metastore_v1::DataprocMetastoreClient](@ref metastore_v1::DataprocMetastoreClient-retry-snippet) +- [\c metastore_v1::DataprocMetastoreFederationClient](@ref metastore_v1::DataprocMetastoreFederationClient-retry-snippet) + + + +@section metastore-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 + +*/ + +// + +/*! @page metastore_v1::DataprocMetastoreClient-retry-snippet Override metastore_v1::DataprocMetastoreClient Retry Policies + +This shows how to override the retry policies for metastore_v1::DataprocMetastoreClient: + +@snippet google/cloud/metastore/v1/samples/dataproc_metastore_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/metastore/v1/samples/dataproc_metastore_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page metastore_v1::DataprocMetastoreFederationClient-retry-snippet Override metastore_v1::DataprocMetastoreFederationClient Retry Policies + +This shows how to override the retry policies for metastore_v1::DataprocMetastoreFederationClient: + +@snippet google/cloud/metastore/v1/samples/dataproc_metastore_federation_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/metastore/v1/samples/dataproc_metastore_federation_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/monitoring/doc/main.dox b/google/cloud/monitoring/doc/main.dox index 327a5c45838fb..6c337ae45a7bf 100644 --- a/google/cloud/monitoring/doc/main.dox +++ b/google/cloud/monitoring/doc/main.dox @@ -44,12 +44,6 @@ application. - [\c monitoring_v3::UptimeCheckServiceClient](@ref google::cloud::monitoring_v3::UptimeCheckServiceClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -57,9 +51,10 @@ can override the default policies. endpoint. - @ref monitoring-override-authentication - describes how to change the authentication credentials used by the library. +- @ref monitoring-override-retry - describes how to change the default retry + policies. - @ref monitoring-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/monitoring -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/monitoring/doc/override-retry-policies.dox b/google/cloud/monitoring/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..b670553518ac7 --- /dev/null +++ b/google/cloud/monitoring/doc/override-retry-policies.dox @@ -0,0 +1,213 @@ +/*! + +@page monitoring-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 monitoring-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. + +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 monitoring-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 monitoring-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 monitoring-override-retry-example Example + + +For example, this will override the retry policies for `monitoring_dashboard_v1::DashboardsServiceClient`: + +@snippet dashboards_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet dashboards_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c monitoring_dashboard_v1::DashboardsServiceClient](@ref monitoring_dashboard_v1::DashboardsServiceClient-retry-snippet) +- [\c monitoring_metricsscope_v1::MetricsScopesClient](@ref monitoring_metricsscope_v1::MetricsScopesClient-retry-snippet) +- [\c monitoring_v3::AlertPolicyServiceClient](@ref monitoring_v3::AlertPolicyServiceClient-retry-snippet) +- [\c monitoring_v3::GroupServiceClient](@ref monitoring_v3::GroupServiceClient-retry-snippet) +- [\c monitoring_v3::MetricServiceClient](@ref monitoring_v3::MetricServiceClient-retry-snippet) +- [\c monitoring_v3::NotificationChannelServiceClient](@ref monitoring_v3::NotificationChannelServiceClient-retry-snippet) +- [\c monitoring_v3::QueryServiceClient](@ref monitoring_v3::QueryServiceClient-retry-snippet) +- [\c monitoring_v3::ServiceMonitoringServiceClient](@ref monitoring_v3::ServiceMonitoringServiceClient-retry-snippet) +- [\c monitoring_v3::UptimeCheckServiceClient](@ref monitoring_v3::UptimeCheckServiceClient-retry-snippet) + + + +@section monitoring-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 + +*/ + +// + +/*! @page monitoring_dashboard_v1::DashboardsServiceClient-retry-snippet Override monitoring_dashboard_v1::DashboardsServiceClient Retry Policies + +This shows how to override the retry policies for monitoring_dashboard_v1::DashboardsServiceClient: + +@snippet google/cloud/monitoring/dashboard/v1/samples/dashboards_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/monitoring/dashboard/v1/samples/dashboards_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page monitoring_metricsscope_v1::MetricsScopesClient-retry-snippet Override monitoring_metricsscope_v1::MetricsScopesClient Retry Policies + +This shows how to override the retry policies for monitoring_metricsscope_v1::MetricsScopesClient: + +@snippet google/cloud/monitoring/metricsscope/v1/samples/metrics_scopes_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/monitoring/metricsscope/v1/samples/metrics_scopes_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page monitoring_v3::AlertPolicyServiceClient-retry-snippet Override monitoring_v3::AlertPolicyServiceClient Retry Policies + +This shows how to override the retry policies for monitoring_v3::AlertPolicyServiceClient: + +@snippet google/cloud/monitoring/v3/samples/alert_policy_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/monitoring/v3/samples/alert_policy_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page monitoring_v3::GroupServiceClient-retry-snippet Override monitoring_v3::GroupServiceClient Retry Policies + +This shows how to override the retry policies for monitoring_v3::GroupServiceClient: + +@snippet google/cloud/monitoring/v3/samples/group_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/monitoring/v3/samples/group_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page monitoring_v3::MetricServiceClient-retry-snippet Override monitoring_v3::MetricServiceClient Retry Policies + +This shows how to override the retry policies for monitoring_v3::MetricServiceClient: + +@snippet google/cloud/monitoring/v3/samples/metric_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/monitoring/v3/samples/metric_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page monitoring_v3::NotificationChannelServiceClient-retry-snippet Override monitoring_v3::NotificationChannelServiceClient Retry Policies + +This shows how to override the retry policies for monitoring_v3::NotificationChannelServiceClient: + +@snippet google/cloud/monitoring/v3/samples/notification_channel_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/monitoring/v3/samples/notification_channel_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page monitoring_v3::QueryServiceClient-retry-snippet Override monitoring_v3::QueryServiceClient Retry Policies + +This shows how to override the retry policies for monitoring_v3::QueryServiceClient: + +@snippet google/cloud/monitoring/v3/samples/query_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/monitoring/v3/samples/query_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page monitoring_v3::ServiceMonitoringServiceClient-retry-snippet Override monitoring_v3::ServiceMonitoringServiceClient Retry Policies + +This shows how to override the retry policies for monitoring_v3::ServiceMonitoringServiceClient: + +@snippet google/cloud/monitoring/v3/samples/service_monitoring_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/monitoring/v3/samples/service_monitoring_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page monitoring_v3::UptimeCheckServiceClient-retry-snippet Override monitoring_v3::UptimeCheckServiceClient Retry Policies + +This shows how to override the retry policies for monitoring_v3::UptimeCheckServiceClient: + +@snippet google/cloud/monitoring/v3/samples/uptime_check_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/monitoring/v3/samples/uptime_check_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/networkconnectivity/doc/main.dox b/google/cloud/networkconnectivity/doc/main.dox index 6f9f0ac7ea54e..4e35d25c4bb45 100644 --- a/google/cloud/networkconnectivity/doc/main.dox +++ b/google/cloud/networkconnectivity/doc/main.dox @@ -31,12 +31,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -44,9 +38,10 @@ can override the default policies. endpoint. - @ref networkconnectivity-override-authentication - describes how to change the authentication credentials used by the library. +- @ref networkconnectivity-override-retry - describes how to change the default retry + policies. - @ref networkconnectivity-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/network-connectivity/docs -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/networkconnectivity/doc/override-retry-policies.dox b/google/cloud/networkconnectivity/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..96d29489de8a6 --- /dev/null +++ b/google/cloud/networkconnectivity/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page networkconnectivity-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 networkconnectivity-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. + +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 networkconnectivity-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 networkconnectivity-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 networkconnectivity-override-retry-example Example + + +For example, this will override the retry policies for `networkconnectivity_v1::HubServiceClient`: + +@snippet hub_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet hub_client_samples.cc custom-idempotency-policy + + + + +@section networkconnectivity-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 + +*/ + +// + +/*! @page networkconnectivity_v1::HubServiceClient-retry-snippet Override networkconnectivity_v1::HubServiceClient Retry Policies + +This shows how to override the retry policies for networkconnectivity_v1::HubServiceClient: + +@snippet google/cloud/networkconnectivity/v1/samples/hub_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/networkconnectivity/v1/samples/hub_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/networkmanagement/doc/main.dox b/google/cloud/networkmanagement/doc/main.dox index 7b36864754a19..9f3d16c7f6adb 100644 --- a/google/cloud/networkmanagement/doc/main.dox +++ b/google/cloud/networkmanagement/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,9 +36,10 @@ can override the default policies. endpoint. - @ref networkmanagement-override-authentication - describes how to change the authentication credentials used by the library. +- @ref networkmanagement-override-retry - describes how to change the default retry + policies. - @ref networkmanagement-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/network-intelligence-center/docs/connectivity-tests/concepts/overview -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/networkmanagement/doc/override-retry-policies.dox b/google/cloud/networkmanagement/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..46502d0a9a4ae --- /dev/null +++ b/google/cloud/networkmanagement/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page networkmanagement-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 networkmanagement-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. + +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 networkmanagement-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 networkmanagement-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 networkmanagement-override-retry-example Example + + +For example, this will override the retry policies for `networkmanagement_v1::ReachabilityServiceClient`: + +@snippet reachability_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet reachability_client_samples.cc custom-idempotency-policy + + + + +@section networkmanagement-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 + +*/ + +// + +/*! @page networkmanagement_v1::ReachabilityServiceClient-retry-snippet Override networkmanagement_v1::ReachabilityServiceClient Retry Policies + +This shows how to override the retry policies for networkmanagement_v1::ReachabilityServiceClient: + +@snippet google/cloud/networkmanagement/v1/samples/reachability_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/networkmanagement/v1/samples/reachability_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/networksecurity/doc/main.dox b/google/cloud/networksecurity/doc/main.dox index fe843d6c5ba09..551e58e59c4ac 100644 --- a/google/cloud/networksecurity/doc/main.dox +++ b/google/cloud/networksecurity/doc/main.dox @@ -30,12 +30,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -43,10 +37,11 @@ can override the default policies. endpoint. - @ref networksecurity-override-authentication - describes how to change the authentication credentials used by the library. +- @ref networksecurity-override-retry - describes how to change the default retry + policies. - @ref networksecurity-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/secure-web-proxy -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/networksecurity/doc/override-retry-policies.dox b/google/cloud/networksecurity/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..dc53411e3dc16 --- /dev/null +++ b/google/cloud/networksecurity/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page networksecurity-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 networksecurity-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. + +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 networksecurity-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 networksecurity-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 networksecurity-override-retry-example Example + + +For example, this will override the retry policies for `networksecurity_v1::NetworkSecurityClient`: + +@snippet network_security_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet network_security_client_samples.cc custom-idempotency-policy + + + + +@section networksecurity-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 + +*/ + +// + +/*! @page networksecurity_v1::NetworkSecurityClient-retry-snippet Override networksecurity_v1::NetworkSecurityClient Retry Policies + +This shows how to override the retry policies for networksecurity_v1::NetworkSecurityClient: + +@snippet google/cloud/networksecurity/v1/samples/network_security_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/networksecurity/v1/samples/network_security_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/networkservices/doc/main.dox b/google/cloud/networkservices/doc/main.dox index 4270fbc979f35..c5e03aba142bf 100644 --- a/google/cloud/networkservices/doc/main.dox +++ b/google/cloud/networkservices/doc/main.dox @@ -30,12 +30,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -43,10 +37,11 @@ can override the default policies. endpoint. - @ref networkservices-override-authentication - describes how to change the authentication credentials used by the library. +- @ref networkservices-override-retry - describes how to change the default retry + policies. - @ref networkservices-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/traffic-director/docs/service-routing-overview -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/networkservices/doc/override-retry-policies.dox b/google/cloud/networkservices/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..981fb55ee3a00 --- /dev/null +++ b/google/cloud/networkservices/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page networkservices-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 networkservices-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. + +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 networkservices-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 networkservices-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 networkservices-override-retry-example Example + + +For example, this will override the retry policies for `networkservices_v1::NetworkServicesClient`: + +@snippet network_services_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet network_services_client_samples.cc custom-idempotency-policy + + + + +@section networkservices-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 + +*/ + +// + +/*! @page networkservices_v1::NetworkServicesClient-retry-snippet Override networkservices_v1::NetworkServicesClient Retry Policies + +This shows how to override the retry policies for networkservices_v1::NetworkServicesClient: + +@snippet google/cloud/networkservices/v1/samples/network_services_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/networkservices/v1/samples/network_services_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/notebooks/doc/main.dox b/google/cloud/notebooks/doc/main.dox index 490b7921a7909..264cd1c708bfb 100644 --- a/google/cloud/notebooks/doc/main.dox +++ b/google/cloud/notebooks/doc/main.dox @@ -35,12 +35,6 @@ application. - [\c notebooks_v1::NotebookServiceClient](@ref google::cloud::notebooks_v1::NotebookServiceClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -48,10 +42,11 @@ can override the default policies. endpoint. - @ref notebooks-override-authentication - describes how to change the authentication credentials used by the library. +- @ref notebooks-override-retry - describes how to change the default retry + policies. - @ref notebooks-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/vertex-ai/docs/workbench [Vertex AI Workbench]: https://cloud.google.com/vertex-ai-workbench -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/notebooks/doc/override-retry-policies.dox b/google/cloud/notebooks/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..50c11fe26739e --- /dev/null +++ b/google/cloud/notebooks/doc/override-retry-policies.dox @@ -0,0 +1,122 @@ +/*! + +@page notebooks-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 notebooks-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. + +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 notebooks-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 notebooks-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 notebooks-override-retry-example Example + + +For example, this will override the retry policies for `notebooks_v1::ManagedNotebookServiceClient`: + +@snippet managed_notebook_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet managed_notebook_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c notebooks_v1::ManagedNotebookServiceClient](@ref notebooks_v1::ManagedNotebookServiceClient-retry-snippet) +- [\c notebooks_v1::NotebookServiceClient](@ref notebooks_v1::NotebookServiceClient-retry-snippet) + + + +@section notebooks-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 + +*/ + +// + +/*! @page notebooks_v1::ManagedNotebookServiceClient-retry-snippet Override notebooks_v1::ManagedNotebookServiceClient Retry Policies + +This shows how to override the retry policies for notebooks_v1::ManagedNotebookServiceClient: + +@snippet google/cloud/notebooks/v1/samples/managed_notebook_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/notebooks/v1/samples/managed_notebook_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page notebooks_v1::NotebookServiceClient-retry-snippet Override notebooks_v1::NotebookServiceClient Retry Policies + +This shows how to override the retry policies for notebooks_v1::NotebookServiceClient: + +@snippet google/cloud/notebooks/v1/samples/notebook_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/notebooks/v1/samples/notebook_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/optimization/doc/main.dox b/google/cloud/optimization/doc/main.dox index c3b2e42b2431c..c03659e706c24 100644 --- a/google/cloud/optimization/doc/main.dox +++ b/google/cloud/optimization/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,9 +36,10 @@ can override the default policies. endpoint. - @ref optimization-override-authentication - describes how to change the authentication credentials used by the library. +- @ref optimization-override-retry - describes how to change the default retry + policies. - @ref optimization-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/optimization -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/optimization/doc/override-retry-policies.dox b/google/cloud/optimization/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..53df667cb2765 --- /dev/null +++ b/google/cloud/optimization/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page optimization-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 optimization-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. + +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 optimization-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 optimization-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 optimization-override-retry-example Example + + +For example, this will override the retry policies for `optimization_v1::FleetRoutingClient`: + +@snippet fleet_routing_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet fleet_routing_client_samples.cc custom-idempotency-policy + + + + +@section optimization-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 + +*/ + +// + +/*! @page optimization_v1::FleetRoutingClient-retry-snippet Override optimization_v1::FleetRoutingClient Retry Policies + +This shows how to override the retry policies for optimization_v1::FleetRoutingClient: + +@snippet google/cloud/optimization/v1/samples/fleet_routing_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/optimization/v1/samples/fleet_routing_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/orgpolicy/doc/main.dox b/google/cloud/orgpolicy/doc/main.dox index 2cb775cb4ea10..00754fdf88679 100644 --- a/google/cloud/orgpolicy/doc/main.dox +++ b/google/cloud/orgpolicy/doc/main.dox @@ -28,12 +28,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -41,9 +35,10 @@ can override the default policies. endpoint. - @ref orgpolicy-override-authentication - describes how to change the authentication credentials used by the library. +- @ref orgpolicy-override-retry - describes how to change the default retry + policies. - @ref orgpolicy-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/resource-manager/docs/organization-policy/overview -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/orgpolicy/doc/override-retry-policies.dox b/google/cloud/orgpolicy/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..b56cfc796e18d --- /dev/null +++ b/google/cloud/orgpolicy/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page orgpolicy-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 orgpolicy-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. + +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 orgpolicy-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 orgpolicy-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 orgpolicy-override-retry-example Example + + +For example, this will override the retry policies for `orgpolicy_v2::OrgPolicyClient`: + +@snippet org_policy_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet org_policy_client_samples.cc custom-idempotency-policy + + + + +@section orgpolicy-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 + +*/ + +// + +/*! @page orgpolicy_v2::OrgPolicyClient-retry-snippet Override orgpolicy_v2::OrgPolicyClient Retry Policies + +This shows how to override the retry policies for orgpolicy_v2::OrgPolicyClient: + +@snippet google/cloud/orgpolicy/v2/samples/org_policy_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/orgpolicy/v2/samples/org_policy_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/osconfig/doc/main.dox b/google/cloud/osconfig/doc/main.dox index d63beae8fca86..c38f5b2f93700 100644 --- a/google/cloud/osconfig/doc/main.dox +++ b/google/cloud/osconfig/doc/main.dox @@ -35,12 +35,6 @@ application. - [\c osconfig_v1::OsConfigServiceClient](@ref google::cloud::osconfig_v1::OsConfigServiceClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -48,9 +42,10 @@ can override the default policies. endpoint. - @ref osconfig-override-authentication - describes how to change the authentication credentials used by the library. +- @ref osconfig-override-retry - describes how to change the default retry + policies. - @ref osconfig-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/compute/docs/os-configuration-management -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/osconfig/doc/override-retry-policies.dox b/google/cloud/osconfig/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..8c1dbe0dc9652 --- /dev/null +++ b/google/cloud/osconfig/doc/override-retry-policies.dox @@ -0,0 +1,122 @@ +/*! + +@page osconfig-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 osconfig-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. + +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 osconfig-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 osconfig-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 osconfig-override-retry-example Example + + +For example, this will override the retry policies for `osconfig_agentendpoint_v1::AgentEndpointServiceClient`: + +@snippet agent_endpoint_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet agent_endpoint_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c osconfig_agentendpoint_v1::AgentEndpointServiceClient](@ref osconfig_agentendpoint_v1::AgentEndpointServiceClient-retry-snippet) +- [\c osconfig_v1::OsConfigServiceClient](@ref osconfig_v1::OsConfigServiceClient-retry-snippet) + + + +@section osconfig-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 + +*/ + +// + +/*! @page osconfig_agentendpoint_v1::AgentEndpointServiceClient-retry-snippet Override osconfig_agentendpoint_v1::AgentEndpointServiceClient Retry Policies + +This shows how to override the retry policies for osconfig_agentendpoint_v1::AgentEndpointServiceClient: + +@snippet google/cloud/osconfig/agentendpoint/v1/samples/agent_endpoint_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/osconfig/agentendpoint/v1/samples/agent_endpoint_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page osconfig_v1::OsConfigServiceClient-retry-snippet Override osconfig_v1::OsConfigServiceClient Retry Policies + +This shows how to override the retry policies for osconfig_v1::OsConfigServiceClient: + +@snippet google/cloud/osconfig/v1/samples/os_config_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/osconfig/v1/samples/os_config_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/oslogin/doc/main.dox b/google/cloud/oslogin/doc/main.dox index c6714962fe6ca..2e75daf7be1f9 100644 --- a/google/cloud/oslogin/doc/main.dox +++ b/google/cloud/oslogin/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,9 +36,10 @@ can override the default policies. endpoint. - @ref oslogin-override-authentication - describes how to change the authentication credentials used by the library. +- @ref oslogin-override-retry - describes how to change the default retry + policies. - @ref oslogin-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/compute/docs/oslogin -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/oslogin/doc/override-retry-policies.dox b/google/cloud/oslogin/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..81cb7b1ea549a --- /dev/null +++ b/google/cloud/oslogin/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page oslogin-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 oslogin-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. + +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 oslogin-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 oslogin-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 oslogin-override-retry-example Example + + +For example, this will override the retry policies for `oslogin_v1::OsLoginServiceClient`: + +@snippet os_login_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet os_login_client_samples.cc custom-idempotency-policy + + + + +@section oslogin-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 + +*/ + +// + +/*! @page oslogin_v1::OsLoginServiceClient-retry-snippet Override oslogin_v1::OsLoginServiceClient Retry Policies + +This shows how to override the retry policies for oslogin_v1::OsLoginServiceClient: + +@snippet google/cloud/oslogin/v1/samples/os_login_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/oslogin/v1/samples/os_login_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/policytroubleshooter/doc/main.dox b/google/cloud/policytroubleshooter/doc/main.dox index 8916ffa873254..521880ad814dc 100644 --- a/google/cloud/policytroubleshooter/doc/main.dox +++ b/google/cloud/policytroubleshooter/doc/main.dox @@ -30,12 +30,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -43,9 +37,10 @@ can override the default policies. endpoint. - @ref policytroubleshooter-override-authentication - describes how to change the authentication credentials used by the library. +- @ref policytroubleshooter-override-retry - describes how to change the default retry + policies. - @ref policytroubleshooter-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/iam/docs/troubleshooting-access -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/policytroubleshooter/doc/override-retry-policies.dox b/google/cloud/policytroubleshooter/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..9b9a7c921ae2e --- /dev/null +++ b/google/cloud/policytroubleshooter/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page policytroubleshooter-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 policytroubleshooter-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. + +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 policytroubleshooter-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 policytroubleshooter-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 policytroubleshooter-override-retry-example Example + + +For example, this will override the retry policies for `policytroubleshooter_v1::IamCheckerClient`: + +@snippet iam_checker_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet iam_checker_client_samples.cc custom-idempotency-policy + + + + +@section policytroubleshooter-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 + +*/ + +// + +/*! @page policytroubleshooter_v1::IamCheckerClient-retry-snippet Override policytroubleshooter_v1::IamCheckerClient Retry Policies + +This shows how to override the retry policies for policytroubleshooter_v1::IamCheckerClient: + +@snippet google/cloud/policytroubleshooter/v1/samples/iam_checker_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/policytroubleshooter/v1/samples/iam_checker_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/privateca/doc/main.dox b/google/cloud/privateca/doc/main.dox index 80f722fd329b5..32d333bd65cb5 100644 --- a/google/cloud/privateca/doc/main.dox +++ b/google/cloud/privateca/doc/main.dox @@ -31,12 +31,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -44,9 +38,10 @@ can override the default policies. endpoint. - @ref privateca-override-authentication - describes how to change the authentication credentials used by the library. +- @ref privateca-override-retry - describes how to change the default retry + policies. - @ref privateca-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/certificate-authority-service/docs -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/privateca/doc/override-retry-policies.dox b/google/cloud/privateca/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..d9107340c0130 --- /dev/null +++ b/google/cloud/privateca/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page privateca-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 privateca-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. + +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 privateca-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 privateca-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 privateca-override-retry-example Example + + +For example, this will override the retry policies for `privateca_v1::CertificateAuthorityServiceClient`: + +@snippet certificate_authority_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet certificate_authority_client_samples.cc custom-idempotency-policy + + + + +@section privateca-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 + +*/ + +// + +/*! @page privateca_v1::CertificateAuthorityServiceClient-retry-snippet Override privateca_v1::CertificateAuthorityServiceClient Retry Policies + +This shows how to override the retry policies for privateca_v1::CertificateAuthorityServiceClient: + +@snippet google/cloud/privateca/v1/samples/certificate_authority_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/privateca/v1/samples/certificate_authority_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/profiler/doc/main.dox b/google/cloud/profiler/doc/main.dox index ecca1715d2679..b607932cc7f58 100644 --- a/google/cloud/profiler/doc/main.dox +++ b/google/cloud/profiler/doc/main.dox @@ -36,12 +36,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -49,9 +43,10 @@ can override the default policies. endpoint. - @ref profiler-override-authentication - describes how to change the authentication credentials used by the library. +- @ref profiler-override-retry - describes how to change the default retry + policies. - @ref profiler-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/profiler -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/profiler/doc/override-retry-policies.dox b/google/cloud/profiler/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..526ddb3dedb8e --- /dev/null +++ b/google/cloud/profiler/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page profiler-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 profiler-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. + +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 profiler-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 profiler-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 profiler-override-retry-example Example + + +For example, this will override the retry policies for `profiler_v2::ProfilerServiceClient`: + +@snippet profiler_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet profiler_client_samples.cc custom-idempotency-policy + + + + +@section profiler-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 + +*/ + +// + +/*! @page profiler_v2::ProfilerServiceClient-retry-snippet Override profiler_v2::ProfilerServiceClient Retry Policies + +This shows how to override the retry policies for profiler_v2::ProfilerServiceClient: + +@snippet google/cloud/profiler/v2/samples/profiler_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/profiler/v2/samples/profiler_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/pubsublite/doc/main.dox b/google/cloud/pubsublite/doc/main.dox index 6444d0347fab6..6442c064935cb 100644 --- a/google/cloud/pubsublite/doc/main.dox +++ b/google/cloud/pubsublite/doc/main.dox @@ -49,6 +49,8 @@ can override the default policies. endpoint. - @ref pubsublite-override-authentication - describes how to change the authentication credentials used by the library. +- @ref pubsublite-override-retry - describes how to change the default retry + policies. - @ref pubsublite-env - describes environment variables that can configure the behavior of the library. [exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff diff --git a/google/cloud/pubsublite/doc/override-retry-policies.dox b/google/cloud/pubsublite/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..b095093626ee9 --- /dev/null +++ b/google/cloud/pubsublite/doc/override-retry-policies.dox @@ -0,0 +1,122 @@ +/*! + +@page pubsublite-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 pubsublite-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. + +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 pubsublite-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 pubsublite-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 pubsublite-override-retry-example Example + + +For example, this will override the retry policies for `pubsublite::AdminServiceClient`: + +@snippet admin_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet admin_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c pubsublite::AdminServiceClient](@ref pubsublite::AdminServiceClient-retry-snippet) +- [\c pubsublite::TopicStatsServiceClient](@ref pubsublite::TopicStatsServiceClient-retry-snippet) + + + +@section pubsublite-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 + +*/ + +// + +/*! @page pubsublite::AdminServiceClient-retry-snippet Override pubsublite::AdminServiceClient Retry Policies + +This shows how to override the retry policies for pubsublite::AdminServiceClient: + +@snippet google/cloud/pubsublite/samples/admin_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/pubsublite/samples/admin_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page pubsublite::TopicStatsServiceClient-retry-snippet Override pubsublite::TopicStatsServiceClient Retry Policies + +This shows how to override the retry policies for pubsublite::TopicStatsServiceClient: + +@snippet google/cloud/pubsublite/samples/topic_stats_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/pubsublite/samples/topic_stats_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/recaptchaenterprise/doc/main.dox b/google/cloud/recaptchaenterprise/doc/main.dox index 7edaddd672ecd..8d9e4519c0f6b 100644 --- a/google/cloud/recaptchaenterprise/doc/main.dox +++ b/google/cloud/recaptchaenterprise/doc/main.dox @@ -30,12 +30,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -43,10 +37,11 @@ can override the default policies. endpoint. - @ref recaptchaenterprise-override-authentication - describes how to change the authentication credentials used by the library. +- @ref recaptchaenterprise-override-retry - describes how to change the default retry + policies. - @ref recaptchaenterprise-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/recaptcha-enterprise -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/recaptchaenterprise/doc/override-retry-policies.dox b/google/cloud/recaptchaenterprise/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..214b31b2edb8a --- /dev/null +++ b/google/cloud/recaptchaenterprise/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page recaptchaenterprise-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 recaptchaenterprise-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. + +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 recaptchaenterprise-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 recaptchaenterprise-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 recaptchaenterprise-override-retry-example Example + + +For example, this will override the retry policies for `recaptchaenterprise_v1::RecaptchaEnterpriseServiceClient`: + +@snippet recaptcha_enterprise_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet recaptcha_enterprise_client_samples.cc custom-idempotency-policy + + + + +@section recaptchaenterprise-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 + +*/ + +// + +/*! @page recaptchaenterprise_v1::RecaptchaEnterpriseServiceClient-retry-snippet Override recaptchaenterprise_v1::RecaptchaEnterpriseServiceClient Retry Policies + +This shows how to override the retry policies for recaptchaenterprise_v1::RecaptchaEnterpriseServiceClient: + +@snippet google/cloud/recaptchaenterprise/v1/samples/recaptcha_enterprise_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/recaptchaenterprise/v1/samples/recaptcha_enterprise_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/recommender/doc/main.dox b/google/cloud/recommender/doc/main.dox index 68dcfa3e0baf3..505169ccc0cb4 100644 --- a/google/cloud/recommender/doc/main.dox +++ b/google/cloud/recommender/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,9 +36,10 @@ can override the default policies. endpoint. - @ref recommender-override-authentication - describes how to change the authentication credentials used by the library. +- @ref recommender-override-retry - describes how to change the default retry + policies. - @ref recommender-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/recommender -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/recommender/doc/override-retry-policies.dox b/google/cloud/recommender/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..972c352813f02 --- /dev/null +++ b/google/cloud/recommender/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page recommender-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 recommender-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. + +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 recommender-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 recommender-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 recommender-override-retry-example Example + + +For example, this will override the retry policies for `recommender_v1::RecommenderClient`: + +@snippet recommender_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet recommender_client_samples.cc custom-idempotency-policy + + + + +@section recommender-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 + +*/ + +// + +/*! @page recommender_v1::RecommenderClient-retry-snippet Override recommender_v1::RecommenderClient Retry Policies + +This shows how to override the retry policies for recommender_v1::RecommenderClient: + +@snippet google/cloud/recommender/v1/samples/recommender_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/recommender/v1/samples/recommender_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/redis/doc/main.dox b/google/cloud/redis/doc/main.dox index d2f4fe5a45ab1..b5dd2ee320b95 100644 --- a/google/cloud/redis/doc/main.dox +++ b/google/cloud/redis/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,9 +36,10 @@ can override the default policies. endpoint. - @ref redis-override-authentication - describes how to change the authentication credentials used by the library. +- @ref redis-override-retry - describes how to change the default retry + policies. - @ref redis-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/memorystore/docs/redis -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/redis/doc/override-retry-policies.dox b/google/cloud/redis/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..67f2a45374de0 --- /dev/null +++ b/google/cloud/redis/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page redis-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 redis-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. + +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 redis-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 redis-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 redis-override-retry-example Example + + +For example, this will override the retry policies for `redis_v1::CloudRedisClient`: + +@snippet cloud_redis_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet cloud_redis_client_samples.cc custom-idempotency-policy + + + + +@section redis-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 + +*/ + +// + +/*! @page redis_v1::CloudRedisClient-retry-snippet Override redis_v1::CloudRedisClient Retry Policies + +This shows how to override the retry policies for redis_v1::CloudRedisClient: + +@snippet google/cloud/redis/v1/samples/cloud_redis_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/redis/v1/samples/cloud_redis_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/resourcemanager/doc/main.dox b/google/cloud/resourcemanager/doc/main.dox index c1404cce10fcb..372fa9c55ec17 100644 --- a/google/cloud/resourcemanager/doc/main.dox +++ b/google/cloud/resourcemanager/doc/main.dox @@ -36,12 +36,6 @@ application. - [\c resourcemanager_v3::ProjectsClient](@ref google::cloud::resourcemanager_v3::ProjectsClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -49,9 +43,10 @@ can override the default policies. endpoint. - @ref resourcemanager-override-authentication - describes how to change the authentication credentials used by the library. +- @ref resourcemanager-override-retry - describes how to change the default retry + policies. - @ref resourcemanager-env - describes environment variables that can configure the behavior of the library. [cloud-product]: https://cloud.google.com/resource-manager -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/resourcemanager/doc/override-retry-policies.dox b/google/cloud/resourcemanager/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..8d73fddda703c --- /dev/null +++ b/google/cloud/resourcemanager/doc/override-retry-policies.dox @@ -0,0 +1,135 @@ +/*! + +@page resourcemanager-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 resourcemanager-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. + +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 resourcemanager-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 resourcemanager-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 resourcemanager-override-retry-example Example + + +For example, this will override the retry policies for `resourcemanager_v3::FoldersClient`: + +@snippet folders_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet folders_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c resourcemanager_v3::FoldersClient](@ref resourcemanager_v3::FoldersClient-retry-snippet) +- [\c resourcemanager_v3::OrganizationsClient](@ref resourcemanager_v3::OrganizationsClient-retry-snippet) +- [\c resourcemanager_v3::ProjectsClient](@ref resourcemanager_v3::ProjectsClient-retry-snippet) + + + +@section resourcemanager-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 + +*/ + +// + +/*! @page resourcemanager_v3::FoldersClient-retry-snippet Override resourcemanager_v3::FoldersClient Retry Policies + +This shows how to override the retry policies for resourcemanager_v3::FoldersClient: + +@snippet google/cloud/resourcemanager/v3/samples/folders_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/resourcemanager/v3/samples/folders_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page resourcemanager_v3::OrganizationsClient-retry-snippet Override resourcemanager_v3::OrganizationsClient Retry Policies + +This shows how to override the retry policies for resourcemanager_v3::OrganizationsClient: + +@snippet google/cloud/resourcemanager/v3/samples/organizations_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/resourcemanager/v3/samples/organizations_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page resourcemanager_v3::ProjectsClient-retry-snippet Override resourcemanager_v3::ProjectsClient Retry Policies + +This shows how to override the retry policies for resourcemanager_v3::ProjectsClient: + +@snippet google/cloud/resourcemanager/v3/samples/projects_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/resourcemanager/v3/samples/projects_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/resourcesettings/doc/main.dox b/google/cloud/resourcesettings/doc/main.dox index 172b871da1cc2..f11a39e579e55 100644 --- a/google/cloud/resourcesettings/doc/main.dox +++ b/google/cloud/resourcesettings/doc/main.dox @@ -30,12 +30,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -43,9 +37,10 @@ can override the default policies. endpoint. - @ref resourcesettings-override-authentication - describes how to change the authentication credentials used by the library. +- @ref resourcesettings-override-retry - describes how to change the default retry + policies. - @ref resourcesettings-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/resource-manager/docs/resource-settings/overview -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/resourcesettings/doc/override-retry-policies.dox b/google/cloud/resourcesettings/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..32da4b5d20b81 --- /dev/null +++ b/google/cloud/resourcesettings/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page resourcesettings-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 resourcesettings-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. + +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 resourcesettings-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 resourcesettings-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 resourcesettings-override-retry-example Example + + +For example, this will override the retry policies for `resourcesettings_v1::ResourceSettingsServiceClient`: + +@snippet resource_settings_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet resource_settings_client_samples.cc custom-idempotency-policy + + + + +@section resourcesettings-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 + +*/ + +// + +/*! @page resourcesettings_v1::ResourceSettingsServiceClient-retry-snippet Override resourcesettings_v1::ResourceSettingsServiceClient Retry Policies + +This shows how to override the retry policies for resourcesettings_v1::ResourceSettingsServiceClient: + +@snippet google/cloud/resourcesettings/v1/samples/resource_settings_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/resourcesettings/v1/samples/resource_settings_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/retail/doc/main.dox b/google/cloud/retail/doc/main.dox index 62f56c305d3e0..ee125bdc0a72c 100644 --- a/google/cloud/retail/doc/main.dox +++ b/google/cloud/retail/doc/main.dox @@ -40,12 +40,6 @@ application. - [\c retail_v2::UserEventServiceClient](@ref google::cloud::retail_v2::UserEventServiceClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -53,9 +47,10 @@ can override the default policies. endpoint. - @ref retail-override-authentication - describes how to change the authentication credentials used by the library. +- @ref retail-override-retry - describes how to change the default retry + policies. - @ref retail-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/retail/docs -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/retail/doc/override-retry-policies.dox b/google/cloud/retail/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..998fb26601219 --- /dev/null +++ b/google/cloud/retail/doc/override-retry-policies.dox @@ -0,0 +1,174 @@ +/*! + +@page retail-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 retail-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. + +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 retail-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 retail-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 retail-override-retry-example Example + + +For example, this will override the retry policies for `retail_v2::CatalogServiceClient`: + +@snippet catalog_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet catalog_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c retail_v2::CatalogServiceClient](@ref retail_v2::CatalogServiceClient-retry-snippet) +- [\c retail_v2::CompletionServiceClient](@ref retail_v2::CompletionServiceClient-retry-snippet) +- [\c retail_v2::PredictionServiceClient](@ref retail_v2::PredictionServiceClient-retry-snippet) +- [\c retail_v2::ProductServiceClient](@ref retail_v2::ProductServiceClient-retry-snippet) +- [\c retail_v2::SearchServiceClient](@ref retail_v2::SearchServiceClient-retry-snippet) +- [\c retail_v2::UserEventServiceClient](@ref retail_v2::UserEventServiceClient-retry-snippet) + + + +@section retail-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 + +*/ + +// + +/*! @page retail_v2::CatalogServiceClient-retry-snippet Override retail_v2::CatalogServiceClient Retry Policies + +This shows how to override the retry policies for retail_v2::CatalogServiceClient: + +@snippet google/cloud/retail/v2/samples/catalog_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/retail/v2/samples/catalog_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page retail_v2::CompletionServiceClient-retry-snippet Override retail_v2::CompletionServiceClient Retry Policies + +This shows how to override the retry policies for retail_v2::CompletionServiceClient: + +@snippet google/cloud/retail/v2/samples/completion_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/retail/v2/samples/completion_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page retail_v2::PredictionServiceClient-retry-snippet Override retail_v2::PredictionServiceClient Retry Policies + +This shows how to override the retry policies for retail_v2::PredictionServiceClient: + +@snippet google/cloud/retail/v2/samples/prediction_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/retail/v2/samples/prediction_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page retail_v2::ProductServiceClient-retry-snippet Override retail_v2::ProductServiceClient Retry Policies + +This shows how to override the retry policies for retail_v2::ProductServiceClient: + +@snippet google/cloud/retail/v2/samples/product_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/retail/v2/samples/product_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page retail_v2::SearchServiceClient-retry-snippet Override retail_v2::SearchServiceClient Retry Policies + +This shows how to override the retry policies for retail_v2::SearchServiceClient: + +@snippet google/cloud/retail/v2/samples/search_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/retail/v2/samples/search_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page retail_v2::UserEventServiceClient-retry-snippet Override retail_v2::UserEventServiceClient Retry Policies + +This shows how to override the retry policies for retail_v2::UserEventServiceClient: + +@snippet google/cloud/retail/v2/samples/user_event_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/retail/v2/samples/user_event_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/run/doc/main.dox b/google/cloud/run/doc/main.dox index 1e27a6cbee15d..08934600b8cc2 100644 --- a/google/cloud/run/doc/main.dox +++ b/google/cloud/run/doc/main.dox @@ -43,12 +43,6 @@ application. - [\c run_v2::ServicesClient](@ref google::cloud::run_v2::ServicesClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -56,9 +50,10 @@ can override the default policies. endpoint. - @ref run-override-authentication - describes how to change the authentication credentials used by the library. +- @ref run-override-retry - describes how to change the default retry + policies. - @ref run-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/run -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/run/doc/override-retry-policies.dox b/google/cloud/run/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..535752467528b --- /dev/null +++ b/google/cloud/run/doc/override-retry-policies.dox @@ -0,0 +1,122 @@ +/*! + +@page run-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 run-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. + +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 run-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 run-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 run-override-retry-example Example + + +For example, this will override the retry policies for `run_v2::RevisionsClient`: + +@snippet revisions_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet revisions_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c run_v2::RevisionsClient](@ref run_v2::RevisionsClient-retry-snippet) +- [\c run_v2::ServicesClient](@ref run_v2::ServicesClient-retry-snippet) + + + +@section run-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 + +*/ + +// + +/*! @page run_v2::RevisionsClient-retry-snippet Override run_v2::RevisionsClient Retry Policies + +This shows how to override the retry policies for run_v2::RevisionsClient: + +@snippet google/cloud/run/v2/samples/revisions_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/run/v2/samples/revisions_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page run_v2::ServicesClient-retry-snippet Override run_v2::ServicesClient Retry Policies + +This shows how to override the retry policies for run_v2::ServicesClient: + +@snippet google/cloud/run/v2/samples/services_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/run/v2/samples/services_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/scheduler/doc/main.dox b/google/cloud/scheduler/doc/main.dox index 1946f6e96c617..e52f9a69d61d3 100644 --- a/google/cloud/scheduler/doc/main.dox +++ b/google/cloud/scheduler/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,8 +36,9 @@ can override the default policies. endpoint. - @ref scheduler-override-authentication - describes how to change the authentication credentials used by the library. +- @ref scheduler-override-retry - describes how to change the default retry + policies. - @ref scheduler-env - describes environment variables that can configure the behavior of the library. -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/scheduler/doc/override-retry-policies.dox b/google/cloud/scheduler/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..14e884cc24732 --- /dev/null +++ b/google/cloud/scheduler/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page scheduler-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 scheduler-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. + +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 scheduler-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 scheduler-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 scheduler-override-retry-example Example + + +For example, this will override the retry policies for `scheduler_v1::CloudSchedulerClient`: + +@snippet cloud_scheduler_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet cloud_scheduler_client_samples.cc custom-idempotency-policy + + + + +@section scheduler-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 + +*/ + +// + +/*! @page scheduler_v1::CloudSchedulerClient-retry-snippet Override scheduler_v1::CloudSchedulerClient Retry Policies + +This shows how to override the retry policies for scheduler_v1::CloudSchedulerClient: + +@snippet google/cloud/scheduler/v1/samples/cloud_scheduler_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/scheduler/v1/samples/cloud_scheduler_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/secretmanager/doc/main.dox b/google/cloud/secretmanager/doc/main.dox index b7ddb1437a676..bb38875808f2b 100644 --- a/google/cloud/secretmanager/doc/main.dox +++ b/google/cloud/secretmanager/doc/main.dox @@ -30,12 +30,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -43,8 +37,9 @@ can override the default policies. endpoint. - @ref secretmanager-override-authentication - describes how to change the authentication credentials used by the library. +- @ref secretmanager-override-retry - describes how to change the default retry + policies. - @ref secretmanager-env - describes environment variables that can configure the behavior of the library. -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/secretmanager/doc/override-retry-policies.dox b/google/cloud/secretmanager/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..80afca03c0e70 --- /dev/null +++ b/google/cloud/secretmanager/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page secretmanager-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 secretmanager-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. + +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 secretmanager-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 secretmanager-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 secretmanager-override-retry-example Example + + +For example, this will override the retry policies for `secretmanager_v1::SecretManagerServiceClient`: + +@snippet secret_manager_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet secret_manager_client_samples.cc custom-idempotency-policy + + + + +@section secretmanager-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 + +*/ + +// + +/*! @page secretmanager_v1::SecretManagerServiceClient-retry-snippet Override secretmanager_v1::SecretManagerServiceClient Retry Policies + +This shows how to override the retry policies for secretmanager_v1::SecretManagerServiceClient: + +@snippet google/cloud/secretmanager/v1/samples/secret_manager_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/secretmanager/v1/samples/secret_manager_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/securitycenter/doc/main.dox b/google/cloud/securitycenter/doc/main.dox index 38b75afee8334..23d51e8b4191f 100644 --- a/google/cloud/securitycenter/doc/main.dox +++ b/google/cloud/securitycenter/doc/main.dox @@ -28,12 +28,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -41,9 +35,10 @@ can override the default policies. endpoint. - @ref securitycenter-override-authentication - describes how to change the authentication credentials used by the library. +- @ref securitycenter-override-retry - describes how to change the default retry + policies. - @ref securitycenter-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/security-command-center -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/securitycenter/doc/override-retry-policies.dox b/google/cloud/securitycenter/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..21e3d6d9e2855 --- /dev/null +++ b/google/cloud/securitycenter/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page securitycenter-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 securitycenter-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. + +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 securitycenter-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 securitycenter-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 securitycenter-override-retry-example Example + + +For example, this will override the retry policies for `securitycenter_v1::SecurityCenterClient`: + +@snippet security_center_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet security_center_client_samples.cc custom-idempotency-policy + + + + +@section securitycenter-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 + +*/ + +// + +/*! @page securitycenter_v1::SecurityCenterClient-retry-snippet Override securitycenter_v1::SecurityCenterClient Retry Policies + +This shows how to override the retry policies for securitycenter_v1::SecurityCenterClient: + +@snippet google/cloud/securitycenter/v1/samples/security_center_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/securitycenter/v1/samples/security_center_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/servicecontrol/doc/main.dox b/google/cloud/servicecontrol/doc/main.dox index cddfae4f1e790..225b12095669a 100644 --- a/google/cloud/servicecontrol/doc/main.dox +++ b/google/cloud/servicecontrol/doc/main.dox @@ -36,12 +36,6 @@ application. - [\c servicecontrol_v2::ServiceControllerClient](@ref google::cloud::servicecontrol_v2::ServiceControllerClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -49,9 +43,10 @@ can override the default policies. endpoint. - @ref servicecontrol-override-authentication - describes how to change the authentication credentials used by the library. +- @ref servicecontrol-override-retry - describes how to change the default retry + policies. - @ref servicecontrol-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/service-control -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/servicecontrol/doc/override-retry-policies.dox b/google/cloud/servicecontrol/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..a8e2ee3aa1955 --- /dev/null +++ b/google/cloud/servicecontrol/doc/override-retry-policies.dox @@ -0,0 +1,135 @@ +/*! + +@page servicecontrol-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 servicecontrol-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. + +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 servicecontrol-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 servicecontrol-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 servicecontrol-override-retry-example Example + + +For example, this will override the retry policies for `servicecontrol_v1::QuotaControllerClient`: + +@snippet quota_controller_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet quota_controller_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c servicecontrol_v1::QuotaControllerClient](@ref servicecontrol_v1::QuotaControllerClient-retry-snippet) +- [\c servicecontrol_v1::ServiceControllerClient](@ref servicecontrol_v1::ServiceControllerClient-retry-snippet) +- [\c servicecontrol_v2::ServiceControllerClient](@ref servicecontrol_v2::ServiceControllerClient-retry-snippet) + + + +@section servicecontrol-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 + +*/ + +// + +/*! @page servicecontrol_v1::QuotaControllerClient-retry-snippet Override servicecontrol_v1::QuotaControllerClient Retry Policies + +This shows how to override the retry policies for servicecontrol_v1::QuotaControllerClient: + +@snippet google/cloud/servicecontrol/v1/samples/quota_controller_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/servicecontrol/v1/samples/quota_controller_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page servicecontrol_v1::ServiceControllerClient-retry-snippet Override servicecontrol_v1::ServiceControllerClient Retry Policies + +This shows how to override the retry policies for servicecontrol_v1::ServiceControllerClient: + +@snippet google/cloud/servicecontrol/v1/samples/service_controller_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/servicecontrol/v1/samples/service_controller_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page servicecontrol_v2::ServiceControllerClient-retry-snippet Override servicecontrol_v2::ServiceControllerClient Retry Policies + +This shows how to override the retry policies for servicecontrol_v2::ServiceControllerClient: + +@snippet google/cloud/servicecontrol/v2/samples/service_controller_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/servicecontrol/v2/samples/service_controller_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/servicedirectory/doc/main.dox b/google/cloud/servicedirectory/doc/main.dox index 6ade247672cad..e8514a88108ba 100644 --- a/google/cloud/servicedirectory/doc/main.dox +++ b/google/cloud/servicedirectory/doc/main.dox @@ -35,12 +35,6 @@ application. - [\c servicedirectory_v1::RegistrationServiceClient](@ref google::cloud::servicedirectory_v1::RegistrationServiceClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -48,9 +42,10 @@ can override the default policies. endpoint. - @ref servicedirectory-override-authentication - describes how to change the authentication credentials used by the library. +- @ref servicedirectory-override-retry - describes how to change the default retry + policies. - @ref servicedirectory-env - describes environment variables that can configure the behavior of the library. [cloud-service]: https://cloud.google.com/service-directory -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/servicedirectory/doc/override-retry-policies.dox b/google/cloud/servicedirectory/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..5c2824d0df264 --- /dev/null +++ b/google/cloud/servicedirectory/doc/override-retry-policies.dox @@ -0,0 +1,122 @@ +/*! + +@page servicedirectory-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 servicedirectory-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. + +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 servicedirectory-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 servicedirectory-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 servicedirectory-override-retry-example Example + + +For example, this will override the retry policies for `servicedirectory_v1::LookupServiceClient`: + +@snippet lookup_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet lookup_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c servicedirectory_v1::LookupServiceClient](@ref servicedirectory_v1::LookupServiceClient-retry-snippet) +- [\c servicedirectory_v1::RegistrationServiceClient](@ref servicedirectory_v1::RegistrationServiceClient-retry-snippet) + + + +@section servicedirectory-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 + +*/ + +// + +/*! @page servicedirectory_v1::LookupServiceClient-retry-snippet Override servicedirectory_v1::LookupServiceClient Retry Policies + +This shows how to override the retry policies for servicedirectory_v1::LookupServiceClient: + +@snippet google/cloud/servicedirectory/v1/samples/lookup_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/servicedirectory/v1/samples/lookup_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page servicedirectory_v1::RegistrationServiceClient-retry-snippet Override servicedirectory_v1::RegistrationServiceClient Retry Policies + +This shows how to override the retry policies for servicedirectory_v1::RegistrationServiceClient: + +@snippet google/cloud/servicedirectory/v1/samples/registration_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/servicedirectory/v1/samples/registration_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/servicemanagement/doc/main.dox b/google/cloud/servicemanagement/doc/main.dox index 8f80ae977113f..6bf62231a3c5a 100644 --- a/google/cloud/servicemanagement/doc/main.dox +++ b/google/cloud/servicemanagement/doc/main.dox @@ -27,12 +27,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -40,9 +34,10 @@ can override the default policies. endpoint. - @ref servicemanagement-override-authentication - describes how to change the authentication credentials used by the library. +- @ref servicemanagement-override-retry - describes how to change the default retry + policies. - @ref servicemanagement-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/service-management -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/servicemanagement/doc/override-retry-policies.dox b/google/cloud/servicemanagement/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..db86d533a5a33 --- /dev/null +++ b/google/cloud/servicemanagement/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page servicemanagement-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 servicemanagement-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. + +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 servicemanagement-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 servicemanagement-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 servicemanagement-override-retry-example Example + + +For example, this will override the retry policies for `servicemanagement_v1::ServiceManagerClient`: + +@snippet service_manager_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet service_manager_client_samples.cc custom-idempotency-policy + + + + +@section servicemanagement-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 + +*/ + +// + +/*! @page servicemanagement_v1::ServiceManagerClient-retry-snippet Override servicemanagement_v1::ServiceManagerClient Retry Policies + +This shows how to override the retry policies for servicemanagement_v1::ServiceManagerClient: + +@snippet google/cloud/servicemanagement/v1/samples/service_manager_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/servicemanagement/v1/samples/service_manager_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/serviceusage/doc/main.dox b/google/cloud/serviceusage/doc/main.dox index 5abe2106b5aca..8c7afc14cc338 100644 --- a/google/cloud/serviceusage/doc/main.dox +++ b/google/cloud/serviceusage/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,9 +36,10 @@ can override the default policies. endpoint. - @ref serviceusage-override-authentication - describes how to change the authentication credentials used by the library. +- @ref serviceusage-override-retry - describes how to change the default retry + policies. - @ref serviceusage-env - describes environment variables that can configure the behavior of the library. [cloud-service]: https://cloud.google.com/service-usage -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/serviceusage/doc/override-retry-policies.dox b/google/cloud/serviceusage/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..2e1ecad306900 --- /dev/null +++ b/google/cloud/serviceusage/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page serviceusage-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 serviceusage-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. + +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 serviceusage-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 serviceusage-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 serviceusage-override-retry-example Example + + +For example, this will override the retry policies for `serviceusage_v1::ServiceUsageClient`: + +@snippet service_usage_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet service_usage_client_samples.cc custom-idempotency-policy + + + + +@section serviceusage-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 + +*/ + +// + +/*! @page serviceusage_v1::ServiceUsageClient-retry-snippet Override serviceusage_v1::ServiceUsageClient Retry Policies + +This shows how to override the retry policies for serviceusage_v1::ServiceUsageClient: + +@snippet google/cloud/serviceusage/v1/samples/service_usage_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/serviceusage/v1/samples/service_usage_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/shell/doc/main.dox b/google/cloud/shell/doc/main.dox index cb63f8ed9cbb6..e49a394f43c5f 100644 --- a/google/cloud/shell/doc/main.dox +++ b/google/cloud/shell/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,9 +36,10 @@ can override the default policies. endpoint. - @ref shell-override-authentication - describes how to change the authentication credentials used by the library. +- @ref shell-override-retry - describes how to change the default retry + policies. - @ref shell-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/shell -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/shell/doc/override-retry-policies.dox b/google/cloud/shell/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..c7ffe743d2a8e --- /dev/null +++ b/google/cloud/shell/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page shell-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 shell-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. + +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 shell-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 shell-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 shell-override-retry-example Example + + +For example, this will override the retry policies for `shell_v1::CloudShellServiceClient`: + +@snippet cloud_shell_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet cloud_shell_client_samples.cc custom-idempotency-policy + + + + +@section shell-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 + +*/ + +// + +/*! @page shell_v1::CloudShellServiceClient-retry-snippet Override shell_v1::CloudShellServiceClient Retry Policies + +This shows how to override the retry policies for shell_v1::CloudShellServiceClient: + +@snippet google/cloud/shell/v1/samples/cloud_shell_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/shell/v1/samples/cloud_shell_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/speech/doc/main.dox b/google/cloud/speech/doc/main.dox index 24536853191fe..a1e8e8e6448f3 100644 --- a/google/cloud/speech/doc/main.dox +++ b/google/cloud/speech/doc/main.dox @@ -34,12 +34,6 @@ application. - [\c speech_v2::SpeechClient](@ref google::cloud::speech_v2::SpeechClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -47,9 +41,10 @@ can override the default policies. endpoint. - @ref speech-override-authentication - describes how to change the authentication credentials used by the library. +- @ref speech-override-retry - describes how to change the default retry + policies. - @ref speech-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/speech -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/speech/doc/override-retry-policies.dox b/google/cloud/speech/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..4032c474db012 --- /dev/null +++ b/google/cloud/speech/doc/override-retry-policies.dox @@ -0,0 +1,122 @@ +/*! + +@page speech-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 speech-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. + +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 speech-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 speech-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 speech-override-retry-example Example + + +For example, this will override the retry policies for `speech_v1::SpeechClient`: + +@snippet speech_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet speech_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c speech_v1::SpeechClient](@ref speech_v1::SpeechClient-retry-snippet) +- [\c speech_v2::SpeechClient](@ref speech_v2::SpeechClient-retry-snippet) + + + +@section speech-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 + +*/ + +// + +/*! @page speech_v1::SpeechClient-retry-snippet Override speech_v1::SpeechClient Retry Policies + +This shows how to override the retry policies for speech_v1::SpeechClient: + +@snippet google/cloud/speech/v1/samples/speech_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/speech/v1/samples/speech_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page speech_v2::SpeechClient-retry-snippet Override speech_v2::SpeechClient Retry Policies + +This shows how to override the retry policies for speech_v2::SpeechClient: + +@snippet google/cloud/speech/v2/samples/speech_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/speech/v2/samples/speech_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/sql/doc/main.dox b/google/cloud/sql/doc/main.dox index 20c3e1252f65f..c53616a2bee11 100644 --- a/google/cloud/sql/doc/main.dox +++ b/google/cloud/sql/doc/main.dox @@ -44,12 +44,6 @@ application. - [\c sql_v1::SqlUsersServiceClient](@ref google::cloud::sql_v1::SqlUsersServiceClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -57,9 +51,10 @@ can override the default policies. endpoint. - @ref sql-override-authentication - describes how to change the authentication credentials used by the library. +- @ref sql-override-retry - describes how to change the default retry + policies. - @ref sql-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/sql -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/sql/doc/override-retry-policies.dox b/google/cloud/sql/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..f81827b4ce439 --- /dev/null +++ b/google/cloud/sql/doc/override-retry-policies.dox @@ -0,0 +1,213 @@ +/*! + +@page sql-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 sql-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. + +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 sql-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 sql-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 sql-override-retry-example Example + + +For example, this will override the retry policies for `sql_v1::SqlBackupRunsServiceClient`: + +@snippet sql_backup_runs_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet sql_backup_runs_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c sql_v1::SqlBackupRunsServiceClient](@ref sql_v1::SqlBackupRunsServiceClient-retry-snippet) +- [\c sql_v1::SqlConnectServiceClient](@ref sql_v1::SqlConnectServiceClient-retry-snippet) +- [\c sql_v1::SqlDatabasesServiceClient](@ref sql_v1::SqlDatabasesServiceClient-retry-snippet) +- [\c sql_v1::SqlFlagsServiceClient](@ref sql_v1::SqlFlagsServiceClient-retry-snippet) +- [\c sql_v1::SqlInstancesServiceClient](@ref sql_v1::SqlInstancesServiceClient-retry-snippet) +- [\c sql_v1::SqlOperationsServiceClient](@ref sql_v1::SqlOperationsServiceClient-retry-snippet) +- [\c sql_v1::SqlSslCertsServiceClient](@ref sql_v1::SqlSslCertsServiceClient-retry-snippet) +- [\c sql_v1::SqlTiersServiceClient](@ref sql_v1::SqlTiersServiceClient-retry-snippet) +- [\c sql_v1::SqlUsersServiceClient](@ref sql_v1::SqlUsersServiceClient-retry-snippet) + + + +@section sql-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 + +*/ + +// + +/*! @page sql_v1::SqlBackupRunsServiceClient-retry-snippet Override sql_v1::SqlBackupRunsServiceClient Retry Policies + +This shows how to override the retry policies for sql_v1::SqlBackupRunsServiceClient: + +@snippet google/cloud/sql/v1/samples/sql_backup_runs_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/sql/v1/samples/sql_backup_runs_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page sql_v1::SqlConnectServiceClient-retry-snippet Override sql_v1::SqlConnectServiceClient Retry Policies + +This shows how to override the retry policies for sql_v1::SqlConnectServiceClient: + +@snippet google/cloud/sql/v1/samples/sql_connect_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/sql/v1/samples/sql_connect_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page sql_v1::SqlDatabasesServiceClient-retry-snippet Override sql_v1::SqlDatabasesServiceClient Retry Policies + +This shows how to override the retry policies for sql_v1::SqlDatabasesServiceClient: + +@snippet google/cloud/sql/v1/samples/sql_databases_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/sql/v1/samples/sql_databases_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page sql_v1::SqlFlagsServiceClient-retry-snippet Override sql_v1::SqlFlagsServiceClient Retry Policies + +This shows how to override the retry policies for sql_v1::SqlFlagsServiceClient: + +@snippet google/cloud/sql/v1/samples/sql_flags_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/sql/v1/samples/sql_flags_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page sql_v1::SqlInstancesServiceClient-retry-snippet Override sql_v1::SqlInstancesServiceClient Retry Policies + +This shows how to override the retry policies for sql_v1::SqlInstancesServiceClient: + +@snippet google/cloud/sql/v1/samples/sql_instances_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/sql/v1/samples/sql_instances_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page sql_v1::SqlOperationsServiceClient-retry-snippet Override sql_v1::SqlOperationsServiceClient Retry Policies + +This shows how to override the retry policies for sql_v1::SqlOperationsServiceClient: + +@snippet google/cloud/sql/v1/samples/sql_operations_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/sql/v1/samples/sql_operations_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page sql_v1::SqlSslCertsServiceClient-retry-snippet Override sql_v1::SqlSslCertsServiceClient Retry Policies + +This shows how to override the retry policies for sql_v1::SqlSslCertsServiceClient: + +@snippet google/cloud/sql/v1/samples/sql_ssl_certs_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/sql/v1/samples/sql_ssl_certs_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page sql_v1::SqlTiersServiceClient-retry-snippet Override sql_v1::SqlTiersServiceClient Retry Policies + +This shows how to override the retry policies for sql_v1::SqlTiersServiceClient: + +@snippet google/cloud/sql/v1/samples/sql_tiers_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/sql/v1/samples/sql_tiers_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page sql_v1::SqlUsersServiceClient-retry-snippet Override sql_v1::SqlUsersServiceClient Retry Policies + +This shows how to override the retry policies for sql_v1::SqlUsersServiceClient: + +@snippet google/cloud/sql/v1/samples/sql_users_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/sql/v1/samples/sql_users_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/storageinsights/doc/main.dox b/google/cloud/storageinsights/doc/main.dox index c71d42016bef5..749b442f5468c 100644 --- a/google/cloud/storageinsights/doc/main.dox +++ b/google/cloud/storageinsights/doc/main.dox @@ -30,12 +30,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -43,9 +37,10 @@ can override the default policies. endpoint. - @ref storageinsights-override-authentication - describes how to change the authentication credentials used by the library. +- @ref storageinsights-override-retry - describes how to change the default retry + policies. - @ref storageinsights-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/storage/docs/insights/inventory-reports -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/storageinsights/doc/override-retry-policies.dox b/google/cloud/storageinsights/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..df16ab61ac0d2 --- /dev/null +++ b/google/cloud/storageinsights/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page storageinsights-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 storageinsights-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. + +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 storageinsights-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 storageinsights-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 storageinsights-override-retry-example Example + + +For example, this will override the retry policies for `storageinsights_v1::StorageInsightsClient`: + +@snippet storage_insights_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet storage_insights_client_samples.cc custom-idempotency-policy + + + + +@section storageinsights-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 + +*/ + +// + +/*! @page storageinsights_v1::StorageInsightsClient-retry-snippet Override storageinsights_v1::StorageInsightsClient Retry Policies + +This shows how to override the retry policies for storageinsights_v1::StorageInsightsClient: + +@snippet google/cloud/storageinsights/v1/samples/storage_insights_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/storageinsights/v1/samples/storage_insights_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/storagetransfer/doc/main.dox b/google/cloud/storagetransfer/doc/main.dox index 3617a20a55147..d6f6f770bcd0f 100644 --- a/google/cloud/storagetransfer/doc/main.dox +++ b/google/cloud/storagetransfer/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,9 +36,10 @@ can override the default policies. endpoint. - @ref storagetransfer-override-authentication - describes how to change the authentication credentials used by the library. +- @ref storagetransfer-override-retry - describes how to change the default retry + policies. - @ref storagetransfer-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/storage-transfer -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/storagetransfer/doc/override-retry-policies.dox b/google/cloud/storagetransfer/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..a096c7f78ee3b --- /dev/null +++ b/google/cloud/storagetransfer/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page storagetransfer-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 storagetransfer-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. + +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 storagetransfer-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 storagetransfer-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 storagetransfer-override-retry-example Example + + +For example, this will override the retry policies for `storagetransfer_v1::StorageTransferServiceClient`: + +@snippet storage_transfer_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet storage_transfer_client_samples.cc custom-idempotency-policy + + + + +@section storagetransfer-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 + +*/ + +// + +/*! @page storagetransfer_v1::StorageTransferServiceClient-retry-snippet Override storagetransfer_v1::StorageTransferServiceClient Retry Policies + +This shows how to override the retry policies for storagetransfer_v1::StorageTransferServiceClient: + +@snippet google/cloud/storagetransfer/v1/samples/storage_transfer_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/storagetransfer/v1/samples/storage_transfer_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/support/doc/main.dox b/google/cloud/support/doc/main.dox index ace5603a17b0b..818ed0b3bfce5 100644 --- a/google/cloud/support/doc/main.dox +++ b/google/cloud/support/doc/main.dox @@ -36,12 +36,6 @@ application. - [\c support_v2::CommentServiceClient](@ref google::cloud::support_v2::CommentServiceClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -49,9 +43,10 @@ can override the default policies. endpoint. - @ref support-override-authentication - describes how to change the authentication credentials used by the library. +- @ref support-override-retry - describes how to change the default retry + policies. - @ref support-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/support -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/support/doc/override-retry-policies.dox b/google/cloud/support/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..f9f5cff41c566 --- /dev/null +++ b/google/cloud/support/doc/override-retry-policies.dox @@ -0,0 +1,135 @@ +/*! + +@page support-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 support-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. + +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 support-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 support-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 support-override-retry-example Example + + +For example, this will override the retry policies for `support_v2::CaseAttachmentServiceClient`: + +@snippet case_attachment_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet case_attachment_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c support_v2::CaseAttachmentServiceClient](@ref support_v2::CaseAttachmentServiceClient-retry-snippet) +- [\c support_v2::CaseServiceClient](@ref support_v2::CaseServiceClient-retry-snippet) +- [\c support_v2::CommentServiceClient](@ref support_v2::CommentServiceClient-retry-snippet) + + + +@section support-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 + +*/ + +// + +/*! @page support_v2::CaseAttachmentServiceClient-retry-snippet Override support_v2::CaseAttachmentServiceClient Retry Policies + +This shows how to override the retry policies for support_v2::CaseAttachmentServiceClient: + +@snippet google/cloud/support/v2/samples/case_attachment_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/support/v2/samples/case_attachment_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page support_v2::CaseServiceClient-retry-snippet Override support_v2::CaseServiceClient Retry Policies + +This shows how to override the retry policies for support_v2::CaseServiceClient: + +@snippet google/cloud/support/v2/samples/case_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/support/v2/samples/case_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page support_v2::CommentServiceClient-retry-snippet Override support_v2::CommentServiceClient Retry Policies + +This shows how to override the retry policies for support_v2::CommentServiceClient: + +@snippet google/cloud/support/v2/samples/comment_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/support/v2/samples/comment_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/talent/doc/main.dox b/google/cloud/talent/doc/main.dox index 50040105c9ab2..860eb77a9e433 100644 --- a/google/cloud/talent/doc/main.dox +++ b/google/cloud/talent/doc/main.dox @@ -38,12 +38,6 @@ application. - [\c talent_v4::TenantServiceClient](@ref google::cloud::talent_v4::TenantServiceClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -51,9 +45,10 @@ can override the default policies. endpoint. - @ref talent-override-authentication - describes how to change the authentication credentials used by the library. +- @ref talent-override-retry - describes how to change the default retry + policies. - @ref talent-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/solutions/talent-solution -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/talent/doc/override-retry-policies.dox b/google/cloud/talent/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..b64cdb0c57643 --- /dev/null +++ b/google/cloud/talent/doc/override-retry-policies.dox @@ -0,0 +1,161 @@ +/*! + +@page talent-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 talent-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. + +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 talent-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 talent-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 talent-override-retry-example Example + + +For example, this will override the retry policies for `talent_v4::CompanyServiceClient`: + +@snippet company_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet company_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c talent_v4::CompanyServiceClient](@ref talent_v4::CompanyServiceClient-retry-snippet) +- [\c talent_v4::CompletionClient](@ref talent_v4::CompletionClient-retry-snippet) +- [\c talent_v4::EventServiceClient](@ref talent_v4::EventServiceClient-retry-snippet) +- [\c talent_v4::JobServiceClient](@ref talent_v4::JobServiceClient-retry-snippet) +- [\c talent_v4::TenantServiceClient](@ref talent_v4::TenantServiceClient-retry-snippet) + + + +@section talent-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 + +*/ + +// + +/*! @page talent_v4::CompanyServiceClient-retry-snippet Override talent_v4::CompanyServiceClient Retry Policies + +This shows how to override the retry policies for talent_v4::CompanyServiceClient: + +@snippet google/cloud/talent/v4/samples/company_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/talent/v4/samples/company_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page talent_v4::CompletionClient-retry-snippet Override talent_v4::CompletionClient Retry Policies + +This shows how to override the retry policies for talent_v4::CompletionClient: + +@snippet google/cloud/talent/v4/samples/completion_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/talent/v4/samples/completion_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page talent_v4::EventServiceClient-retry-snippet Override talent_v4::EventServiceClient Retry Policies + +This shows how to override the retry policies for talent_v4::EventServiceClient: + +@snippet google/cloud/talent/v4/samples/event_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/talent/v4/samples/event_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page talent_v4::JobServiceClient-retry-snippet Override talent_v4::JobServiceClient Retry Policies + +This shows how to override the retry policies for talent_v4::JobServiceClient: + +@snippet google/cloud/talent/v4/samples/job_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/talent/v4/samples/job_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page talent_v4::TenantServiceClient-retry-snippet Override talent_v4::TenantServiceClient Retry Policies + +This shows how to override the retry policies for talent_v4::TenantServiceClient: + +@snippet google/cloud/talent/v4/samples/tenant_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/talent/v4/samples/tenant_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/tasks/doc/main.dox b/google/cloud/tasks/doc/main.dox index 8e951396e07b0..23f80de7b88e0 100644 --- a/google/cloud/tasks/doc/main.dox +++ b/google/cloud/tasks/doc/main.dox @@ -30,12 +30,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -43,8 +37,9 @@ can override the default policies. endpoint. - @ref tasks-override-authentication - describes how to change the authentication credentials used by the library. +- @ref tasks-override-retry - describes how to change the default retry + policies. - @ref tasks-env - describes environment variables that can configure the behavior of the library. -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/tasks/doc/override-retry-policies.dox b/google/cloud/tasks/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..4575e3778a577 --- /dev/null +++ b/google/cloud/tasks/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page tasks-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 tasks-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. + +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 tasks-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 tasks-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 tasks-override-retry-example Example + + +For example, this will override the retry policies for `tasks_v2::CloudTasksClient`: + +@snippet cloud_tasks_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet cloud_tasks_client_samples.cc custom-idempotency-policy + + + + +@section tasks-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 + +*/ + +// + +/*! @page tasks_v2::CloudTasksClient-retry-snippet Override tasks_v2::CloudTasksClient Retry Policies + +This shows how to override the retry policies for tasks_v2::CloudTasksClient: + +@snippet google/cloud/tasks/v2/samples/cloud_tasks_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/tasks/v2/samples/cloud_tasks_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/texttospeech/doc/main.dox b/google/cloud/texttospeech/doc/main.dox index f95b2b947744f..6abd155535424 100644 --- a/google/cloud/texttospeech/doc/main.dox +++ b/google/cloud/texttospeech/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,9 +36,10 @@ can override the default policies. endpoint. - @ref texttospeech-override-authentication - describes how to change the authentication credentials used by the library. +- @ref texttospeech-override-retry - describes how to change the default retry + policies. - @ref texttospeech-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/text-to-speech -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/texttospeech/doc/override-retry-policies.dox b/google/cloud/texttospeech/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..8199338a3dc50 --- /dev/null +++ b/google/cloud/texttospeech/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page texttospeech-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 texttospeech-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. + +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 texttospeech-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 texttospeech-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 texttospeech-override-retry-example Example + + +For example, this will override the retry policies for `texttospeech_v1::TextToSpeechClient`: + +@snippet text_to_speech_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet text_to_speech_client_samples.cc custom-idempotency-policy + + + + +@section texttospeech-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 + +*/ + +// + +/*! @page texttospeech_v1::TextToSpeechClient-retry-snippet Override texttospeech_v1::TextToSpeechClient Retry Policies + +This shows how to override the retry policies for texttospeech_v1::TextToSpeechClient: + +@snippet google/cloud/texttospeech/v1/samples/text_to_speech_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/texttospeech/v1/samples/text_to_speech_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/timeseriesinsights/doc/main.dox b/google/cloud/timeseriesinsights/doc/main.dox index c9e3e142d50d8..280630e71f7fb 100644 --- a/google/cloud/timeseriesinsights/doc/main.dox +++ b/google/cloud/timeseriesinsights/doc/main.dox @@ -33,12 +33,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -46,10 +40,11 @@ can override the default policies. endpoint. - @ref timeseriesinsights-override-authentication - describes how to change the authentication credentials used by the library. +- @ref timeseriesinsights-override-retry - describes how to change the default retry + policies. - @ref timeseriesinsights-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/timeseries-insights -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/timeseriesinsights/doc/override-retry-policies.dox b/google/cloud/timeseriesinsights/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..998ec9363337f --- /dev/null +++ b/google/cloud/timeseriesinsights/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page timeseriesinsights-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 timeseriesinsights-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. + +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 timeseriesinsights-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 timeseriesinsights-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 timeseriesinsights-override-retry-example Example + + +For example, this will override the retry policies for `timeseriesinsights_v1::TimeseriesInsightsControllerClient`: + +@snippet timeseries_insights_controller_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet timeseries_insights_controller_client_samples.cc custom-idempotency-policy + + + + +@section timeseriesinsights-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 + +*/ + +// + +/*! @page timeseriesinsights_v1::TimeseriesInsightsControllerClient-retry-snippet Override timeseriesinsights_v1::TimeseriesInsightsControllerClient Retry Policies + +This shows how to override the retry policies for timeseriesinsights_v1::TimeseriesInsightsControllerClient: + +@snippet google/cloud/timeseriesinsights/v1/samples/timeseries_insights_controller_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/timeseriesinsights/v1/samples/timeseries_insights_controller_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/tpu/doc/main.dox b/google/cloud/tpu/doc/main.dox index dbb2ebc93e65d..bd9e3b8db7c1b 100644 --- a/google/cloud/tpu/doc/main.dox +++ b/google/cloud/tpu/doc/main.dox @@ -35,12 +35,6 @@ application. - [\c tpu_v2::TpuClient](@ref google::cloud::tpu_v2::TpuClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -48,9 +42,10 @@ can override the default policies. endpoint. - @ref tpu-override-authentication - describes how to change the authentication credentials used by the library. +- @ref tpu-override-retry - describes how to change the default retry + policies. - @ref tpu-env - describes environment variables that can configure the behavior of the library. [cloud-service]: https://cloud.google.com/tpu -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/tpu/doc/override-retry-policies.dox b/google/cloud/tpu/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..341291f034f2c --- /dev/null +++ b/google/cloud/tpu/doc/override-retry-policies.dox @@ -0,0 +1,122 @@ +/*! + +@page tpu-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 tpu-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. + +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 tpu-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 tpu-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 tpu-override-retry-example Example + + +For example, this will override the retry policies for `tpu_v1::TpuClient`: + +@snippet tpu_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet tpu_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c tpu_v1::TpuClient](@ref tpu_v1::TpuClient-retry-snippet) +- [\c tpu_v2::TpuClient](@ref tpu_v2::TpuClient-retry-snippet) + + + +@section tpu-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 + +*/ + +// + +/*! @page tpu_v1::TpuClient-retry-snippet Override tpu_v1::TpuClient Retry Policies + +This shows how to override the retry policies for tpu_v1::TpuClient: + +@snippet google/cloud/tpu/v1/samples/tpu_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/tpu/v1/samples/tpu_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page tpu_v2::TpuClient-retry-snippet Override tpu_v2::TpuClient Retry Policies + +This shows how to override the retry policies for tpu_v2::TpuClient: + +@snippet google/cloud/tpu/v2/samples/tpu_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/tpu/v2/samples/tpu_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/trace/doc/main.dox b/google/cloud/trace/doc/main.dox index a0193c2b55fa7..a13faab6993ea 100644 --- a/google/cloud/trace/doc/main.dox +++ b/google/cloud/trace/doc/main.dox @@ -37,12 +37,6 @@ application. - [\c trace_v2::TraceServiceClient](@ref google::cloud::trace_v2::TraceServiceClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -50,9 +44,10 @@ can override the default policies. endpoint. - @ref trace-override-authentication - describes how to change the authentication credentials used by the library. +- @ref trace-override-retry - describes how to change the default retry + policies. - @ref trace-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/trace -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/trace/doc/override-retry-policies.dox b/google/cloud/trace/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..4a72555f732e9 --- /dev/null +++ b/google/cloud/trace/doc/override-retry-policies.dox @@ -0,0 +1,122 @@ +/*! + +@page trace-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 trace-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. + +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 trace-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 trace-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 trace-override-retry-example Example + + +For example, this will override the retry policies for `trace_v1::TraceServiceClient`: + +@snippet trace_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet trace_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c trace_v1::TraceServiceClient](@ref trace_v1::TraceServiceClient-retry-snippet) +- [\c trace_v2::TraceServiceClient](@ref trace_v2::TraceServiceClient-retry-snippet) + + + +@section trace-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 + +*/ + +// + +/*! @page trace_v1::TraceServiceClient-retry-snippet Override trace_v1::TraceServiceClient Retry Policies + +This shows how to override the retry policies for trace_v1::TraceServiceClient: + +@snippet google/cloud/trace/v1/samples/trace_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/trace/v1/samples/trace_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page trace_v2::TraceServiceClient-retry-snippet Override trace_v2::TraceServiceClient Retry Policies + +This shows how to override the retry policies for trace_v2::TraceServiceClient: + +@snippet google/cloud/trace/v2/samples/trace_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/trace/v2/samples/trace_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/translate/doc/main.dox b/google/cloud/translate/doc/main.dox index 42b8027c5ffb2..c5e01821a6ec3 100644 --- a/google/cloud/translate/doc/main.dox +++ b/google/cloud/translate/doc/main.dox @@ -28,12 +28,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -41,9 +35,10 @@ can override the default policies. endpoint. - @ref translate-override-authentication - describes how to change the authentication credentials used by the library. +- @ref translate-override-retry - describes how to change the default retry + policies. - @ref translate-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/translate -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/translate/doc/override-retry-policies.dox b/google/cloud/translate/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..1b5e54d29a4e0 --- /dev/null +++ b/google/cloud/translate/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page translate-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 translate-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. + +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 translate-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 translate-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 translate-override-retry-example Example + + +For example, this will override the retry policies for `translate_v3::TranslationServiceClient`: + +@snippet translation_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet translation_client_samples.cc custom-idempotency-policy + + + + +@section translate-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 + +*/ + +// + +/*! @page translate_v3::TranslationServiceClient-retry-snippet Override translate_v3::TranslationServiceClient Retry Policies + +This shows how to override the retry policies for translate_v3::TranslationServiceClient: + +@snippet google/cloud/translate/v3/samples/translation_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/translate/v3/samples/translation_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/video/doc/main.dox b/google/cloud/video/doc/main.dox index aaf4b804b9f9e..b745661940663 100644 --- a/google/cloud/video/doc/main.dox +++ b/google/cloud/video/doc/main.dox @@ -42,12 +42,6 @@ application. - [\c video_transcoder_v1::TranscoderServiceClient](@ref google::cloud::video_transcoder_v1::TranscoderServiceClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -55,11 +49,12 @@ can override the default policies. endpoint. - @ref video-override-authentication - describes how to change the authentication credentials used by the library. +- @ref video-override-retry - describes how to change the default retry + policies. - @ref video-env - describes environment variables that can configure the behavior of the library. [livestream-service-docs]: https://cloud.google.com/livestream [transcoder-service-docs]: https://cloud.google.com/transcoder [stitcher-service-docs]: https://cloud.google.com/video-stitcher -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/video/doc/override-retry-policies.dox b/google/cloud/video/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..b01a65d763432 --- /dev/null +++ b/google/cloud/video/doc/override-retry-policies.dox @@ -0,0 +1,135 @@ +/*! + +@page video-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 video-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. + +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 video-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 video-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 video-override-retry-example Example + + +For example, this will override the retry policies for `video_livestream_v1::LivestreamServiceClient`: + +@snippet livestream_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet livestream_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c video_livestream_v1::LivestreamServiceClient](@ref video_livestream_v1::LivestreamServiceClient-retry-snippet) +- [\c video_stitcher_v1::VideoStitcherServiceClient](@ref video_stitcher_v1::VideoStitcherServiceClient-retry-snippet) +- [\c video_transcoder_v1::TranscoderServiceClient](@ref video_transcoder_v1::TranscoderServiceClient-retry-snippet) + + + +@section video-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 + +*/ + +// + +/*! @page video_livestream_v1::LivestreamServiceClient-retry-snippet Override video_livestream_v1::LivestreamServiceClient Retry Policies + +This shows how to override the retry policies for video_livestream_v1::LivestreamServiceClient: + +@snippet google/cloud/video/livestream/v1/samples/livestream_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/video/livestream/v1/samples/livestream_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page video_stitcher_v1::VideoStitcherServiceClient-retry-snippet Override video_stitcher_v1::VideoStitcherServiceClient Retry Policies + +This shows how to override the retry policies for video_stitcher_v1::VideoStitcherServiceClient: + +@snippet google/cloud/video/stitcher/v1/samples/video_stitcher_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/video/stitcher/v1/samples/video_stitcher_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page video_transcoder_v1::TranscoderServiceClient-retry-snippet Override video_transcoder_v1::TranscoderServiceClient Retry Policies + +This shows how to override the retry policies for video_transcoder_v1::TranscoderServiceClient: + +@snippet google/cloud/video/transcoder/v1/samples/transcoder_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/video/transcoder/v1/samples/transcoder_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/videointelligence/doc/main.dox b/google/cloud/videointelligence/doc/main.dox index ce6a9c42b4a53..20b252ecba202 100644 --- a/google/cloud/videointelligence/doc/main.dox +++ b/google/cloud/videointelligence/doc/main.dox @@ -30,12 +30,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -43,9 +37,10 @@ can override the default policies. endpoint. - @ref videointelligence-override-authentication - describes how to change the authentication credentials used by the library. +- @ref videointelligence-override-retry - describes how to change the default retry + policies. - @ref videointelligence-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/videointelligence -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/videointelligence/doc/override-retry-policies.dox b/google/cloud/videointelligence/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..7897609bc93b9 --- /dev/null +++ b/google/cloud/videointelligence/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page videointelligence-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 videointelligence-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. + +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 videointelligence-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 videointelligence-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 videointelligence-override-retry-example Example + + +For example, this will override the retry policies for `videointelligence_v1::VideoIntelligenceServiceClient`: + +@snippet video_intelligence_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet video_intelligence_client_samples.cc custom-idempotency-policy + + + + +@section videointelligence-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 + +*/ + +// + +/*! @page videointelligence_v1::VideoIntelligenceServiceClient-retry-snippet Override videointelligence_v1::VideoIntelligenceServiceClient Retry Policies + +This shows how to override the retry policies for videointelligence_v1::VideoIntelligenceServiceClient: + +@snippet google/cloud/videointelligence/v1/samples/video_intelligence_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/videointelligence/v1/samples/video_intelligence_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/vision/doc/main.dox b/google/cloud/vision/doc/main.dox index 8834fdc6d8935..3d86741f8c674 100644 --- a/google/cloud/vision/doc/main.dox +++ b/google/cloud/vision/doc/main.dox @@ -36,12 +36,6 @@ application. - [\c vision_v1::ProductSearchClient](@ref google::cloud::vision_v1::ProductSearchClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -49,9 +43,10 @@ can override the default policies. endpoint. - @ref vision-override-authentication - describes how to change the authentication credentials used by the library. +- @ref vision-override-retry - describes how to change the default retry + policies. - @ref vision-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/vision -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/vision/doc/override-retry-policies.dox b/google/cloud/vision/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..31043e4f21fe6 --- /dev/null +++ b/google/cloud/vision/doc/override-retry-policies.dox @@ -0,0 +1,122 @@ +/*! + +@page vision-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 vision-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. + +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 vision-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 vision-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 vision-override-retry-example Example + + +For example, this will override the retry policies for `vision_v1::ImageAnnotatorClient`: + +@snippet image_annotator_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet image_annotator_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c vision_v1::ImageAnnotatorClient](@ref vision_v1::ImageAnnotatorClient-retry-snippet) +- [\c vision_v1::ProductSearchClient](@ref vision_v1::ProductSearchClient-retry-snippet) + + + +@section vision-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 + +*/ + +// + +/*! @page vision_v1::ImageAnnotatorClient-retry-snippet Override vision_v1::ImageAnnotatorClient Retry Policies + +This shows how to override the retry policies for vision_v1::ImageAnnotatorClient: + +@snippet google/cloud/vision/v1/samples/image_annotator_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/vision/v1/samples/image_annotator_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page vision_v1::ProductSearchClient-retry-snippet Override vision_v1::ProductSearchClient Retry Policies + +This shows how to override the retry policies for vision_v1::ProductSearchClient: + +@snippet google/cloud/vision/v1/samples/product_search_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/vision/v1/samples/product_search_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/vmmigration/doc/main.dox b/google/cloud/vmmigration/doc/main.dox index 658e9860be4a8..2e2c3ed2a8597 100644 --- a/google/cloud/vmmigration/doc/main.dox +++ b/google/cloud/vmmigration/doc/main.dox @@ -28,12 +28,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -41,9 +35,10 @@ can override the default policies. endpoint. - @ref vmmigration-override-authentication - describes how to change the authentication credentials used by the library. +- @ref vmmigration-override-retry - describes how to change the default retry + policies. - @ref vmmigration-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/migrate/compute-engine -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/vmmigration/doc/override-retry-policies.dox b/google/cloud/vmmigration/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..1e3ff64b8824c --- /dev/null +++ b/google/cloud/vmmigration/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page vmmigration-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 vmmigration-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. + +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 vmmigration-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 vmmigration-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 vmmigration-override-retry-example Example + + +For example, this will override the retry policies for `vmmigration_v1::VmMigrationClient`: + +@snippet vm_migration_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet vm_migration_client_samples.cc custom-idempotency-policy + + + + +@section vmmigration-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 + +*/ + +// + +/*! @page vmmigration_v1::VmMigrationClient-retry-snippet Override vmmigration_v1::VmMigrationClient Retry Policies + +This shows how to override the retry policies for vmmigration_v1::VmMigrationClient: + +@snippet google/cloud/vmmigration/v1/samples/vm_migration_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/vmmigration/v1/samples/vm_migration_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/vmwareengine/doc/main.dox b/google/cloud/vmwareengine/doc/main.dox index 817df49474e08..af4df0658d075 100644 --- a/google/cloud/vmwareengine/doc/main.dox +++ b/google/cloud/vmwareengine/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,9 +36,10 @@ can override the default policies. endpoint. - @ref vmwareengine-override-authentication - describes how to change the authentication credentials used by the library. +- @ref vmwareengine-override-retry - describes how to change the default retry + policies. - @ref vmwareengine-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/vmware-engine -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/vmwareengine/doc/override-retry-policies.dox b/google/cloud/vmwareengine/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..46771802d2583 --- /dev/null +++ b/google/cloud/vmwareengine/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page vmwareengine-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 vmwareengine-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. + +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 vmwareengine-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 vmwareengine-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 vmwareengine-override-retry-example Example + + +For example, this will override the retry policies for `vmwareengine_v1::VmwareEngineClient`: + +@snippet vmware_engine_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet vmware_engine_client_samples.cc custom-idempotency-policy + + + + +@section vmwareengine-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 + +*/ + +// + +/*! @page vmwareengine_v1::VmwareEngineClient-retry-snippet Override vmwareengine_v1::VmwareEngineClient Retry Policies + +This shows how to override the retry policies for vmwareengine_v1::VmwareEngineClient: + +@snippet google/cloud/vmwareengine/v1/samples/vmware_engine_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/vmwareengine/v1/samples/vmware_engine_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/vpcaccess/doc/main.dox b/google/cloud/vpcaccess/doc/main.dox index fa1f65723dcee..f91c9895f8897 100644 --- a/google/cloud/vpcaccess/doc/main.dox +++ b/google/cloud/vpcaccess/doc/main.dox @@ -28,12 +28,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -41,9 +35,10 @@ can override the default policies. endpoint. - @ref vpcaccess-override-authentication - describes how to change the authentication credentials used by the library. +- @ref vpcaccess-override-retry - describes how to change the default retry + policies. - @ref vpcaccess-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/vpc/docs/serverless-vpc-access -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/vpcaccess/doc/override-retry-policies.dox b/google/cloud/vpcaccess/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..db5f061cd4cfd --- /dev/null +++ b/google/cloud/vpcaccess/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page vpcaccess-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 vpcaccess-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. + +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 vpcaccess-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 vpcaccess-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 vpcaccess-override-retry-example Example + + +For example, this will override the retry policies for `vpcaccess_v1::VpcAccessServiceClient`: + +@snippet vpc_access_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet vpc_access_client_samples.cc custom-idempotency-policy + + + + +@section vpcaccess-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 + +*/ + +// + +/*! @page vpcaccess_v1::VpcAccessServiceClient-retry-snippet Override vpcaccess_v1::VpcAccessServiceClient Retry Policies + +This shows how to override the retry policies for vpcaccess_v1::VpcAccessServiceClient: + +@snippet google/cloud/vpcaccess/v1/samples/vpc_access_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/vpcaccess/v1/samples/vpc_access_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/webrisk/doc/main.dox b/google/cloud/webrisk/doc/main.dox index ab9aa7e35eaba..d787bb43eab2f 100644 --- a/google/cloud/webrisk/doc/main.dox +++ b/google/cloud/webrisk/doc/main.dox @@ -29,12 +29,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -42,8 +36,9 @@ can override the default policies. endpoint. - @ref webrisk-override-authentication - describes how to change the authentication credentials used by the library. +- @ref webrisk-override-retry - describes how to change the default retry + policies. - @ref webrisk-env - describes environment variables that can configure the behavior of the library. -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/webrisk/doc/override-retry-policies.dox b/google/cloud/webrisk/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..2864e478280d0 --- /dev/null +++ b/google/cloud/webrisk/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page webrisk-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 webrisk-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. + +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 webrisk-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 webrisk-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 webrisk-override-retry-example Example + + +For example, this will override the retry policies for `webrisk_v1::WebRiskServiceClient`: + +@snippet web_risk_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet web_risk_client_samples.cc custom-idempotency-policy + + + + +@section webrisk-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 + +*/ + +// + +/*! @page webrisk_v1::WebRiskServiceClient-retry-snippet Override webrisk_v1::WebRiskServiceClient Retry Policies + +This shows how to override the retry policies for webrisk_v1::WebRiskServiceClient: + +@snippet google/cloud/webrisk/v1/samples/web_risk_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/webrisk/v1/samples/web_risk_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/websecurityscanner/doc/main.dox b/google/cloud/websecurityscanner/doc/main.dox index 469768734f3f0..7094475fcc9c7 100644 --- a/google/cloud/websecurityscanner/doc/main.dox +++ b/google/cloud/websecurityscanner/doc/main.dox @@ -30,12 +30,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -43,8 +37,9 @@ can override the default policies. endpoint. - @ref websecurityscanner-override-authentication - describes how to change the authentication credentials used by the library. +- @ref websecurityscanner-override-retry - describes how to change the default retry + policies. - @ref websecurityscanner-env - describes environment variables that can configure the behavior of the library. -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/websecurityscanner/doc/override-retry-policies.dox b/google/cloud/websecurityscanner/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..5dfa867aedf9f --- /dev/null +++ b/google/cloud/websecurityscanner/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page websecurityscanner-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 websecurityscanner-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. + +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 websecurityscanner-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 websecurityscanner-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 websecurityscanner-override-retry-example Example + + +For example, this will override the retry policies for `websecurityscanner_v1::WebSecurityScannerClient`: + +@snippet web_security_scanner_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet web_security_scanner_client_samples.cc custom-idempotency-policy + + + + +@section websecurityscanner-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 + +*/ + +// + +/*! @page websecurityscanner_v1::WebSecurityScannerClient-retry-snippet Override websecurityscanner_v1::WebSecurityScannerClient Retry Policies + +This shows how to override the retry policies for websecurityscanner_v1::WebSecurityScannerClient: + +@snippet google/cloud/websecurityscanner/v1/samples/web_security_scanner_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/websecurityscanner/v1/samples/web_security_scanner_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/workflows/doc/main.dox b/google/cloud/workflows/doc/main.dox index dc111c669f9ca..fd38fcc46de85 100644 --- a/google/cloud/workflows/doc/main.dox +++ b/google/cloud/workflows/doc/main.dox @@ -35,12 +35,6 @@ application. - [\c workflows_v1::WorkflowsClient](@ref google::cloud::workflows_v1::WorkflowsClient) -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -48,8 +42,9 @@ can override the default policies. endpoint. - @ref workflows-override-authentication - describes how to change the authentication credentials used by the library. +- @ref workflows-override-retry - describes how to change the default retry + policies. - @ref workflows-env - describes environment variables that can configure the behavior of the library. -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/workflows/doc/override-retry-policies.dox b/google/cloud/workflows/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..68e137c617b1f --- /dev/null +++ b/google/cloud/workflows/doc/override-retry-policies.dox @@ -0,0 +1,122 @@ +/*! + +@page workflows-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 workflows-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. + +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 workflows-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 workflows-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 workflows-override-retry-example Example + + +For example, this will override the retry policies for `workflows_executions_v1::ExecutionsClient`: + +@snippet executions_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet executions_client_samples.cc custom-idempotency-policy + + +Follow these links to find examples for other \c *Client classes: + +- [\c workflows_executions_v1::ExecutionsClient](@ref workflows_executions_v1::ExecutionsClient-retry-snippet) +- [\c workflows_v1::WorkflowsClient](@ref workflows_v1::WorkflowsClient-retry-snippet) + + + +@section workflows-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 + +*/ + +// + +/*! @page workflows_executions_v1::ExecutionsClient-retry-snippet Override workflows_executions_v1::ExecutionsClient Retry Policies + +This shows how to override the retry policies for workflows_executions_v1::ExecutionsClient: + +@snippet google/cloud/workflows/executions/v1/samples/executions_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/workflows/executions/v1/samples/executions_client_samples.cc custom-idempotency-policy + +*/ + +/*! @page workflows_v1::WorkflowsClient-retry-snippet Override workflows_v1::WorkflowsClient Retry Policies + +This shows how to override the retry policies for workflows_v1::WorkflowsClient: + +@snippet google/cloud/workflows/v1/samples/workflows_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/workflows/v1/samples/workflows_client_samples.cc custom-idempotency-policy + +*/ +// diff --git a/google/cloud/workstations/doc/main.dox b/google/cloud/workstations/doc/main.dox index b8d218f066c1e..4c59202bd3960 100644 --- a/google/cloud/workstations/doc/main.dox +++ b/google/cloud/workstations/doc/main.dox @@ -31,12 +31,6 @@ parameters, and infrastructure to mock application. -## Retry, Backoff, and Idempotency Policies. - -The library automatically retries requests that fail with transient errors, and -uses [exponential backoff] to backoff between retries. Application developers -can override the default policies. - ## More Information - @ref common-error-handling - describes how the library reports errors. @@ -44,9 +38,10 @@ can override the default policies. endpoint. - @ref workstations-override-authentication - describes how to change the authentication credentials used by the library. +- @ref workstations-override-retry - describes how to change the default retry + policies. - @ref workstations-env - describes environment variables that can configure the behavior of the library. [cloud-service-docs]: https://cloud.google.com/workstations -[exponential backoff]: https://en.wikipedia.org/wiki/Exponential_backoff */ diff --git a/google/cloud/workstations/doc/override-retry-policies.dox b/google/cloud/workstations/doc/override-retry-policies.dox new file mode 100644 index 0000000000000..23b5063ce5655 --- /dev/null +++ b/google/cloud/workstations/doc/override-retry-policies.dox @@ -0,0 +1,105 @@ +/*! + +@page workstations-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 workstations-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. + +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 workstations-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 workstations-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 workstations-override-retry-example Example + + +For example, this will override the retry policies for `workstations_v1::WorkstationsClient`: + +@snippet workstations_client_samples.cc set-retry-policy + +This assumes you have created a custom idempotency policy. Such as: + +@snippet workstations_client_samples.cc custom-idempotency-policy + + + + +@section workstations-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 + +*/ + +// + +/*! @page workstations_v1::WorkstationsClient-retry-snippet Override workstations_v1::WorkstationsClient Retry Policies + +This shows how to override the retry policies for workstations_v1::WorkstationsClient: + +@snippet google/cloud/workstations/v1/samples/workstations_client_samples.cc set-retry-policy + +Assuming you have created a custom idempotency policy. Such as: + +@snippet google/cloud/workstations/v1/samples/workstations_client_samples.cc custom-idempotency-policy + +*/ +//