Struct RetryBuilder

Source

pub struct RetryBuilder<E = BoxError> { /* private fields */ }

Expand description

Builder for Retry.

The generic parameter E is the operation error type preserved inside AttemptFailure::Error. Failure listeners may observe failures, override the retry decision, or return AttemptFailureDecision::UseDefault to let the policy decide from configured limits and delay strategy.

Implementations§

Source §

impl<E> RetryBuilder<E>

Source

pub fn new() -> Self

Creates a builder with default options and no listeners.

§Returns

A retry builder using RetryOptions::default.

Source

pub fn options(self, options: RetryOptions) -> Self

Replaces all retry options.

§Parameters

options: Retry option snapshot.

§Returns

The updated builder.

Source

pub fn max_attempts(self, max_attempts: u32) -> Self

Sets the maximum total attempts, including the initial attempt.

§Parameters

max_attempts: Maximum attempts. Zero is recorded as a build error.

§Returns

The updated builder.

Source

pub fn max_retries(self, max_retries: u32) -> Self

Sets the maximum retry count after the initial attempt.

§Parameters

max_retries: Number of retries after the first attempt.

§Returns

The updated builder.

Source

pub fn max_operation_elapsed( self, max_operation_elapsed: Option<Duration>, ) -> Self

Sets the maximum cumulative user operation time.

§Parameters

max_operation_elapsed: Optional cumulative user operation time budget.

§Returns

The updated builder.

Source

pub fn max_total_elapsed(self, max_total_elapsed: Option<Duration>) -> Self

Sets the maximum total monotonic retry-flow elapsed time.

§Parameters

max_total_elapsed: Optional total retry-flow time budget. Operation execution, retry sleeps, retry-after sleeps, and retry control-path listener time are included.

§Returns

The updated builder.

Source

pub fn delay(self, delay: RetryDelay) -> Self

Sets the retry delay strategy.

§Parameters

delay: Base delay strategy used between attempts.

§Returns

The updated builder.

Source

pub fn no_delay(self) -> Self

Configures immediate retries with no sleep.

§Returns

The updated builder.

Source

pub fn fixed_delay(self, delay: Duration) -> Self

Configures a fixed retry delay.

§Parameters

delay: Delay slept before each retry.

§Returns

The updated builder.

Source

pub fn random_delay(self, min: Duration, max: Duration) -> Self

Configures a random retry delay range.

§Parameters

min: Inclusive lower delay bound.
max: Inclusive upper delay bound.

§Returns

The updated builder.

Source

pub fn exponential_backoff(self, initial: Duration, max: Duration) -> Self

Configures exponential backoff with the default multiplier 2.0.

§Parameters

initial: First retry delay.
max: Maximum retry delay.

§Returns

The updated builder.

Source

pub fn exponential_backoff_with_multiplier( self, initial: Duration, max: Duration, multiplier: f64, ) -> Self

Configures exponential backoff with a custom multiplier.

§Parameters

initial: First retry delay.
max: Maximum retry delay.
multiplier: Multiplier applied after each failed attempt.

§Returns

The updated builder.

Source

pub fn jitter(self, jitter: RetryJitter) -> Self

Sets the jitter strategy.

§Parameters

jitter: Jitter strategy applied to base delays.

§Returns

The updated builder.

Source

pub fn jitter_factor(self, factor: f64) -> Self

Sets relative jitter by factor.

§Parameters

factor: Relative jitter factor in [0.0, 1.0].

§Returns

The updated builder.

Source

pub fn attempt_timeout(self, attempt_timeout: Option<Duration>) -> Self

Sets a per-attempt timeout.

§Parameters

attempt_timeout: Timeout applied by run_async, run_in_worker, and run_blocking_with_timeout. None disables per-attempt timeout.

§Returns

The updated builder.

Source

pub fn attempt_timeout_option( self, attempt_timeout: Option<AttemptTimeoutOption>, ) -> Self

Sets the complete per-attempt timeout option.

§Parameters

attempt_timeout: Timeout option. None disables per-attempt timeout.

§Returns

The updated builder.

Source

pub fn attempt_timeout_policy(self, policy: AttemptTimeoutPolicy) -> Self

Sets the policy used when an attempt times out.

If a timeout duration is already configured, this updates the complete timeout option. Otherwise the policy is kept and applied when RetryBuilder::attempt_timeout is called later.

§Parameters

policy: Timeout policy to use.

§Returns

The updated builder.

Source

pub fn worker_cancel_grace(self, grace: Duration) -> Self

Sets how long worker-thread execution waits after cancelling a timed-out worker.

§Parameters

grace: Duration to wait after the attempt timeout fires and the cooperative cancellation token is marked as cancelled. Use zero to skip the grace wait.

§Returns

The updated builder.

Source

pub fn retry_after_hint<H>(self, hint: H) -> Self
where H: BiFunction<AttemptFailure<E>, RetryContext, Option<Duration>> + Send + Sync + 'static,

Extracts an optional retry-after hint from each failure.

§Parameters

hint: Function that inspects a failure and context before failure listeners run.

§Returns

The updated builder.

Source

pub fn retry_after_from_error<H>(self, hint: H) -> Self
where H: Fn(&E) -> Option<Duration> + Send + Sync + 'static,

Extracts an optional retry-after hint from operation errors.

§Parameters

hint: Function returning a delay hint for application errors.

§Returns

The updated builder.

Source

pub fn before_attempt<C>(self, listener: C) -> Self
where C: Consumer<RetryContext> + Send + Sync + 'static,

Registers a listener invoked before every attempt.

§Parameters

listener: Listener receiving the retry context.

§Returns

The updated builder.

Source

pub fn on_success<C>(self, listener: C) -> Self
where C: Consumer<RetryContext> + Send + Sync + 'static,

Registers a listener invoked when an attempt succeeds.

§Parameters

listener: Listener receiving the success context.

§Returns

The updated builder.

Source

pub fn on_failure<F>(self, listener: F) -> Self
where F: BiFunction<AttemptFailure<E>, RetryContext, AttemptFailureDecision> + Send + Sync + 'static,

Registers a listener invoked after each attempt failure.

§Parameters

listener: Listener returning a retry failure decision.

§Returns

The updated builder.

Source

pub fn on_retry<C>(self, listener: C) -> Self
where C: BiConsumer<AttemptFailure<E>, RetryContext> + Send + Sync + 'static,

Registers a listener invoked after a retry delay has been selected.

The listener receives the failed attempt and a context whose RetryContext::next_delay contains the delay that will be slept before the next attempt. The listener is observational and cannot change the retry decision.