summaryrefslogblamecommitdiffstats
path: root/docs/en/ranch/1.5/guide/protocols/index.html
blob: a9609445f1f8df712ddd33d57f1451a7cf7b18b9 (plain) (tree)
1
2
3
4
5
6
7
8
9
10
11
12











                                                                                                                      
                                                   
















































































































































































                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 

                                                                   







































                                                                                                                                                                                                                           
<!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&apos;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">-&gt;</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">-&gt;</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">-&gt;</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">-&gt;</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">-&gt;</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&apos;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">-&gt;</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">-&gt;</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 &copy; Loïc Hoguin 2012-2018</p>
            </div>
          </div>
        </div>
      </footer>

    
    <script src="/js/custom.js"></script>
  </body>
</html>