aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/src/guide/listeners.asciidoc38
-rw-r--r--doc/src/manual/ranch.asciidoc27
-rw-r--r--doc/src/manual/ranch.set_transport_options.asciidoc1
3 files changed, 58 insertions, 8 deletions
diff --git a/doc/src/guide/listeners.asciidoc b/doc/src/guide/listeners.asciidoc
index 0aee43c..779497c 100644
--- a/doc/src/guide/listeners.asciidoc
+++ b/doc/src/guide/listeners.asciidoc
@@ -177,6 +177,44 @@ file must not exist: Ranch must be able to create it.
]}, echo_protocol, []
).
+=== Performing additional setup steps on a listening socket
+
+If it is necessary to perform additional setup steps on the listening
+socket, it is possible to specify a function with the transport option
+`post_listen_callback`. This function will be called after the listening
+socket has been created but before accepting connections on it,
+with the socket as the single argument.
+
+The function must return either the atom `ok`, after which the listener
+will start accepting connections on the socket, or a tuple
+`{error, Reason}` which will cause the listener to fail starting with
+`Reason`.
+
+.Setting permissions on a UNIX Domain socket file
+
+[source,erlang]
+----
+PostListenCb = fun (Sock) ->
+ case ranch_tcp:sockname(Sock) of
+ {ok, {local, SockFile}} ->
+ file:change_mode(SockFile, 8#777);
+ {ok, _} ->
+ ok;
+ Error = {error, _} ->
+ Error
+ end
+end,
+
+{ok, _} = ranch:start_listener(tcp_echo,
+ ranch_tcp, #{
+ socket_opts => [
+ {ip, {local, "/tmp/ranch_echo.sock"}},
+ {port, 0}],
+ post_listen_callback => PostListenCb},
+ echo_protocol, []
+).
+----
+
=== Accepting connections on an existing socket
If you want to accept connections on an existing socket, you can write
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`