Add post-listen callback

2 files changed, 20 insertions, 8 deletions

diff --git a/doc/src/manual/ranch.asciidoc b/doc/src/manual/ranch.asciidoc
index ed57236..6dffb7f 100644
--- a/doc/src/manual/ranch.asciidoc
+++ b/doc/src/manual/ranch.asciidoc
@@ -93,14 +93,15 @@ Unique name used to refer to a listener.
 [source,erlang]
 ----
 transport_opts(SocketOpts) = #{
-    connection_type   => worker | supervisor,
-    handshake_timeout => timeout(),
-    max_connections   => max_conns(),
-    logger            => module(),
-    num_acceptors     => pos_integer(),
-    num_conns_sups    => pos_integer(),
-    shutdown          => timeout() | brutal_kill,
-    socket_opts       => SocketOpts
+    connection_type      => worker | supervisor,
+    handshake_timeout    => timeout(),
+    max_connections      => max_conns(),
+    logger               => module(),
+    num_acceptors        => pos_integer(),
+    num_conns_sups       => pos_integer(),
+    post_listen_callback => fun((term()) -> ok | {error, term()}),
+    shutdown             => timeout() | brutal_kill,
+    socket_opts          => SocketOpts
 }
 ----
 
@@ -137,6 +138,16 @@ num_conns_sups - see below::
 Number of processes that supervise connection processes.
 If not specified, defaults to be equal to `num_acceptors`.
 
+post_listen_callback (fun(_ListenSock) -> ok end)::
+
+A function which will be called after a listen socket has been successfully
+created, with the socket as argument. It can be used to perform any
+necessary setup steps on the socket.
++
+If the callback function returns `ok`, the listener will start accepting
+connections on the socket. If it returns `{error, Reason}`, the listener
+will fail to start.
+
 shutdown (5000)::
 
 Maximum allowed time for children to stop on listener shutdown.
diff --git a/doc/src/manual/ranch.set_transport_options.asciidoc b/doc/src/manual/ranch.set_transport_options.asciidoc
index 8c2eacb..125d037 100644
--- a/doc/src/manual/ranch.set_transport_options.asciidoc
+++ b/doc/src/manual/ranch.set_transport_options.asciidoc
@@ -29,6 +29,7 @@ Changes to the following options will take effect...
 * only after the listener has been suspended and resumed:
 ** `num_acceptors`
 ** `num_listen_sockets`
+** `post_listen_callback`
 ** `socket_opts`
 * only when the entire listener is restarted:
 ** `connection_type`