A retry library for Clojure
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src/again
test/again
.gitignore
.travis.yml
LICENSE
README.md
project.clj

README.md

Again

Build Status

A Clojure library for retrying an operation based on a retry strategy.

Clojars:

[listora/again "0.1.0"]

--

Usage

Require the library:

(require '[again.core :as again])

Again provides a very simple (too simple?) API for retrying an operation: given a retry strategy and an operation, the operation will be retried based on the provided strategy if it throws an exception.

A retry strategy is just a sequence of integers that represent a delay in milliseconds before retrying the operation. Once the sequence runs out, with-retries will re-throw the last exception.

Basic use case:

(again/with-retries
  [100 1000 10000]
  (my-operation arg-1 arg-2))

The above will retry my-operation three times, for a total of four tries, with 100ms, 1000ms and 10000ms delays between the retries.

The library provides a numbers of functions for generating and manipulating retry strategies. Most of the provided strategies are infinite sequences. The strategies can be restricted with the manipulator functions.

Generators:

  • constant-strategy - constant delays between retries
  • immediate-strategy - 0ms delays between retries
  • additive-strategy - incrementally increasing delays between retries
  • stop-strategy - no retries
  • multiplicative-strategy - exponentially increasing delays between retries

Manipulators:

  • randomize-strategy - scale each delay with a new random number
  • max-retries - limit the number of retries to a given number
  • clamp-delay - limit the delay to a given number
  • max-delay - stop retrying when the delay crosses a given number
  • max-duration - stop retrying when the combined delay crosses a given number

Exponential backoff example:

The generators and manipulators can be combined to create a desired retry strategy. Eg an exponential backoff retry strategy with an initial delay of 500ms and a multiplier of 1.5, limited to either 10 retries or a maximum duration of 10s can be generated as follows:

(def exponential-backoff-strategy
  (again/max-duration
    10000
    (again/max-retries
      10
      (again/randomize-strategy
        0.5
        (again/multiplicative-strategy 500 1.5)))))

We can also prepend a 0 to the strategy in order to execute the first retry immediately:

(def exponential-backoff-strategy-with-immediate-retry
  (cons 0 exponential-backoff-strategy))

License

Copyright © 2014 Listora

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.