Module retry_throttler 

Defines traits for retry throttling and some common implementations.

The client libraries can be configured to automatically retry RPCs. Most often retries are only enabled if (1) the request was never sent and the local error is recoverable, or (2) the failure is a transient errors and the RPC is idempotent.

Retry strategies that do not throttle themselves can slow down recovery when the service is overloaded, or when recovering from a large incident. This is also known as “retry storms”: the retry attempts can grow to be more than the normal traffic and hinder recovery.

Advanced applications may want to configure a retry throttler to Address Cascading Failures and when Handling Overload conditions. This module contains the traits and some implementations of retry throttling strategies.

To configure the default throttler for a client, use ClientBuilder::with_retry_throttler. To configure the throttler used for a specific request, use RequestOptionsBuilder::with_retry_throttler.

Typically applications should create one retry throttler and share it across multiple clients.

Example

Stochastically reject calls based on observed failure rates:

let throttler = AdaptiveThrottler::new(2.0)?;

Reject calls if the success rate is too low:

let tokens = 1000;
let min_tokens = 250;
let error_cost = 10;
let throttler = CircuitBreaker::new(tokens, min_tokens, error_cost)?;

Structs

AdaptiveThrottler

Implements a probabilistic throttler based on observed failure rates.

CircuitBreaker

A CircuitBreaker throttler rejects retry attempts if the success rate is too low.

RetryThrottlerArg

A helper type to use RetryThrottler in client and request options.

Enums

Error

The error type for throttler policy creation. Errors that can occur when building a retry throttler.

Traits

RetryThrottler

Implementations of this trait prevent a client from sending too many retries.

Type Aliases

SharedRetryThrottler

Retry throttlers are shared by many clients, so they are wrapped in Arc<>. Consequently, they are used from many threads at the same time, so they are wrapped in Mutex.