From 50ff97bf82cd146cb289e5b9fbd864bbcc9c30d9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Sat, 27 Jul 2019 16:42:00 +0200
Subject: Add the retry_fun option for different backoff strategies

---
 doc/src/manual/gun.asciidoc | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

(limited to 'doc/src')

diff --git a/doc/src/manual/gun.asciidoc b/doc/src/manual/gun.asciidoc
index cd34537..f8d5406 100644
--- a/doc/src/manual/gun.asciidoc
+++ b/doc/src/manual/gun.asciidoc
@@ -208,6 +208,7 @@ opts() :: #{
     http2_opts            => http2_opts(),
     protocols             => [http | http2],
     retry                 => non_neg_integer(),
+    retry_fun             => fun(),
     retry_timeout         => pos_integer(),
     supervise             => boolean(),
     tcp_opts              => [gen_tcp:connect_option()],
@@ -253,6 +254,29 @@ retry (5)::
 
 Number of times Gun will try to reconnect on failure before giving up.
 
+retry_fun - see below::
+
+A fun that will be called before every reconnect attempt. It receives
+the current number of retries left and the Gun options. It returns the
+next number of retries left and the timeout to apply before reconnecting.
+
+The default fun will remove one to the number of retries and set the
+timeout to the `retry_timeout` value.
+
+The fun must be defined as follow:
+
+[source,erlang]
+----
+fun ((non_neg_integer(), opts()) -> #{
+    retries => non_neg_integer(),
+    timeout => pos_integer()
+})
+----
+
+The fun will never be called when the `retry` option is set to 0. When
+this function returns 0 in the `retries` value, Gun will do one last
+reconnect attempt before giving up.
+
 retry_timeout (5000)::
 
 Time between retries in milliseconds.
@@ -350,6 +374,8 @@ undocumented and must be set to `gun_ws_h`.
 * *2.0*: The `connect_timeout` option has been split into
          three options: `domain_lookup_timeout`, `connect_timeout`
          and when applicable `tls_handshake_timeout`.
+* *2.0*: The option `retry_fun` was added. It can be used to
+         implement different reconnect strategies.
 * *2.0*: The `transport_opts` option has been split into
          two options: `tcp_opts` and `tls_opts`.
 * *2.0*: Introduce the type `req_headers()` and extend the
-- 
cgit v1.2.3