Browse Source

Document connection draining on application shutdown

juhlig 5 years ago
parent
commit
91468482f4
1 changed files with 30 additions and 1 deletions
  1. 30 1
      doc/src/guide/connection_draining.asciidoc

+ 30 - 1
doc/src/guide/connection_draining.asciidoc

@@ -6,7 +6,7 @@ a listener in a graceful fashion, ie by not accepting any new connections,
 but allowing the existing connection processes to exit by themselves instead
 but allowing the existing connection processes to exit by themselves instead
 of being killed.
 of being killed.
 
 
-For this purpose, you should first suspend the listeners you wish to
+For this purpose, you should first suspend the listener you wish to
 stop gracefully, and then wait for its connection count to drop to
 stop gracefully, and then wait for its connection count to drop to
 zero.
 zero.
 
 
@@ -67,3 +67,32 @@ after DrainTimeout ->
 end,
 end,
 ok = ranch:stop_listener(Ref).
 ok = ranch:stop_listener(Ref).
 ----
 ----
+
+To drain listeners automatically as part of your application shutdown routine,
+use the `prep_stop/1` function of your application module.
+
+.Draining listeners automatically on application shutdown
+
+[source,erlang]
+----
+-module(my_app).
+
+-behavior(application).
+
+-export([start/2]).
+-export([prep_stop/1]).
+-export([stop/1]).
+
+start(_StartType, _StartArgs) ->
+	{ok, _} = ranch:start_listener(my_listener, ranch_tcp, #{}, my_protocol, []),
+	my_app_sup:start_link().
+
+prep_stop(State) ->
+	ok = ranch:suspend_listener(my_listener),
+	ok = ranch:wait_for_connections(my_listener, '==', 0),
+	ok = ranch:stop_listener(my_listener),
+	State.
+
+stop(_State) ->
+	ok.
+----