<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Module ranch</title>
<link rel="stylesheet" type="text/css" href="stylesheet.css" title="EDoc">
</head>
<body bgcolor="white">
<div class="navbar"><a name="#navbar_top"></a><table width="100%" border="0" cellspacing="0" cellpadding="2" summary="navigation bar"><tr><td><a href="overview-summary.html" target="overviewFrame">Overview</a></td><td><a href="http://www.erlang.org/"><img src="erlang.png" align="right" border="0" alt="erlang logo"></a></td></tr></table></div>
<hr>
<h1>Module ranch</h1>
<ul class="index"><li><a href="#description">Description</a></li><li><a href="#types">Data Types</a></li><li><a href="#index">Function Index</a></li><li><a href="#functions">Function Details</a></li></ul>Ranch API to start and stop listeners.
<h2><a name="description">Description</a></h2>Ranch API to start and stop listeners.
<h2><a name="types">Data Types</a></h2>
<h3 class="typedecl"><a name="type-max_conns">max_conns()</a></h3>
<p><tt>max_conns() = non_neg_integer() | infinity</tt></p>
<h2><a name="index">Function Index</a></h2>
<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#accept_ack-1">accept_ack/1</a></td><td>Acknowledge the accepted connection.</td></tr>
<tr><td valign="top"><a href="#child_spec-6">child_spec/6</a></td><td>Return a child spec suitable for embedding.</td></tr>
<tr><td valign="top"><a href="#filter_options-3">filter_options/3</a></td><td>Filter a list of options and remove all unwanted values.</td></tr>
<tr><td valign="top"><a href="#get_max_connections-1">get_max_connections/1</a></td><td>Return the max number of connections allowed concurrently.</td></tr>
<tr><td valign="top"><a href="#get_port-1">get_port/1</a></td><td>Return the listener's port.</td></tr>
<tr><td valign="top"><a href="#get_protocol_options-1">get_protocol_options/1</a></td><td>Return the current protocol options for the given listener.</td></tr>
<tr><td valign="top"><a href="#require-1">require/1</a></td><td>Start the given applications if they were not already started.</td></tr>
<tr><td valign="top"><a href="#set_max_connections-2">set_max_connections/2</a></td><td>Set the max number of connections allowed concurrently.</td></tr>
<tr><td valign="top"><a href="#set_option_default-3">set_option_default/3</a></td><td>Add an option to a list, but only if it wasn't previously set.</td></tr>
<tr><td valign="top"><a href="#set_protocol_options-2">set_protocol_options/2</a></td><td>Upgrade the protocol options for the given listener.</td></tr>
<tr><td valign="top"><a href="#start_listener-6">start_listener/6</a></td><td>Start a listener for the given transport and protocol.</td></tr>
<tr><td valign="top"><a href="#stop_listener-1">stop_listener/1</a></td><td>Stop a listener identified by <em>Ref</em>.</td></tr>
</table>
<h2><a name="functions">Function Details</a></h2>
<h3 class="function"><a name="accept_ack-1">accept_ack/1</a></h3>
<div class="spec">
<p><tt>accept_ack(ListenerPid::pid()) -> ok</tt><br></p>
</div><p><p>Acknowledge the accepted connection.</p>
Effectively used to make sure the socket control has been given to
the protocol process before starting to use it.</p>
<h3 class="function"><a name="child_spec-6">child_spec/6</a></h3>
<div class="spec">
<p><tt>child_spec(Ref::any(), NbAcceptors::non_neg_integer(), Transport::module(), TransOpts::any(), Protocol::module(), ProtoOpts::any()) -> <a href="supervisor.html#type-child_spec">supervisor:child_spec()</a></tt><br></p>
</div><p><p>Return a child spec suitable for embedding.</p>
When you want to embed Ranch in another application, you can use this
function to create a <em>ChildSpec</em> suitable for use in a supervisor.
The parameters are the same as in <em>start_listener/6</em> but rather
than hooking the listener to the Ranch internal supervisor, it just returns
the spec.</p>
<h3 class="function"><a name="filter_options-3">filter_options/3</a></h3>
<div class="spec">
<p><tt>filter_options(Tail::[{atom(), any()}], AllowedKeys::[atom()], Acc) -> Acc</tt>
<ul class="definitions"><li><tt>Acc = [any()]</tt></li></ul></p>
</div><p><p>Filter a list of options and remove all unwanted values.</p>
It takes a list of options, a list of allowed keys and an accumulator.
This accumulator can be used to set default options that should never
be overriden.</p>
<h3 class="function"><a name="get_max_connections-1">get_max_connections/1</a></h3>
<div class="spec">
<p><tt>get_max_connections(Ref::any()) -> <a href="#type-max_conns">max_conns()</a></tt><br></p>
</div><p>Return the max number of connections allowed concurrently.</p>
<h3 class="function"><a name="get_port-1">get_port/1</a></h3>
<div class="spec">
<p><tt>get_port(Ref::any()) -> <a href="inet.html#type-port_number">inet:port_number()</a></tt><br></p>
</div><p>Return the listener's port.</p>
<h3 class="function"><a name="get_protocol_options-1">get_protocol_options/1</a></h3>
<div class="spec">
<p><tt>get_protocol_options(Ref::any()) -> any()</tt><br></p>
</div><p>Return the current protocol options for the given listener.</p>
<h3 class="function"><a name="require-1">require/1</a></h3>
<div class="spec">
<p><tt>require(Tail::[module()]) -> ok</tt><br></p>
</div><p>Start the given applications if they were not already started.</p>
<h3 class="function"><a name="set_max_connections-2">set_max_connections/2</a></h3>
<div class="spec">
<p><tt>set_max_connections(Ref::any(), MaxConnections::<a href="#type-max_conns">max_conns()</a>) -> ok</tt><br></p>
</div><p>Set the max number of connections allowed concurrently.</p>
<h3 class="function"><a name="set_option_default-3">set_option_default/3</a></h3>
<div class="spec">
<p><tt>set_option_default(Opts, Key::atom(), Value::any()) -> Opts</tt>
<ul class="definitions"><li><tt>Opts = [{atom(), any()}]</tt></li></ul></p>
</div><p>Add an option to a list, but only if it wasn't previously set.</p>
<h3 class="function"><a name="set_protocol_options-2">set_protocol_options/2</a></h3>
<div class="spec">
<p><tt>set_protocol_options(Ref::any(), ProtoOpts::any()) -> ok</tt><br></p>
</div><p><p>Upgrade the protocol options for the given listener.</p>
The upgrade takes place at the acceptor level, meaning that only the
newly accepted connections receive the new protocol options. This has
no effect on the currently opened connections.</p>
<h3 class="function"><a name="start_listener-6">start_listener/6</a></h3>
<div class="spec">
<p><tt>start_listener(Ref::any(), NbAcceptors::non_neg_integer(), Transport::module(), TransOpts::any(), Protocol::module(), ProtoOpts::any()) -> {ok, pid()} | {error, badarg}</tt><br></p>
</div><p><p>Start a listener for the given transport and protocol.</p>
<p>A listener is effectively a pool of <em>NbAcceptors</em> acceptors.
Acceptors accept connections on the given <em>Transport</em> and forward
connections to the given <em>Protocol</em> handler. Both transport and
protocol modules can be given options through the <em>TransOpts</em> and
the <em>ProtoOpts</em> arguments. Available options are documented in the
<em>listen</em> transport function and in the protocol module of your choice.</p>
<p>All acceptor and connection processes are supervised by the listener.</p>
<p>It is recommended to set a large enough number of acceptors to improve
performance. The exact number depends of course on your hardware, on the
protocol used and on the number of expected simultaneous connections.</p>
<p>The <em>Transport</em> option <em>max_connections</em> allows you to define
the maximum number of simultaneous connections for this listener. It defaults
to 1024. See <em>ranch_listener</em> for more details on limiting the number
of connections.</p>
<p><em>Ref</em> can be used to stop the listener later on.</p>
This function will return <code>{error, badarg}` if and only if the transport
module given doesn</code>t appear to be correct.</p>
<h3 class="function"><a name="stop_listener-1">stop_listener/1</a></h3>
<div class="spec">
<p><tt>stop_listener(Ref::any()) -> ok | {error, not_found}</tt><br></p>
</div><p><p>Stop a listener identified by <em>Ref</em>.</p>
Note that stopping the listener will close all currently running
connections abruptly.</p>
<hr>
<div class="navbar"><a name="#navbar_bottom"></a><table width="100%" border="0" cellspacing="0" cellpadding="2" summary="navigation bar"><tr><td><a href="overview-summary.html" target="overviewFrame">Overview</a></td><td><a href="http://www.erlang.org/"><img src="erlang.png" align="right" border="0" alt="erlang logo"></a></td></tr></table></div>
<p><i>Generated by EDoc, Mar 9 2013, 09:38:58.</i></p>
</body>
</html>
