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/manual/ranch.asciidoc | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

(limited to 'doc/src/manual/ranch.asciidoc')

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.
-- 
cgit v1.2.3