GenRetry provides utilities for retrying Elixir functions, with configurable delay and backoff characteristics.

Summary

Given a 0-arity function which raises an exception upon failure, retry/2 and retry_link/2 repeatedly executes the function until success is reached or the maximum number of retries has occurred.

GenRetry.Task.async/2 and GenRetry.Task.Supervisor.async/3 provide drop-in replacements for Task.async/1 and Task.Supervisor.async/2, respectively, adding retry capability. They return plain %Task{} structs, usable with any other function in the Task module.

Examples

my_background_function = fn ->
  :ok = try_to_send_tps_reports()
end
GenRetry.retry(my_background_function, retries: 10, delay: 10_000)

my_future_function = fn ->
  {:ok, val} = get_val_from_flaky_network_service()
  val
end
t = GenRetry.Task.async(my_future_function, retries: 3)
my_val = Task.await(t)  # may raise exception

Installation

1. Add GenRetry to your list of dependencies in mix.exs:

    def deps do
      [{:gen_retry, "~> 1.4.0"}]
    end

2. Ensure GenRetry is started before your application:

    def application do
      [applications: [:gen_retry]]
    end

3. (Optional) Specify a custom logging module in your config.exs

    config :gen_retry, GenRetry.Logger, logger: MyApp.CustomLogger

   where MyApp.CustomLogger implements the GenRetry.Logger behavior. The default module is GenRetry.Utils if none is specified in a config.

Options

• :retries, integer (default 1): Number of times to retry upon failure. Set to 0 to try exactly once; set to :infinity to retry forever.

• :delay, integer (default 1000): Number of milliseconds to wait between first failure and first retry. Subsequent retries use this value as a starting point for exponential backoff.

• :jitter, number (default 0): Proportion of current retry delay to randomly add to delay time. For example, given options delay: 1000, jitter: 0.1, the first delay will be a random time between 1000 and 1100 milliseconds. Values under 0 will remove time rather than add it; beware of values under -1, which may result in nonsensical "negative time delays".

• :exp_base, number (default 2): The base to use for exponentiation during exponential backoff. Set to 1 to disable backoff. Values less than 1 are not very useful.

• :respond_to, pid (ignored by GenRetry.Task.*): The process ID to which a message should be sent upon completion. Successful exits send {:success, return_value, final_retry_state}; unsuccessful exits send {:failure, error, stacktrace, final_retry_state}.

• :on_success, fn {result, final_retry_state} -> nil end (default no-op): A function to run on success. The argument is a tuple containing the result and the final retry state.

• :on_failure, fn {exception, stacktrace, final_retry_state} -> nil end (default no-op): A function to run on failure. The argument is a tuple containing the exception, stacktrace, and final retry state.