# relentless
[](https://crates.io/crates/relentless)
[](https://docs.rs/relentless)
[](https://github.com/camercu/relentless/actions/workflows/ci.yml)
[](#msrv)
Retry and polling for Rust — with composable strategies, policy reuse, and
first-class support for polling workflows where `Ok(_)` doesn't always mean
"done."
Most retry libraries handle the simple case well: call a function, retry on
error, back off. `relentless` handles that too, but it also handles the cases
those libraries make awkward:
- **Polling**, where `Ok("pending")` means "keep going" and you need
`.until(predicate::ok(...))` rather than just retrying errors.
- **Policy reuse**, where a single `RetryPolicy` captures your retry rules and
gets shared across multiple call sites — no duplicated builder chains.
- **Strategy composition**, where `wait::fixed(50ms) + wait::exponential(100ms)`
and `stop::attempts(5) | stop::elapsed(2s)` express complex behavior in one
line.
- **Hooks and stats**, where you observe the retry lifecycle (logging, metrics)
without restructuring your retry logic.
All of this works in sync and async code, across `std`, `no_std`, and `wasm`
targets.
Inspired by Python's [`tenacity`](https://github.com/jd/tenacity) (composable
strategy algebra) and Rust's [`backon`](https://crates.io/crates/backon)
(ergonomic retry builders).
## Install
```bash
cargo add relentless
```
### Feature flags
| `std` (default) | `std::thread::sleep` fallback, `Instant` elapsed clock, `std::error::Error` on `RetryError` |
| `alloc` | Boxed policies, closure elapsed clocks, multiple hooks per point |
| `tokio-sleep` | `sleep::tokio()` async sleep adapter |
| `embassy-sleep` | `sleep::embassy()` async sleep adapter |
| `gloo-timers-sleep` | `sleep::gloo()` async sleep adapter (wasm32) |
| `futures-timer-sleep` | `sleep::futures_timer()` async sleep adapter |
Async retry does not require `alloc`.
---
## Examples
For full docs, see <https://docs.rs/relentless>. Behavior spec:
[docs/SPEC.md](./docs/SPEC.md). Runnable examples live in
[`examples/`](./examples).
Sync examples omit `.sleep(...)` because `std` builds fall back to
`std::thread::sleep` automatically. Without `std`, pass an explicit sleeper
before `.call()`.
### 1) Retry with defaults
The `.retry()` extension trait is the fastest way to add retries. Defaults: 3
attempts, exponential backoff from 100 ms, retry on any `Err`.
```rust,no_run
use relentless::RetryExt;
fn fetch_job_output() -> Result<String, std::io::Error> {
std::fs::read_to_string("/var/run/background_job.output")
}
let results = fetch_job_output.retry().call();
```
### 2) Customized retry
The `retry` free function is equivalent to the extension trait, with the added
ability to capture retry loop state. Both the free function and extension trait
give full control over which errors to retry, how long to wait, and when to
stop.
```rust,no_run
use core::time::Duration;
use relentless::{Wait, retry, predicate, stop, wait};
reqwest::blocking::get("https://api.example.com/data")?.text()
})
wait::exponential(Duration::from_millis(200))
.full_jitter()
.cap(Duration::from_secs(5)),
)
.stop(stop::attempts(10))
.timeout(Duration::from_secs(30))
.call();
```
### 3) Reuse a policy across call sites
`RetryPolicy` captures retry rules once. Compose wait strategies with `+` and
stop strategies with `|` or `&`.
```rust,no_run
use core::time::Duration;
use relentless::{RetryPolicy, stop, wait};
fn check_health() -> Result<String, std::io::Error> { todo!() }
fn fetch_invoice(id: &str) -> Result<String, std::io::Error> { todo!() }
let policy = RetryPolicy::new()
.wait(
wait::fixed(Duration::from_millis(50))
+ wait::exponential(Duration::from_millis(100)),
)
.stop(stop::attempts(5) | stop::elapsed(Duration::from_secs(30)));
// Same policy, different operations.
### 4) Poll for a condition
Use `.until(predicate)` to keep retrying until a success condition is met.
Unlike `.when()`, which retries on matching outcomes, `.until()` retries on
everything *except* the matching outcome.
```rust,no_run
use relentless::{RetryPolicy, predicate};
#[derive(Debug, PartialEq)]
enum Status { Pending, Done }
fn poll_status() -> Result<Status, std::io::Error> { todo!() }
let result = RetryPolicy::new()
.until(predicate::ok(|s: &Status| *s == Status::Done))
.retry(|_| poll_status())
.call();
```
To also retry selected errors during polling, use `predicate::result`:
```rust,no_run
use relentless::{RetryPolicy, predicate};
#[derive(Debug)]
enum Status { Pending, Done }
#[derive(Debug)]
enum Error { Retryable, Fatal }
fn poll_job() -> Result<Status, Error> { todo!() }
// Retry until Done or Fatal; keep going on Pending or Retryable.
let result = RetryPolicy::new()
.until(predicate::result(|outcome: &Result<Status, Error>| {
matches!(outcome, Ok(Status::Done) | Err(Error::Fatal))
}))
.retry(|_| poll_job())
.call();
```
### 5) Async retry
Pass an async sleep adapter — here via the `tokio-sleep` feature.
```rust,no_run
use relentless::retry_async;
async fn fetch(url: &str) -> Result<String, reqwest::Error> {
reqwest::get(url).await?.text().await
}
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let body = retry_async(|_| fetch("https://api.example.com/data"))
.sleep(relentless::sleep::tokio())
.await?;
Ok(())
}
```
### 6) Hooks & stats
```rust
use relentless::retry;
if state.attempt > 1 {
println!("retrying (attempt {})", state.attempt);
}
})
.after_attempt(|state| {
if let Err(e) = state.outcome {
eprintln!("attempt {} failed: {e}", state.attempt);
}
})
.with_stats()
.call();
println!("attempts: {}, total wait: {:?}", stats.attempts, stats.total_wait);
```
### 7) Error handling
```rust,no_run
use relentless::{retry, RetryError};