<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="">
<meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara">
<title>Nine Nines: Protocols</title>
<link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'>
<link href="/css/99s.css?r=2" rel="stylesheet">
<link rel="shortcut icon" href="/img/ico/favicon.ico">
<link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png">
<link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png">
<link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png">
</head>
<body class="">
<header id="page-head">
<div id="topbar" class="container">
<div class="row">
<div class="span2">
<h1 id="logo"><a href="/" title="99s">99s</a></h1>
</div>
<div class="span10">
<div id="side-header">
<nav>
<ul>
<li><a title="Hear my thoughts" href="/articles">Articles</a></li>
<li><a title="Watch my talks" href="/talks">Talks</a></li>
<li class="active"><a title="Read the docs" href="/docs">Documentation</a></li>
<li><a title="Request my services" href="/services">Consulting & Training</a></li>
</ul>
</nav>
<ul id="social">
<li>
<a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a>
</li>
<li>
<a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a>
</li>
</ul>
</div>
</div>
</div>
</div>
</header>
<div id="contents" class="two_col">
<div class="container">
<div class="row">
<div id="docs" class="span9 maincol">
<h1 class="lined-header"><span>Protocols</span></h1>
<p>A protocol handler starts a connection process and defines the protocol logic executed in this process.</p>
<h2 id="_writing_a_protocol_handler">Writing a protocol handler</h2>
<p>All protocol handlers must implement the <code>ranch_protocol</code> behavior which defines a single callback, <code>start_link/4</code>. 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 <code>ranch:start_listener/5</code>. This callback must return <code>{ok, Pid}</code>, with <code>Pid</code> the pid of the new process.</p>
<p>The newly started process can then freely initialize itself. However, it must call <code>ranch:accept_ack/1</code> before doing any socket operation. This will ensure the connection process is the owner of the socket. It expects the listener's name as argument.</p>
<div class="listingblock"><div class="title">Acknowledge accepting the socket</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><font color="#0000FF">ok</font> <font color="#990000">=</font> <b><font color="#000000">ranch:accept_ack</font></b>(<font color="#009900">Ref</font>)<font color="#990000">.</font></tt></pre>
</div></div>
<p>If your protocol code requires specific socket options, you should set them while initializing your connection process, after calling <code>ranch:accept_ack/1</code>. You can use <code>Transport:setopts/2</code> for that purpose.</p>
<p>Following is the complete protocol code for the example found in <code>examples/tcp_echo/</code>.</p>
<div class="listingblock"><div class="title">Protocol module that echoes everything it receives</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><b><font color="#000080">-module</font></b>(<font color="#FF6600">echo_protocol</font>)<font color="#990000">.</font>
<b><font color="#000080">-behaviour</font></b>(<font color="#FF6600">ranch_protocol</font>)<font color="#990000">.</font>
<b><font color="#000080">-export</font></b>([<b><font color="#000000">start_link</font></b><font color="#990000">/</font><font color="#993399">4</font>])<font color="#990000">.</font>
<b><font color="#000080">-export</font></b>([<b><font color="#000000">init</font></b><font color="#990000">/</font><font color="#993399">4</font>])<font color="#990000">.</font>
<b><font color="#000000">start_link</font></b>(<font color="#009900">Ref</font>, <font color="#009900">Socket</font>, <font color="#009900">Transport</font>, <font color="#009900">Opts</font>) <font color="#990000">-></font>
<font color="#009900">Pid</font> <font color="#990000">=</font> <b><font color="#000080">spawn_link</font></b>(<b><font color="#000080">?MODULE</font></b>, <font color="#FF6600">init</font>, [<font color="#009900">Ref</font>, <font color="#009900">Socket</font>, <font color="#009900">Transport</font>, <font color="#009900">Opts</font>]),
{<font color="#FF6600">ok</font>, <font color="#009900">Pid</font>}<font color="#990000">.</font>
<b><font color="#000000">init</font></b>(<font color="#009900">Ref</font>, <font color="#009900">Socket</font>, <font color="#009900">Transport</font>, <font color="#009900">_Opts</font> <font color="#990000">=</font> []) <font color="#990000">-></font>
<font color="#0000FF">ok</font> <font color="#990000">=</font> <b><font color="#000000">ranch:accept_ack</font></b>(<font color="#009900">Ref</font>),
<b><font color="#000000">loop</font></b>(<font color="#009900">Socket</font>, <font color="#009900">Transport</font>)<font color="#990000">.</font>
<b><font color="#000000">loop</font></b>(<font color="#009900">Socket</font>, <font color="#009900">Transport</font>) <font color="#990000">-></font>
<b><font color="#0000FF">case</font></b> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">recv</font></b>(<font color="#009900">Socket</font>, <font color="#993399">0</font>, <font color="#993399">5000</font>) <b><font color="#0000FF">of</font></b>
{<font color="#FF6600">ok</font>, <font color="#009900">Data</font>} <font color="#990000">-></font>
<font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">send</font></b>(<font color="#009900">Socket</font>, <font color="#009900">Data</font>),
<b><font color="#000000">loop</font></b>(<font color="#009900">Socket</font>, <font color="#009900">Transport</font>);
<font color="#990000">_</font> <font color="#990000">-></font>
<font color="#0000FF">ok</font> <font color="#990000">=</font> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">close</font></b>(<font color="#009900">Socket</font>)
<b><font color="#0000FF">end</font></b><font color="#990000">.</font></tt></pre>
</div></div>
<h2 id="_using_gen_server">Using gen_server</h2>
<p>Special processes like the ones that use the <code>gen_server</code> or <code>gen_fsm</code> behaviours have the particularity of having their <code>start_link</code> call not return until the <code>init</code> function returns. This is problematic, because you won't be able to call <code>ranch:accept_ack/1</code> from the <code>init</code> callback as this would cause a deadlock to happen.</p>
<p>Use the <code>gen_server:enter_loop/3</code> function. It allows you to start your process normally (although it must be started with <code>proc_lib</code> like all special processes), then perform any needed operations before falling back into the normal <code>gen_server</code> execution loop.</p>
<div class="listingblock"><div class="title">Use a gen_server for protocol handling</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><b><font color="#000080">-module</font></b>(<font color="#FF6600">my_protocol</font>)<font color="#990000">.</font>
<b><font color="#000080">-behaviour</font></b>(<font color="#FF6600">gen_server</font>)<font color="#990000">.</font>
<b><font color="#000080">-behaviour</font></b>(<font color="#FF6600">ranch_protocol</font>)<font color="#990000">.</font>
<b><font color="#000080">-export</font></b>([<b><font color="#000000">start_link</font></b><font color="#990000">/</font><font color="#993399">4</font>])<font color="#990000">.</font>
<b><font color="#000080">-export</font></b>([<b><font color="#000000">init</font></b><font color="#990000">/</font><font color="#993399">1</font>])<font color="#990000">.</font>
<i><font color="#9A1900">%% Exports of other gen_server callbacks here.</font></i>
<b><font color="#000000">start_link</font></b>(<font color="#009900">Ref</font>, <font color="#009900">Socket</font>, <font color="#009900">Transport</font>, <font color="#009900">Opts</font>) <font color="#990000">-></font>
{<font color="#FF6600">ok</font>, <b><font color="#000000">proc_lib:spawn_link</font></b>(<b><font color="#000080">?MODULE</font></b>, <font color="#FF6600">init</font>, [{<font color="#009900">Ref</font>, <font color="#009900">Socket</font>, <font color="#009900">Transport</font>, <font color="#009900">Opts</font>}])}<font color="#990000">.</font>
<b><font color="#000000">init</font></b>({<font color="#009900">Ref</font>, <font color="#009900">Socket</font>, <font color="#009900">Transport</font>, <font color="#009900">_Opts</font> <font color="#990000">=</font> []}) <font color="#990000">-></font>
<i><font color="#9A1900">%% Perform any required state initialization here.</font></i>
<font color="#0000FF">ok</font> <font color="#990000">=</font> <b><font color="#000000">ranch:accept_ack</font></b>(<font color="#009900">Ref</font>),
<font color="#0000FF">ok</font> <font color="#990000">=</font> <font color="#009900">Transport</font><font color="#990000">:</font><b><font color="#000000">setopts</font></b>(<font color="#009900">Socket</font>, [{<font color="#FF6600">active</font>, <font color="#FF6600">once</font>}]),
<b><font color="#000000">gen_server:enter_loop</font></b>(<b><font color="#000080">?MODULE</font></b>, [], {<font color="#FF6600">state</font>, <font color="#009900">Socket</font>, <font color="#009900">Transport</font>})<font color="#990000">.</font>
<i><font color="#9A1900">%% Other gen_server callbacks here.</font></i></tt></pre>
</div></div>
<p>Check the <code>tcp_reverse</code> example for a complete example.</p>
<nav style="margin:1em 0">
<a style="float:left" href="https://ninenines.eu/docs/en/ranch/1.5/guide/transports/">
Transports
</a>
<a style="float:right" href="https://ninenines.eu/docs/en/ranch/1.5/guide/embedded/">
Embedded mode
</a>
</nav>
</div>
<div class="span3 sidecol">
<h3>
Ranch
1.5
User Guide
</h3>
<ul>
<li><a href="/docs/en/ranch/1.5/guide">User Guide</a></li>
<li><a href="/docs/en/ranch/1.5/manual">Function Reference</a></li>
</ul>
<h4 id="docs-nav">Navigation</h4>
<h4>Version select</h4>
<ul>
<li><a href="/docs/en/ranch/1.6/guide">1.6</a></li>
<li><a href="/docs/en/ranch/1.5/guide">1.5</a></li>
<li><a href="/docs/en/ranch/1.4/guide">1.4</a></li>
<li><a href="/docs/en/ranch/1.3/guide">1.3</a></li>
<li><a href="/docs/en/ranch/1.2/guide">1.2</a></li>
</ul>
</div>
</div>
</div>
</div>
<footer>
<div class="container">
<div class="row">
<div class="span6">
<p id="scroll-top"><a href="#">↑ Scroll to top</a></p>
<nav>
<ul>
<li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li>
</ul>
</nav>
</div>
<div class="span6 credits">
<p><img src="/img/footer_logo.png"></p>
<p>Copyright © Loïc Hoguin 2012-2018</p>
</div>
</div>
</div>
</footer>
<script src="/js/custom.js"></script>
</body>
</html>
