From 2730f7188738cc7b1100e50bcc8567d33ecb3934 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 31 May 2017 14:11:38 +0200 Subject: Deprecated ranch:start_listener/6 and child_spec/6 The NumAcceptors argument has been moved to transport option num_acceptor, which defaults to 10. The functions now take one less argument. The old functions are still here, though deprecated. --- doc/src/guide/embedded.asciidoc | 2 +- doc/src/guide/internals.asciidoc | 2 +- doc/src/guide/listeners.asciidoc | 32 +++++++++++++++++++++++++------- doc/src/guide/protocols.asciidoc | 2 +- doc/src/guide/ssl_auth.asciidoc | 2 +- 5 files changed, 29 insertions(+), 11 deletions(-) (limited to 'doc/src/guide') diff --git a/doc/src/guide/embedded.asciidoc b/doc/src/guide/embedded.asciidoc index 593a807..55c018b 100644 --- a/doc/src/guide/embedded.asciidoc +++ b/doc/src/guide/embedded.asciidoc @@ -17,7 +17,7 @@ regardless of the number of listeners you will use. Then you need to add the child specs for each listener. Ranch has a convenience function for getting the listeners child specs -called `ranch:child_spec/6`, that works like `ranch:start_listener/6`, +called `ranch:child_spec/5`, that works like `ranch:start_listener/5`, except that it doesn't start anything, it only returns child specs. As for `ranch_sup`, the child spec is simple enough to not require a diff --git a/doc/src/guide/internals.asciidoc b/doc/src/guide/internals.asciidoc index fa63f1d..c5bde58 100644 --- a/doc/src/guide/internals.asciidoc +++ b/doc/src/guide/internals.asciidoc @@ -47,7 +47,7 @@ that new process. === Number of acceptors -The second argument to `ranch:start_listener/6` is the number of +The second argument to `ranch:start_listener/5` is the number of processes that will be accepting connections. Care should be taken when choosing this number. diff --git a/doc/src/guide/listeners.asciidoc b/doc/src/guide/listeners.asciidoc index 1055b80..97afa22 100644 --- a/doc/src/guide/listeners.asciidoc +++ b/doc/src/guide/listeners.asciidoc @@ -26,7 +26,7 @@ When starting a listener, a number of different settings are required: Ranch includes both TCP and SSL transport handlers, respectively `ranch_tcp` and `ranch_ssl`. -A listener can be started by calling the `ranch:start_listener/6` +A listener can be started by calling the `ranch:start_listener/5` function. Before doing so however, you must ensure that the `ranch` application is started. @@ -42,7 +42,7 @@ to the `echo_protocol` handler. .Starting a listener for TCP connections on port 5555 [source,erlang] -{ok, _} = ranch:start_listener(tcp_echo, 100, +{ok, _} = ranch:start_listener(tcp_echo, ranch_tcp, [{port, 5555}], echo_protocol, [] ). @@ -108,12 +108,12 @@ the port number 0, or if you omit the port number entirely, Ranch will start listening on a random port. You can retrieve this port number by calling `ranch:get_port/1`. The -argument is the name of the listener you gave in `ranch:start_listener/6`. +argument is the name of the listener you gave in `ranch:start_listener/5`. .Starting a listener for TCP connections on a random port [source,erlang] -{ok, _} = ranch:start_listener(tcp_echo, 100, +{ok, _} = ranch:start_listener(tcp_echo, ranch_tcp, [{port, 0}], echo_protocol, [] ). @@ -159,7 +159,7 @@ connections are handled optimally. .Customizing the maximum number of concurrent connections [source,erlang] -{ok, _} = ranch:start_listener(tcp_echo, 100, +{ok, _} = ranch:start_listener(tcp_echo, ranch_tcp, [{port, 5555}, {max_connections, 100}], echo_protocol, [] ). @@ -169,7 +169,7 @@ You can disable this limit by setting its value to the atom `infinity`. .Disabling the limit for the number of connections [source,erlang] -{ok, _} = ranch:start_listener(tcp_echo, 100, +{ok, _} = ranch:start_listener(tcp_echo, ranch_tcp, [{port, 5555}, {max_connections, infinity}], echo_protocol, [] ). @@ -213,6 +213,24 @@ ranch:set_max_connections(tcp_echo, MaxConns). The change will occur immediately. +=== Customizing the number of acceptor processes + +By default Ranch will use 10 acceptor processes. Their role is +to accept connections and spawn a connection process for every +new connection. + +This number can be tweaked to improve performance. A good +number is typically between 10 or 100 acceptors. You must +measure to find the best value for your application. + +.Specifying a custom number of acceptor processes + +[source,erlang] +{ok, _} = ranch:start_listener(tcp_echo, + ranch_tcp, [{port, 5555}, {num_acceptors, 42}], + echo_protocol, [] +). + === When running out of file descriptors Operating systems have limits on the number of sockets @@ -278,7 +296,7 @@ calling `ranch:get_protocol_options/1`. [source,erlang] Opts = ranch:get_protocol_options(tcp_echo). -=== Obtain information about listeners +=== Obtaining information about listeners Ranch provides two functions for retrieving information about the listeners, for reporting and diagnostic purposes. diff --git a/doc/src/guide/protocols.asciidoc b/doc/src/guide/protocols.asciidoc index 48c74ef..b9a31f2 100644 --- a/doc/src/guide/protocols.asciidoc +++ b/doc/src/guide/protocols.asciidoc @@ -10,7 +10,7 @@ which defines a single callback, `start_link/4`. This callback is responsible for spawning a new process for handling the connection. It receives four arguments: the name of the listener, the socket, the transport handler being used and the protocol options defined in -the call to `ranch:start_listener/6`. This callback must +the call to `ranch:start_listener/5`. This callback must return `{ok, Pid}`, with `Pid` the pid of the new process. The newly started process can then freely initialize itself. However, diff --git a/doc/src/guide/ssl_auth.asciidoc b/doc/src/guide/ssl_auth.asciidoc index de0bbaf..de16107 100644 --- a/doc/src/guide/ssl_auth.asciidoc +++ b/doc/src/guide/ssl_auth.asciidoc @@ -49,7 +49,7 @@ the listener to enable this behavior. .Configure a listener for SSL authentication [source,erlang] -{ok, _} = ranch:start_listener(my_ssl, 100, +{ok, _} = ranch:start_listener(my_ssl, ranch_ssl, [ {port, SSLPort}, {certfile, PathToCertfile}, -- cgit v1.2.3