Struct Retry

Source

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

Expand description

Retry policy and executor bound to an operation error type.

The generic parameter E is the caller’s operation error type. Cloning a retry policy shares all registered functors through reference-counted rs-function wrappers.

Implementations§

Source §

impl<E> Retry<E>

Source of an effective attempt timeout.

Source

pub fn builder() -> RetryBuilder<E>

Creates a retry builder.

§Returns

A RetryBuilder configured with defaults.

Source

pub fn from_options(options: RetryOptions) -> Result<Self, RetryConfigError>

Creates a retry policy from options.

§Parameters

options: Retry options to validate and install.

§Returns

A retry policy using the default listener set.

§Errors

Returns RetryConfigError if the options are invalid.

Source

pub fn options(&self) -> &RetryOptions

Returns the immutable options used by this retry policy.

§Returns

Shared retry options.

Source

pub fn run<T, F>(&self, operation: F) -> Result<T, RetryError<E>>
where F: FnMut() -> Result<T, E>,

Runs a synchronous operation with retry.

§Parameters

operation: Operation called once per attempt until it succeeds or the retry flow stops.

§Returns

Ok(T) with the operation value, or RetryError when retrying stops.

§Panics

Propagates operation panics and listener panics unless listener panic isolation is enabled.

§Blocking

Blocks the current thread with std::thread::sleep between attempts when a non-zero retry delay is selected.

§Elapsed Budget

max_operation_elapsed counts only user operation execution time. max_total_elapsed counts monotonic retry-flow time, including operation execution, retry sleep, retry-after sleep, and retry control-path listener time. This synchronous mode cannot interrupt an already-running operation; it checks budgets before attempts and after failed attempts. If attempt_timeout is configured, this method returns RetryErrorReason::UnsupportedOperation because timeout enforcement requires worker-thread or async execution.

Source

pub fn run_in_worker<T, F>(&self, operation: F) -> Result<T, RetryError<E>>
where T: Send + 'static, E: Send + 'static, F: Fn(AttemptCancelToken) -> Result<T, E> + Send + Sync + 'static,

Runs a blocking operation with retry inside worker-thread attempts.

Each attempt runs on a worker thread. Worker panics are captured as AttemptFailure::Panic. Worker-spawn failures are reported as AttemptFailure::Executor. If the effective timeout expires, the retry executor stops waiting and marks the attempt’s AttemptCancelToken as cancelled. It then waits up to RetryOptions::worker_cancel_grace for the worker to exit. Configured attempt-timeout expirations continue according to AttemptTimeoutPolicy only when the worker exits within that grace period; otherwise the retry flow stops with RetryErrorReason::WorkerStillRunning. Elapsed-budget expirations stop with RetryErrorReason::MaxOperationElapsedExceeded or RetryErrorReason::MaxTotalElapsedExceeded.

§Parameters

operation: Thread-safe operation called once per attempt. It receives a cooperative cancellation token for that attempt.

§Returns

Ok(T) with the operation value, or RetryError when retrying stops.

§Panics

Does not propagate operation panics. Listener panic behavior follows this retry policy’s listener isolation setting.

§Blocking

Blocks the current thread while waiting for each worker result or timeout and while sleeping between retry attempts.

§Elapsed Budget

max_operation_elapsed counts only user operation execution time. max_total_elapsed counts monotonic retry-flow time. Worker attempts use the shortest of configured attempt timeout, remaining max-operation-elapsed budget, and remaining max-total-elapsed budget as their effective timeout.

Source

pub fn run_blocking_with_timeout<T, F>( &self, operation: F, ) -> Result<T, RetryError<E>>
where T: Send + 'static, E: Send + 'static, F: Fn(AttemptCancelToken) -> Result<T, E> + Send + Sync + 'static,

Runs a blocking operation with retry and per-attempt timeout isolation.

This method is a compatibility alias for Retry::run_in_worker. It also runs attempts in worker threads when no timeout is configured, so worker panics are reported as AttemptFailure::Panic instead of unwinding through the caller. Worker-spawn failures are reported as AttemptFailure::Executor.

§Parameters

operation: Thread-safe operation called once per attempt. It receives a cooperative cancellation token for that attempt.

§Returns

Ok(T) with the operation value, or RetryError when retrying stops.

§Panics

Does not propagate operation panics. Listener panic behavior follows this retry policy’s listener isolation setting.

§Blocking

Blocks the current thread while waiting for each worker result or timeout and while sleeping between retry attempts.

§Elapsed Budget

max_operation_elapsed counts only user operation execution time. max_total_elapsed counts monotonic retry-flow time. Worker attempts use the shortest of configured attempt timeout, remaining max-operation-elapsed budget, and remaining max-total-elapsed budget as their effective timeout.

Source

pub async fn run_async<T, F, Fut>( &self, operation: F, ) -> Result<T, RetryError<E>>
where F: FnMut() -> Fut, Fut: Future<Output = Result<T, E>>,

Runs an asynchronous operation with retry.

§Parameters

operation: Factory returning a fresh future for each attempt.

§Returns

Ok(T) with the operation value, or RetryError when retrying stops.

§Panics

Propagates operation panics from the current async task. They are not converted to AttemptFailure::Panic because run_async does not create an isolation boundary. Listener panics are propagated unless listener panic isolation is enabled. Tokio may panic if timer APIs are used outside a runtime with a time driver.

§Elapsed Budget

max_operation_elapsed counts only user operation execution time. max_total_elapsed counts monotonic retry-flow time. Async attempts use the shortest of configured attempt timeout, remaining max-operation-elapsed budget, and remaining max-total-elapsed budget as their effective timeout.