Add documentation for backoff algorithms

nbraun-amazon · michael-grunder · commit 732eb8dcbe93 · 2021-10-05T14:34:58.000-07:00
diff --git a/README.markdown b/README.markdown
@@ -35,6 +35,7 @@ You can also make a one-time contribution with one of the links below.
 1. [Classes and methods](#classes-and-methods)
    * [Usage](#usage)
    * [Connection](#connection)
+   * [Retry and backoff](#retry-and-backoff)
    * [Server](#server)
    * [Keys and strings](#keys-and-strings)
    * [Hashes](#hashes)
@@ -428,6 +429,41 @@ _**Description**_: Sends a string to Redis, which replies with the same string
 
 *STRING*: the same message.
 
+## Retry and backoff
+
+1. [Maximum retries](#maximum-retries)
+1. [Backoff algorithms](#backoff-algorithms)
+
+### Maximum retries
+You can set and get the maximum retries upon connection issues using the `OPT_MAX_RETRIES` option. Note that this is the number of _retries_, meaning if you set this option to _n_, there will be a maximum _n+1_ attemps overall. Defaults to 10.
+
+##### *Example*
+
+~~~php
+$redis->setOption(Redis::OPT_MAX_RETRIES, 5);
+$redis->getOption(Redis::OPT_MAX_RETRIES);
+~~~
+
+### Backoff algorithms
+You can set the backoff algorithm using the `Redis::OPT_BACKOFF_ALGORITHM` option and choose among the following algorithms described in this blog post by Marc Brooker from AWS: [Exponential Backoff And Jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter):
+
+* Default: `Redis::BACKOFF_ALGORITHM_DEFAULT`
+* Decorrelated jitter: `Redis::BACKOFF_ALGORITHM_DECORRELATED_JITTER`
+* Full jitter: `Redis::BACKOFF_ALGORITHM_FULL_JITTER`
+* Equal jitter: `Redis::BACKOFF_ALGORITHM_EQUAL_JITTER`
+* Exponential: `Redis::BACKOFF_ALGORITHM_EXPONENTIAL`
+* Uniform: `Redis::BACKOFF_ALGORITHM_UNIFORM`
+* Constant: `Redis::BACKOFF_ALGORITHM_CONSTANT`
+
+These algorithms depend on the _base_ and _cap_ parameters, both in milliseconds, which you can set using the `Redis::OPT_BACKOFF_BASE` and `Redis::OPT_BACKOFF_CAP` options, respectively.
+
+##### *Example*
+
+~~~php
+$redis->setOption(Redis::OPT_BACKOFF_ALGORITHM, Redis::BACKOFF_ALGORITHM_DECORRELATED_JITTER);
+$redis->setOption(Redis::OPT_BACKOFF_BASE, 500); // base for backoff computation: 500ms
+$redis->setOption(Redis::OPT_BACKOFF_CAP, 750); // backoff time capped at 750ms
+~~~
 
 ## Server
 
diff --git a/tests/RedisTest.php b/tests/RedisTest.php
@@ -5280,9 +5280,6 @@ public function testMaxRetriesOption() {
     }
 
     public function testBackoffOptions() {
-        $this->redis->setOption(Redis::OPT_MAX_RETRIES, 5);
-        $this->assertEquals($this->redis->getOption(Redis::OPT_MAX_RETRIES), 5);
-
         $this->redis->setOption(Redis::OPT_BACKOFF_ALGORITHM, Redis::BACKOFF_ALGORITHM_DEFAULT);
         $this->assertEquals($this->redis->getOption(Redis::OPT_BACKOFF_ALGORITHM), Redis::BACKOFF_ALGORITHM_DEFAULT);
 
@@ -5295,6 +5292,9 @@ public function testBackoffOptions() {
         $this->redis -> setOption(Redis::OPT_BACKOFF_ALGORITHM, Redis::BACKOFF_ALGORITHM_EXPONENTIAL);
         $this->assertEquals($this->redis->getOption(Redis::OPT_BACKOFF_ALGORITHM), Redis::BACKOFF_ALGORITHM_EXPONENTIAL);
 
+        $this->redis->setOption(Redis::OPT_BACKOFF_ALGORITHM, Redis::BACKOFF_ALGORITHM_EQUAL_JITTER);
+        $this->assertEquals($this->redis->getOption(Redis::OPT_BACKOFF_ALGORITHM), Redis::BACKOFF_ALGORITHM_EQUAL_JITTER);
+
         $this->redis->setOption(Redis::OPT_BACKOFF_ALGORITHM, Redis::BACKOFF_ALGORITHM_FULL_JITTER);
         $this->assertEquals($this->redis->getOption(Redis::OPT_BACKOFF_ALGORITHM), Redis::BACKOFF_ALGORITHM_FULL_JITTER);
 
