2 The Retry Reference

7.7

top ← prev up next →

2 The Retry Reference

This document describes the complete API of the retry library. For a gentler introduction and use cases, see The Retry Guide.

2.1 Core Retry API

procedure
(retryer? v) → boolean?
v : any/c

A predicate that returns true when v is a retryer, and false otherwise.

procedure
(retryer [ #:handle handle-proc
#:should-retry? should-retry-proc]) → retryer?
handle-proc : (-> any/c exact-nonnegative-integer? void?)
= void
should-retry-proc : (-> any/c exact-nonnegative-integer? boolean?)
= (const #t)

Returns a retryer that retries when should-retry-proc returns true and handles failures with handle-proc. See call/retry for details on how these procedures are called to retry failures. Using only the default procedures for both cases produces a retryer equivalent to always-retryer.

procedure
(call/retry retryer proc) → any
retryer : retryer?
proc : (-> any)

Calls proc and catches any thrown exceptions, then consults the given retryer to determine whether proc should be called again.

If a value v is thrown on the nth retry, (retryer-handle retryer v n) is called to handle the exception (or rethrow it if the retryer doesn’t handle this particular kind of exception). The value of n starts at zero. Then, (retryer-should-retry? retryer n) is called to determine whether to retry. If that returns true, proc is called again and this process repeats. Otherwise, the value v is rethrown and attempts to call proc are abandoned. Invocations of call/retry may never terminate, as some retryers never stop retrying. For a shorthand syntax, see with-retry.

syntax
(with-retry retryer-expr body ...)

retryer-expr : retryer?

Equivalent to (call/retry retryer-expr (λ () body ...)).

procedure
(retryer-handle retryer
raised
num-previous-retries) → void?
  retryer : retryer?
  raised : any/c
  num-previous-retries : exact-nonnegative-integer?

Dispatches to retryer to determine how to handle raised after num-previous-retries retries.

procedure
(retryer-should-retry? retryer
raised
num-previous-retries) → boolean?
  retryer : retryer?
  raised : any/c
  num-previous-retries : exact-nonnegative-integer?

Dispatches to retryer to determine whether an operation should retry when raised was raised after num-previous-retries retries.

2.2 Built-In Retryers

value
always-retryer : retryer? = (retryer)

The always retryer. Swallows all failures and retries without restriction.

value
never-retryer : retryer? = (retryer #:should-retry? (const #f))

The never retryer. Does absolutely nothing in the face of failure and never retries.

procedure
(limit-retryer limit) → retryer?
limit : exact-nonnegative-integer?

Returns a retryer that only retries a maximum of limit times.

procedure
(print-exn-retryer to-string) → retryer?
to-string : (-> string? exact-nonnegative-integer? string?)

Returns a retryer that handles raised exn? values by calling to-string with the raised exception’s message and the number of previous retries, and then passing the resulting string to displayln.

procedure
(sleep-retryer sleep-amount-proc) → retryer?
sleep-amount-proc : (-> exact-nonnegative-integer? time-period?)

Returns a retryer that handles all raised values by sleep-ing for an amount of time determined by calling sleep-amount-proc with the number of previous retries.

procedure
(sleep-retryer/random max-sleep-amount-proc) → retryer?
max-sleep-amount-proc : (-> exact-nonnegative-integer? time-period?)

Like sleep-retryer, but instead of sleeping for an amount of time equal to what is returned by max-sleep-amount-proc a random amount of time up to the returned amount is used. The unit of the returned time-period? determines how precise the randomness is. Returning (seconds 3) causes the retryer to sleep for either zero, one, or two seconds, while returning (milliseconds 3000) sleeps for up to 3000 milliseconds.

procedure
(sleep-const-retryer sleep-amount) → retryer?
sleep-amount : exact-nonnegative-integer?

Returns a retryer that handles all raised values by sleep-ing for sleep-amount. Equivalent to (sleep-retryer (const sleep-amount)).

procedure
(sleep-const-retryer/random max-sleep-amount) → retryer?
max-sleep-amount : time-period?

Like sleep-const-retryer and sleep-retryer/random. The returned retryer sleeps for at most max-sleep-amount.

procedure
(sleep-exponential-retryer sleep-amount
[ #:exponent-base base]) → retryer?
sleep-amount : time-period?
base : (>/c 0) = 2

Returns a retryer that handles all raised values by sleep-ing for an amount of time equal to sleep-amount multiplied by an exponential factor. The exponential factor is equal to base raised to the power of the number of previous retries. With the default exponent base of two, the returned retryer sleeps for sleep-amount on the first retry, twice that on the second, four times on the third, eight on the fourth, and so on. Supplying a different exponent base changes the speed of the exponential growth.

procedure
(sleep-exponential-retryer/random max-sleep-amount
[ #:exponent-base base])
→ retryer?
max-sleep-amount : exact-nonnegative-integer?
base : (>/c 0) = 2

Like sleep-exponential-retryer and sleep-retryer/random. The returned retryer sleeps for a random amount of time that is at most what the equivalent sleep-exponential-retryer would sleep for.

2.3 Higher-Order Retryers

procedure
(retryer-compose ret ...) → retryer?
ret : retryer?

Returns a retryer that is a composition of the given retryers. The returned retryer retries a failure only if every ret retries that failure in the sense of retryer-should-retry?. To handle failures, the composed retryer calls each ret using retryer-handle. The first ret is called last in both these operations, giving right-to-left composition in the same manner as function composition with compose.

procedure
(cycle-retryer ret cycle-length) → retryer?
ret : retryer?
cycle-length : exact-positive-integer?

Returns a retryer that is like ret, but takes the number of previous retries from retryer-should-retry? and retryer-handle and resets it on a cycle of length cycle-length using modulo. This allows creation of retryers that perform some cyclic behavior, such as implementing a retryer on top of sleep-exponential-retryer that resets the exponential backoff cycle after cycle-length retries.

top ← prev up next →

2.1	Core Retry API
2.2	Built-In Retryers
2.3	Higher-Order Retryers