summaryrefslogtreecommitdiffstats
path: root/docs/en/ranch/1.3/guide/listeners/index.html
diff options
context:
space:
mode:
Diffstat (limited to 'docs/en/ranch/1.3/guide/listeners/index.html')
-rw-r--r--docs/en/ranch/1.3/guide/listeners/index.html727
1 files changed, 365 insertions, 362 deletions
diff --git a/docs/en/ranch/1.3/guide/listeners/index.html b/docs/en/ranch/1.3/guide/listeners/index.html
index 6cc4d0a1..bb7f3310 100644
--- a/docs/en/ranch/1.3/guide/listeners/index.html
+++ b/docs/en/ranch/1.3/guide/listeners/index.html
@@ -7,7 +7,7 @@
<meta name="description" content="">
<meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara">
- <meta name="generator" content="Hugo 0.17" />
+ <meta name="generator" content="Hugo 0.26" />
<title>Nine Nines: Listeners</title>
@@ -67,373 +67,376 @@
<h1 class="lined-header"><span>Listeners</span></h1>
-<div class="paragraph"><p>A listener is a set of processes whose role is to listen on a port
-for new connections. It manages a pool of acceptor processes, each
-of them indefinitely accepting connections. When it does, it starts
-a new process executing the protocol handler code. All the socket
-programming is abstracted through the use of transport handlers.</p></div>
-<div class="paragraph"><p>The listener takes care of supervising all the acceptor and connection
-processes, allowing developers to focus on building their application.</p></div>
-<div class="sect1">
-<h2 id="_starting_a_listener">Starting a listener</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch does nothing by default. It is up to the application developer
-to request that Ranch listens for connections.</p></div>
-<div class="paragraph"><p>A listener can be started and stopped at will.</p></div>
-<div class="paragraph"><p>When starting a listener, a number of different settings are required:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-A name to identify it locally and be able to interact with it.
-</p>
-</li>
-<li>
-<p>
-The number of acceptors in the pool.
-</p>
-</li>
-<li>
-<p>
-A transport handler and its associated options.
-</p>
-</li>
-<li>
-<p>
-A protocol handler and its associated options.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Ranch includes both TCP and SSL transport handlers, respectively
-<code>ranch_tcp</code> and <code>ranch_ssl</code>.</p></div>
-<div class="paragraph"><p>A listener can be started by calling the <code>ranch:start_listener/5</code>
-function. Before doing so however, you must ensure that the <code>ranch</code>
-application is started.</p></div>
-<div class="listingblock">
-<div class="title">Starting the Ranch application</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">application:start</span></span>(<span style="color: #FF6600">ranch</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You are then ready to start a listener. Let&#8217;s call it <code>tcp_echo</code>. It will
-have a pool of 100 acceptors, use a TCP transport and forward connections
-to the <code>echo_protocol</code> handler.</p></div>
-<div class="listingblock">
-<div class="title">Starting a listener for TCP connections on port 5555</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
-)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can try this out by compiling and running the <code>tcp_echo</code> example in the
-examples directory. To do so, open a shell in the <em>examples/tcp_echo/</em>
-directory and run the following command:</p></div>
-<div class="listingblock">
-<div class="title">Building and starting a Ranch example</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>$ make run</tt></pre></div></div>
-<div class="paragraph"><p>You can then connect to it using telnet and see the echo server reply
-everything you send to it. Then when you&#8217;re done testing, you can use
-the <code>Ctrl+]</code> key to escape to the telnet command line and type
-<code>quit</code> to exit.</p></div>
-<div class="listingblock">
-<div class="title">Connecting to the example listener with telnet</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>$ telnet localhost <span style="color: #993399">5555</span>
-Trying <span style="color: #993399">127.0</span><span style="color: #990000">.</span><span style="color: #993399">0.1</span><span style="color: #990000">...</span>
-Connected to localhost<span style="color: #990000">.</span>
-Escape character is <span style="color: #FF0000">'^]'</span><span style="color: #990000">.</span>
-Hello<span style="color: #990000">!</span>
-Hello<span style="color: #990000">!</span>
-It works<span style="color: #990000">!</span>
-It works<span style="color: #990000">!</span>
-<span style="color: #990000">^]</span>
-
-telnet<span style="color: #990000">&gt;</span> quit
-Connection closed<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_stopping_a_listener">Stopping a listener</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>All you need to stop a Ranch listener is to call the
-<code>ranch:stop_listener/1</code> function with the listener&#8217;s name
-as argument. In the previous section we started the listener
-named <code>tcp_echo</code>. We can now stop it.</p></div>
-<div class="listingblock">
-<div class="title">Stopping a listener</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">ranch:stop_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_default_transport_options">Default transport options</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>By default the socket will be set to return <code>binary</code> data, with the
-options <code>{active, false}</code>, <code>{packet, raw}</code>, <code>{reuseaddr, true}</code> set.
-These values can&#8217;t be overriden when starting the listener, but
-they can be overriden using <code>Transport:setopts/2</code> in the protocol.</p></div>
-<div class="paragraph"><p>It will also set <code>{backlog, 1024}</code> and <code>{nodelay, true}</code>, which
-can be overriden at listener startup.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_listening_on_a_random_port">Listening on a random port</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You do not have to specify a specific port to listen on. If you give
-the port number 0, or if you omit the port number entirely, Ranch will
-start listening on a random port.</p></div>
-<div class="paragraph"><p>You can retrieve this port number by calling <code>ranch:get_port/1</code>. The
-argument is the name of the listener you gave in <code>ranch:start_listener/5</code>.</p></div>
-<div class="listingblock">
-<div class="title">Starting a listener for TCP connections on a random port</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">0</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
-)<span style="color: #990000">.</span>
-<span style="color: #009900">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_port</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_listening_on_privileged_ports">Listening on privileged ports</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Some systems limit access to ports below 1024 for security reasons.
-This can easily be identified by an <code>{error, eacces}</code> error when trying
-to open a listening socket on such a port.</p></div>
-<div class="paragraph"><p>The methods for listening on privileged ports vary between systems,
-please refer to your system&#8217;s documentation for more information.</p></div>
-<div class="paragraph"><p>We recommend the use of port rewriting for systems with a single server,
-and load balancing for systems with multiple servers. Documenting these
-solutions is however out of the scope of this guide.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_accepting_connections_on_an_existing_socket">Accepting connections on an existing socket</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>If you want to accept connections on an existing socket, you can use the
-<code>socket</code> transport option, which should just be the relevant data returned
-from the connect function for the transport or the underlying socket library
-(<code>gen_tcp:connect</code>, <code>ssl:connect</code>). The accept function will then be
-called on the passed in socket. You should connect the socket in
-<code>{active, false}</code> mode, as well.</p></div>
-<div class="paragraph"><p>Note, however, that because of a bug in SSL, you cannot change ownership of an
-SSL listen socket prior to R16. Ranch will catch the error thrown, but the
-owner of the SSL socket will remain as whatever process created the socket.
-However, this will not affect accept behaviour unless the owner process dies,
-in which case the socket is closed. Therefore, to use this feature with SSL
-with an erlang release prior to R16, ensure that the SSL socket is opened in a
-persistant process.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_limiting_the_number_of_concurrent_connections">Limiting the number of concurrent connections</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>max_connections</code> transport option allows you to limit the number
-of concurrent connections. It defaults to 1024. Its purpose is to
-prevent your system from being overloaded and ensuring all the
-connections are handled optimally.</p></div>
-<div class="listingblock">
-<div class="title">Customizing the maximum number of concurrent connections</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">max_connections</span>, <span style="color: #993399">100</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
-)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can disable this limit by setting its value to the atom <code>infinity</code>.</p></div>
-<div class="listingblock">
-<div class="title">Disabling the limit for the number of connections</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">max_connections</span>, <span style="color: #FF6600">infinity</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
-)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The maximum number of connections is a soft limit. In practice, it
-can reach <code>max_connections</code> + the number of acceptors.</p></div>
-<div class="paragraph"><p>When the maximum number of connections is reached, Ranch will stop
-accepting connections. This will not result in further connections
-being rejected, as the kernel option allows queueing incoming
-connections. The size of this queue is determined by the <code>backlog</code>
-option and defaults to 1024. Ranch does not know about the number
-of connections that are in the backlog.</p></div>
-<div class="paragraph"><p>You may not always want connections to be counted when checking for
-<code>max_connections</code>. For example you might have a protocol where both
-short-lived and long-lived connections are possible. If the long-lived
-connections are mostly waiting for messages, then they don&#8217;t consume
-much resources and can safely be removed from the count.</p></div>
-<div class="paragraph"><p>To remove the connection from the count, you must call the
-<code>ranch:remove_connection/1</code> from within the connection process,
-with the name of the listener as the only argument.</p></div>
-<div class="listingblock">
-<div class="title">Removing a connection from the count of connections</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">ranch:remove_connection</span></span>(<span style="color: #009900">Ref</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>As seen in the chapter covering protocols, this pid is received as the
-first argument of the protocol&#8217;s <code>start_link/4</code> callback.</p></div>
-<div class="paragraph"><p>You can modify the <code>max_connections</code> value on a running listener by
-using the <code>ranch:set_max_connections/2</code> function, with the name of the
-listener as first argument and the new value as the second.</p></div>
-<div class="listingblock">
-<div class="title">Upgrading the maximum number of connections</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">ranch:set_max_connections</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #009900">MaxConns</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The change will occur immediately.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_customizing_the_number_of_acceptor_processes">Customizing the number of acceptor processes</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>By default Ranch will use 10 acceptor processes. Their role is
-to accept connections and spawn a connection process for every
-new connection.</p></div>
-<div class="paragraph"><p>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.</p></div>
-<div class="listingblock">
-<div class="title">Specifying a custom number of acceptor processes</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">num_acceptors</span>, <span style="color: #993399">42</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
-)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_when_running_out_of_file_descriptors">When running out of file descriptors</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Operating systems have limits on the number of sockets
-which can be opened by applications. When this maximum is
-reached the listener can no longer accept new connections. The
-accept rate of the listener will be automatically reduced, and a
-warning message will be logged.</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>=ERROR REPORT==== 13-Jan-2016::12:24:38 ===
-Ranch acceptor reducing accept rate: out of file descriptors</code></pre>
-</div></div>
-<div class="paragraph"><p>If you notice messages like this you should increase the number
-of file-descriptors which can be opened by your application. How
-this should be done is operating-system dependent. Please consult
-the documentation of your operating system.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_using_a_supervisor_for_connection_processes">Using a supervisor for connection processes</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch allows you to define the type of process that will be used
-for the connection processes. By default it expects a <code>worker</code>.
-When the <code>connection_type</code> configuration value is set to <code>supervisor</code>,
-Ranch will consider that the connection process it manages is a
-supervisor and will reflect that in its supervision tree.</p></div>
-<div class="paragraph"><p>Connection processes of type <code>supervisor</code> can either handle the
-socket directly or through one of their children. In the latter
-case the start function for the connection process must return
-two pids: the pid of the supervisor you created (that will be
-supervised) and the pid of the protocol handling process (that
-will receive the socket).</p></div>
-<div class="paragraph"><p>Instead of returning <code>{ok, ConnPid}</code>, simply return
-<code>{ok, SupPid, ConnPid}</code>.</p></div>
-<div class="paragraph"><p>It is very important that the connection process be created
-under the supervisor process so that everything works as intended.
-If not, you will most likely experience issues when the supervised
-process is stopped.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_upgrading">Upgrading</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch allows you to upgrade the protocol options. This takes effect
-immediately and for all subsequent connections.</p></div>
-<div class="paragraph"><p>To upgrade the protocol options, call <code>ranch:set_protocol_options/2</code>
-with the name of the listener as first argument and the new options
-as the second.</p></div>
-<div class="listingblock">
-<div class="title">Upgrading the protocol options</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">ranch:set_protocol_options</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #009900">NewOpts</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>All future connections will use the new options.</p></div>
-<div class="paragraph"><p>You can also retrieve the current options similarly by
-calling <code>ranch:get_protocol_options/1</code>.</p></div>
-<div class="listingblock">
-<div class="title">Retrieving the current protocol options</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">Opts</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_protocol_options</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_obtaining_information_about_listeners">Obtaining information about listeners</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch provides two functions for retrieving information about the
-listeners, for reporting and diagnostic purposes.</p></div>
-<div class="paragraph"><p>The <code>ranch:info/0</code> function will return detailed information
-about all listeners.</p></div>
-<div class="listingblock">
-<div class="title">Retrieving detailed information</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">ranch:info</span></span>()<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The <code>ranch:procs/2</code> function will return all acceptor or listener
-processes for a given listener.</p></div>
-<div class="listingblock">
-<div class="title">Get all acceptor processes</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">ranch:procs</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #FF6600">acceptors</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Get all connection processes</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">ranch:procs</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #FF6600">connections</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
+<div class="paragraph"><p>A listener is a set of processes whose role is to listen on a port
+for new connections. It manages a pool of acceptor processes, each
+of them indefinitely accepting connections. When it does, it starts
+a new process executing the protocol handler code. All the socket
+programming is abstracted through the use of transport handlers.</p></div>
+<div class="paragraph"><p>The listener takes care of supervising all the acceptor and connection
+processes, allowing developers to focus on building their application.</p></div>
+<div class="sect1">
+<h2 id="_starting_a_listener">Starting a listener</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Ranch does nothing by default. It is up to the application developer
+to request that Ranch listens for connections.</p></div>
+<div class="paragraph"><p>A listener can be started and stopped at will.</p></div>
+<div class="paragraph"><p>When starting a listener, a number of different settings are required:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+A name to identify it locally and be able to interact with it.
+</p>
+</li>
+<li>
+<p>
+The number of acceptors in the pool.
+</p>
+</li>
+<li>
+<p>
+A transport handler and its associated options.
+</p>
+</li>
+<li>
+<p>
+A protocol handler and its associated options.
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>Ranch includes both TCP and SSL transport handlers, respectively
+<code>ranch_tcp</code> and <code>ranch_ssl</code>.</p></div>
+<div class="paragraph"><p>A listener can be started by calling the <code>ranch:start_listener/5</code>
+function. Before doing so however, you must ensure that the <code>ranch</code>
+application is started.</p></div>
+<div class="listingblock">
+<div class="title">Starting the Ranch application</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">application:start</span></span>(<span style="color: #FF6600">ranch</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>You are then ready to start a listener. Let&#8217;s call it <code>tcp_echo</code>. It will
+have a pool of 100 acceptors, use a TCP transport and forward connections
+to the <code>echo_protocol</code> handler.</p></div>
+<div class="listingblock">
+<div class="title">Starting a listener for TCP connections on port 5555</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>,
+ <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}],
+ <span style="color: #FF6600">echo_protocol</span>, []
+)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>You can try this out by compiling and running the <code>tcp_echo</code> example in the
+examples directory. To do so, open a shell in the <em>examples/tcp_echo/</em>
+directory and run the following command:</p></div>
+<div class="listingblock">
+<div class="title">Building and starting a Ranch example</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>$ make run</tt></pre></div></div>
+<div class="paragraph"><p>You can then connect to it using telnet and see the echo server reply
+everything you send to it. Then when you&#8217;re done testing, you can use
+the <code>Ctrl+]</code> key to escape to the telnet command line and type
+<code>quit</code> to exit.</p></div>
+<div class="listingblock">
+<div class="title">Connecting to the example listener with telnet</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>$ telnet localhost <span style="color: #993399">5555</span>
+Trying <span style="color: #993399">127.0</span><span style="color: #990000">.</span><span style="color: #993399">0.1</span><span style="color: #990000">...</span>
+Connected to localhost<span style="color: #990000">.</span>
+Escape character is <span style="color: #FF0000">'^]'</span><span style="color: #990000">.</span>
+Hello<span style="color: #990000">!</span>
+Hello<span style="color: #990000">!</span>
+It works<span style="color: #990000">!</span>
+It works<span style="color: #990000">!</span>
+<span style="color: #990000">^]</span>
+
+telnet<span style="color: #990000">&gt;</span> quit
+Connection closed<span style="color: #990000">.</span></tt></pre></div></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_stopping_a_listener">Stopping a listener</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>All you need to stop a Ranch listener is to call the
+<code>ranch:stop_listener/1</code> function with the listener&#8217;s name
+as argument. In the previous section we started the listener
+named <code>tcp_echo</code>. We can now stop it.</p></div>
+<div class="listingblock">
+<div class="title">Stopping a listener</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">ranch:stop_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_default_transport_options">Default transport options</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>By default the socket will be set to return <code>binary</code> data, with the
+options <code>{active, false}</code>, <code>{packet, raw}</code>, <code>{reuseaddr, true}</code> set.
+These values can&#8217;t be overriden when starting the listener, but
+they can be overriden using <code>Transport:setopts/2</code> in the protocol.</p></div>
+<div class="paragraph"><p>It will also set <code>{backlog, 1024}</code> and <code>{nodelay, true}</code>, which
+can be overriden at listener startup.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_listening_on_a_random_port">Listening on a random port</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>You do not have to specify a specific port to listen on. If you give
+the port number 0, or if you omit the port number entirely, Ranch will
+start listening on a random port.</p></div>
+<div class="paragraph"><p>You can retrieve this port number by calling <code>ranch:get_port/1</code>. The
+argument is the name of the listener you gave in <code>ranch:start_listener/5</code>.</p></div>
+<div class="listingblock">
+<div class="title">Starting a listener for TCP connections on a random port</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>,
+ <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">0</span>}],
+ <span style="color: #FF6600">echo_protocol</span>, []
+)<span style="color: #990000">.</span>
+<span style="color: #009900">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_port</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_listening_on_privileged_ports">Listening on privileged ports</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Some systems limit access to ports below 1024 for security reasons.
+This can easily be identified by an <code>{error, eacces}</code> error when trying
+to open a listening socket on such a port.</p></div>
+<div class="paragraph"><p>The methods for listening on privileged ports vary between systems,
+please refer to your system&#8217;s documentation for more information.</p></div>
+<div class="paragraph"><p>We recommend the use of port rewriting for systems with a single server,
+and load balancing for systems with multiple servers. Documenting these
+solutions is however out of the scope of this guide.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_accepting_connections_on_an_existing_socket">Accepting connections on an existing socket</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>If you want to accept connections on an existing socket, you can use the
+<code>socket</code> transport option, which should just be the relevant data returned
+from the connect function for the transport or the underlying socket library
+(<code>gen_tcp:connect</code>, <code>ssl:connect</code>). The accept function will then be
+called on the passed in socket. You should connect the socket in
+<code>{active, false}</code> mode, as well.</p></div>
+<div class="paragraph"><p>Note, however, that because of a bug in SSL, you cannot change ownership of an
+SSL listen socket prior to R16. Ranch will catch the error thrown, but the
+owner of the SSL socket will remain as whatever process created the socket.
+However, this will not affect accept behaviour unless the owner process dies,
+in which case the socket is closed. Therefore, to use this feature with SSL
+with an erlang release prior to R16, ensure that the SSL socket is opened in a
+persistant process.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_limiting_the_number_of_concurrent_connections">Limiting the number of concurrent connections</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The <code>max_connections</code> transport option allows you to limit the number
+of concurrent connections. It defaults to 1024. Its purpose is to
+prevent your system from being overloaded and ensuring all the
+connections are handled optimally.</p></div>
+<div class="listingblock">
+<div class="title">Customizing the maximum number of concurrent connections</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>,
+ <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">max_connections</span>, <span style="color: #993399">100</span>}],
+ <span style="color: #FF6600">echo_protocol</span>, []
+)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>You can disable this limit by setting its value to the atom <code>infinity</code>.</p></div>
+<div class="listingblock">
+<div class="title">Disabling the limit for the number of connections</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>,
+ <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">max_connections</span>, <span style="color: #FF6600">infinity</span>}],
+ <span style="color: #FF6600">echo_protocol</span>, []
+)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>The maximum number of connections is a soft limit. In practice, it
+can reach <code>max_connections</code> + the number of acceptors.</p></div>
+<div class="paragraph"><p>When the maximum number of connections is reached, Ranch will stop
+accepting connections. This will not result in further connections
+being rejected, as the kernel option allows queueing incoming
+connections. The size of this queue is determined by the <code>backlog</code>
+option and defaults to 1024. Ranch does not know about the number
+of connections that are in the backlog.</p></div>
+<div class="paragraph"><p>You may not always want connections to be counted when checking for
+<code>max_connections</code>. For example you might have a protocol where both
+short-lived and long-lived connections are possible. If the long-lived
+connections are mostly waiting for messages, then they don&#8217;t consume
+much resources and can safely be removed from the count.</p></div>
+<div class="paragraph"><p>To remove the connection from the count, you must call the
+<code>ranch:remove_connection/1</code> from within the connection process,
+with the name of the listener as the only argument.</p></div>
+<div class="listingblock">
+<div class="title">Removing a connection from the count of connections</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">ranch:remove_connection</span></span>(<span style="color: #009900">Ref</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>As seen in the chapter covering protocols, this pid is received as the
+first argument of the protocol&#8217;s <code>start_link/4</code> callback.</p></div>
+<div class="paragraph"><p>You can modify the <code>max_connections</code> value on a running listener by
+using the <code>ranch:set_max_connections/2</code> function, with the name of the
+listener as first argument and the new value as the second.</p></div>
+<div class="listingblock">
+<div class="title">Upgrading the maximum number of connections</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">ranch:set_max_connections</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #009900">MaxConns</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>The change will occur immediately.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_customizing_the_number_of_acceptor_processes">Customizing the number of acceptor processes</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>By default Ranch will use 10 acceptor processes. Their role is
+to accept connections and spawn a connection process for every
+new connection.</p></div>
+<div class="paragraph"><p>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.</p></div>
+<div class="listingblock">
+<div class="title">Specifying a custom number of acceptor processes</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>,
+ <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">num_acceptors</span>, <span style="color: #993399">42</span>}],
+ <span style="color: #FF6600">echo_protocol</span>, []
+)<span style="color: #990000">.</span></tt></pre></div></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_when_running_out_of_file_descriptors">When running out of file descriptors</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Operating systems have limits on the number of sockets
+which can be opened by applications. When this maximum is
+reached the listener can no longer accept new connections. The
+accept rate of the listener will be automatically reduced, and a
+warning message will be logged.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>=ERROR REPORT==== 13-Jan-2016::12:24:38 ===
+Ranch acceptor reducing accept rate: out of file descriptors</code></pre>
+</div></div>
+<div class="paragraph"><p>If you notice messages like this you should increase the number
+of file-descriptors which can be opened by your application. How
+this should be done is operating-system dependent. Please consult
+the documentation of your operating system.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_using_a_supervisor_for_connection_processes">Using a supervisor for connection processes</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Ranch allows you to define the type of process that will be used
+for the connection processes. By default it expects a <code>worker</code>.
+When the <code>connection_type</code> configuration value is set to <code>supervisor</code>,
+Ranch will consider that the connection process it manages is a
+supervisor and will reflect that in its supervision tree.</p></div>
+<div class="paragraph"><p>Connection processes of type <code>supervisor</code> can either handle the
+socket directly or through one of their children. In the latter
+case the start function for the connection process must return
+two pids: the pid of the supervisor you created (that will be
+supervised) and the pid of the protocol handling process (that
+will receive the socket).</p></div>
+<div class="paragraph"><p>Instead of returning <code>{ok, ConnPid}</code>, simply return
+<code>{ok, SupPid, ConnPid}</code>.</p></div>
+<div class="paragraph"><p>It is very important that the connection process be created
+under the supervisor process so that everything works as intended.
+If not, you will most likely experience issues when the supervised
+process is stopped.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_upgrading">Upgrading</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Ranch allows you to upgrade the protocol options. This takes effect
+immediately and for all subsequent connections.</p></div>
+<div class="paragraph"><p>To upgrade the protocol options, call <code>ranch:set_protocol_options/2</code>
+with the name of the listener as first argument and the new options
+as the second.</p></div>
+<div class="listingblock">
+<div class="title">Upgrading the protocol options</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">ranch:set_protocol_options</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #009900">NewOpts</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>All future connections will use the new options.</p></div>
+<div class="paragraph"><p>You can also retrieve the current options similarly by
+calling <code>ranch:get_protocol_options/1</code>.</p></div>
+<div class="listingblock">
+<div class="title">Retrieving the current protocol options</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #009900">Opts</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_protocol_options</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_obtaining_information_about_listeners">Obtaining information about listeners</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Ranch provides two functions for retrieving information about the
+listeners, for reporting and diagnostic purposes.</p></div>
+<div class="paragraph"><p>The <code>ranch:info/0</code> function will return detailed information
+about all listeners.</p></div>
+<div class="listingblock">
+<div class="title">Retrieving detailed information</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">ranch:info</span></span>()<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="paragraph"><p>The <code>ranch:procs/2</code> function will return all acceptor or listener
+processes for a given listener.</p></div>
+<div class="listingblock">
+<div class="title">Get all acceptor processes</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">ranch:procs</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #FF6600">acceptors</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+<div class="listingblock">
+<div class="title">Get all connection processes</div>
+<div class="content"><!-- Generator: GNU source-highlight 3.1.8
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="font-weight: bold"><span style="color: #000000">ranch:procs</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #FF6600">connections</span>)<span style="color: #990000">.</span></tt></pre></div></div>
+</div>
+</div>
+
+
+
<nav style="margin:1em 0">
generated by cgit v1.2.3 (git 2.25.1) at 2024-07-01 07:26:24 +0000