The exponential-backoff Reference Manual

Table of Contents

The exponential-backoff Reference Manual

This is the exponential-backoff Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Dec 22 13:24:59 2020 GMT+0.

1 Introduction

Exponential backoff

An implementation of the exponential backoff algorithm in Common Lisp.

Inspired by the implementation found in Chromium. Read the header file to learn about each of the parameters.

Example

If you like to SLEEP or otherwise block, and don't care to signal errors until giving up:

(defun noisy-sleep (seconds)
  (format t "Sleeping for ~A seconds.~%" seconds)
  (sleep seconds))

(exponential-backoff:with-exponential-backoff ((:initial-delay-ms 1000 :jitter-factor 0.1)
                                               :max-retries 3 :sleep-function #'noisy-sleep)
  (format t "Trying...~%")
  (error "Something bad happened."))

;; Output:
;;
;; Trying...
;; Sleeping for 0.9575 seconds.
;; Trying...
;; Sleeping for 1.8265 seconds.
;; Trying...
;; Sleeping for 3.855 seconds.
;; Trying...
;; ; Evaluation aborted on #<SIMPLE-ERROR "Something bad happened." {1009EB9E83}>.

A more involved example that uses the backoff information by itself:

(loop with b = (exponential-backoff:exponential-backoff
                :num-failures-to-ignore 1
                :initial-delay-ms (* 5 1000)
                :jitter-factor 0.1
                :max-backoff-ms (* 5 60 1000))
      for time-to-wait = (exponential-backoff:time-until-release b)
      for will-succeed in '(t nil nil nil t nil nil t t nil nil)
      do (format t "Waiting for ~F ms before ~:[failing~;succeeding~]...~%" time-to-wait will-succeed)
      do (sleep (/ time-to-wait 1000))
      do (exponential-backoff:inform b will-succeed))

;; Output:
;;
;; Waiting for 0.0 ms before succeeding...
;; Waiting for 0.0 ms before failing...
;; Waiting for 0.0 ms before failing...
;; Waiting for 4647.0 ms before failing...
;; Waiting for 9893.5 ms before succeeding...
;; Waiting for 0.0 ms before failing...
;; Waiting for 9357.5 ms before failing...
;; Waiting for 18710.0 ms before succeeding...
;; Waiting for 0.0 ms before succeeding...
;; Waiting for 0.0 ms before failing...
;; Waiting for 9969.0 ms before failing...

License

MIT

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 exponential-backoff

Author

death <github.com/death>

License

MIT

Description

An implementation of the exponential backoff algorithm

Source

exponential-backoff.asd (file)

Component

exponential-backoff.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 exponential-backoff.asd

Location

exponential-backoff.asd

Systems

exponential-backoff (system)

3.1.2 exponential-backoff/exponential-backoff.lisp

Parent

exponential-backoff (system)

Location

exponential-backoff.lisp

Packages

exponential-backoff

Exported Definitions

• exponential-backoff (function)
• inform (function)
• reset (function)
• time-until-release (function)
• with-exponential-backoff (macro)

Internal Definitions

• call-with-exponential-backoff (function)
• now (function)
• release-time (function)

4 Packages

Packages are listed by definition order.

4.1 exponential-backoff

Source

exponential-backoff.lisp (file)

Use List

common-lisp

Exported Definitions

• exponential-backoff (function)
• inform (function)
• reset (function)
• time-until-release (function)
• with-exponential-backoff (macro)

Internal Definitions

• call-with-exponential-backoff (function)
• now (function)
• release-time (function)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Macros

Macro: with-exponential-backoff (BACKOFF &rest OPTIONS &key SLEEP-FUNCTION MAX-RETRIES RESET) &body FORMS

Package

exponential-backoff

Source

exponential-backoff.lisp (file)

5.1.2 Functions

Function: exponential-backoff &key NUM-FAILURES-TO-IGNORE INITIAL-DELAY-MS MULTIPLY-FACTOR JITTER-FACTOR MAX-BACKOFF-MS ALWAYS-USE-INITIAL-DELAY

Package

exponential-backoff

Source

exponential-backoff.lisp (file)

Function: inform BACKOFF SUCCEEDED

Package

exponential-backoff

Source

exponential-backoff.lisp (file)

Function: reset BACKOFF

Package

exponential-backoff

Source

exponential-backoff.lisp (file)

Function: time-until-release BACKOFF

Package

exponential-backoff

Source

exponential-backoff.lisp (file)

5.2 Internal definitions

5.2.1 Functions

Function: call-with-exponential-backoff FN BACKOFF &key SLEEP-FUNCTION MAX-RETRIES RESET

Package

exponential-backoff

Source

exponential-backoff.lisp (file)

Function: now ()

Package

exponential-backoff

Source

exponential-backoff.lisp (file)

Function: release-time BACKOFF

Package

exponential-backoff

Source

exponential-backoff.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types