diff options
Diffstat (limited to 'doc/src/manual/ranch.wait_for_connections.asciidoc')
-rw-r--r-- | doc/src/manual/ranch.wait_for_connections.asciidoc | 76 |
1 files changed, 76 insertions, 0 deletions
diff --git a/doc/src/manual/ranch.wait_for_connections.asciidoc b/doc/src/manual/ranch.wait_for_connections.asciidoc new file mode 100644 index 0000000..3fdc2a1 --- /dev/null +++ b/doc/src/manual/ranch.wait_for_connections.asciidoc @@ -0,0 +1,76 @@ += ranch:wait_for_connections(3) + +== Name + +ranch:wait_for_connections - Wait for a specific number of connections + +== Description + +[source,erlang] +---- +wait_for_connections(Ref :: ranch:ref(), + Operator, + NumConns :: non_neg_integer()) + -> ok + +Operator :: '>' | '>=' | '==' | '=<' | '<' +---- + +Wait for a specific number of connections. + +This function waits until the number of connections on the +given listener becomes higher than, equal to or lower than +the given number. It never returns otherwise. + +This function can be used to gracefully shutdown a listener +by first suspending the listener and then waiting for +connections to terminate before finally stopping the listener. + +// @todo The suspend/wait/stop pattern should be tested. + +== Arguments + +Ref:: + +The listener name. + +Operator:: + +The operator to use for the comparison. + +NumConns:: + +The number of connections to reach. + +== Return value + +The atom `ok` is always returned. It can be safely ignored. + +== Changelog + +* *1.6*: Function introduced. + +== Examples + +.Wait for at least 100 connections +[source,erlang] +---- +ranch:wait_for_connections(example, '>=', 100). +---- + +.Gracefully shutdown a listener +[source,erlang] +---- +Ref = example, + +ok = ranch:suspend_listener(Ref), +ranch:wait_for_connections(Ref, '==', 0), +ok = ranch:stop_listener(Ref). +---- + +== See also + +link:man:ranch:stop_listener(3)[ranch:stop_listener(3)], +link:man:ranch:suspend_listener(3)[ranch:suspend_listener(3)], +link:man:ranch:resume_listener(3)[ranch:resume_listener(3)], +link:man:ranch(3)[ranch(3)] |