From ad1dc0c538610bdaf5e7b197ca997820d4a3d348 Mon Sep 17 00:00:00 2001
From: Maria Scott <maria-12648430@hnc-agency.org>
Date: Tue, 7 Sep 2021 11:42:49 +0200
Subject: Manual for num_connection alarms

---
 doc/src/guide/listeners.asciidoc | 13 ++++++-------
 doc/src/manual/ranch.asciidoc    | 40 ++++++++++++++++++++++++++++++++++++++++
 src/ranch_conns_sup.erl          |  2 +-
 3 files changed, 47 insertions(+), 8 deletions(-)

diff --git a/doc/src/guide/listeners.asciidoc b/doc/src/guide/listeners.asciidoc
index 4437143..0e94e45 100644
--- a/doc/src/guide/listeners.asciidoc
+++ b/doc/src/guide/listeners.asciidoc
@@ -330,7 +330,7 @@ processes.
 
 === Setting connection count alarms
 
-The `alarms` transport options allows you to configure alarms
+The `alarms` transport option allows you to configure alarms
 which will be triggered when the number of connections under a connection
 supervisor reaches or exceeds the defined treshold.
 
@@ -340,7 +340,7 @@ options as values.
 Any term is allowed as an alarm name.
 
 Alarm options, defining the alarm behavior, are again a map with the following
-keys, all of which are mandatory:
+keys:
 
 `type`::
 The alarm type. Currently, `num_connections` is the only allowed type.
@@ -356,7 +356,7 @@ alarm is triggered. Its arguments are the listener name, the alarm
 name, the Pid of the triggering connection supervisor, and the Pids of
 all the connection processes under that supervisor.
 
-`cooldown`::
+`cooldown` (5000)::
 The minimum time to elapse before the alarm can trigger again, in
 milliseconds.
 
@@ -373,8 +373,7 @@ Alarms = #{
                     "Supervisor ~s of listener ~s "
                     "has ~b connections",
                 [Name, Ref, ConnSup, length(ConnPids)])
-        end,
-        cooldown => 5000
+        end
     }
 },
 {ok, _} = ranch:start_listener(tcp_echo,
@@ -386,8 +385,8 @@ Alarms = #{
 In the example code, an alarm named `my_alarm` is defined, which will
 call the given function when the number of connections under a
 connection supervisor reaches or exceeds 100. When the number of
-connections is still (or again) above 100 after 5 seconds, the
-alarm will trigger again.
+connections is still (or again) above 100 after the default cooldown
+period of 5 seconds, the alarm will trigger again.
 
 === When running out of file descriptors
 
diff --git a/doc/src/manual/ranch.asciidoc b/doc/src/manual/ranch.asciidoc
index 26e0769..af006a2 100644
--- a/doc/src/manual/ranch.asciidoc
+++ b/doc/src/manual/ranch.asciidoc
@@ -88,6 +88,14 @@ Unique name used to refer to a listener.
 [source,erlang]
 ----
 transport_opts(SocketOpts) = #{
+    alarms               => #{
+                                term() => #{
+                                    type := num_connections,
+                                    treshold := non_neg_integer(),
+                                    callback := fun((ref(), term(), pid(), [pid()]) -> any()),
+                                    cooldown => non_neg_integer()
+                                }
+                            },
     connection_type      => worker | supervisor,
     handshake_timeout    => timeout(),
     max_connections      => max_conns(),
@@ -107,6 +115,38 @@ options and transport-specific socket options.
 
 None of the options are required.
 
+alarms (#{})::
+
+Alarms to call a function when the number of connections under a
+connection supervisor reaches or exceeds a defined treshold.
++
+The map keys are the alarm names, which can be any `term`. The
+associated values are the respective alarm options, again in a map
+with the following keys:
+
+type:::
+
+Must be set to `num_connections`.
+
+treshold:::
+
+Treshold value, which must be a `non_neg_integer`. When the
+number of connections under a connection supervisor reaches
+or exceeds this value, The alarm will trigger and call
+the function defined in the `callback` key (see below).
+
+callback:::
+
+The alarm function, which takes the listener name, the alarm
+name, the pid of the connection supervisor and a list of the pids
+of all connection processes under that supervisor as arguments.
+The return value is ignored.
+
+cooldown (5000):::
+
+The minimum time after which the alarm can be triggered again,
+in milliseconds.
+
 connection_type (worker)::
 
 Type of process that will handle the connection.
diff --git a/src/ranch_conns_sup.erl b/src/ranch_conns_sup.erl
index fcf5927..66ee488 100644
--- a/src/ranch_conns_sup.erl
+++ b/src/ranch_conns_sup.erl
@@ -43,7 +43,7 @@
 	handshake_timeout :: timeout(),
 	max_conns = undefined :: ranch:max_conns(),
 	stats_counters_ref :: counters:counters_ref(),
-	alarms = #{} :: #{term() => {undefined | reference(), map()}},
+	alarms = #{} :: #{term() => {map(), undefined | reference()}},
 	logger = undefined :: module()
 }).
 
-- 
cgit v1.2.3