<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Nine Nines Support: Cowboy User Guide</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<!-- Change them or set them up as you like -->
<meta name="description" content="">
<meta name="author" content="(Soft10) Pol Cámara">
<!-- Stylesheets -->
<link href='http://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'>
<link href="/css/bootstrap.min.css" rel="stylesheet">
<link href="/css/99s.css" rel="stylesheet">
<!-- <link href="js/google-code-prettify/prettify.css" rel="stylesheet"> -->
<link href="/css/sh99s.css" rel="stylesheet"/>
<!-- Enables html5 support on older browsers, other js is placed at the end of the page to speed up loading -->
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<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">
<link rel="alternate" href="/feeds/atom.xml" type="application/atom+xml" title="Nine Nines Atom Feed">
</head>
<body class="big_text docs">
<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">
<!-- Top navigation and social icons-->
<div id="side-header">
<nav>
<ul>
<li><a title="Erlang training" href="/training">Training</a></li>
<li><a title="Technical publications" href="/articles">Articles</a></li>
<li><a title="Our talks" href="/talks">Talks</a></li>
<li class="active"><a title="Our services" href="/support">Pricing & Sponsoring</a></li>
<li><a title="Community support" href="https://ninenines.eu/archives/extend/">Mailing Lists</a></li>
<li><a title="Contact us" href="mailto:[email protected]">Contact</a></li>
</ul>
</nav>
<ul id="social">
<li>
<a href="https://github.com/ninenines" title="Check our Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a>
</li>
<li class="dropdown" id="twitter-links">
<a href="#twitter-links" class="dropdown-toggle" data-toggle="dropdown" title="Follow us on Twitter">
<img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png" alt="Twitter">
</a>
<ul class="dropdown-menu">
<li><a title="Visit Loïc Hoguin's Twitter Account" href="http://twitter.com/lhoguin">@lhoguin</a></li>
<!-- <li class="divider"></li>
<li><a title="Visit our official Twitter account" href="#">@99s</a></li> -->
</ul>
</li>
<!-- <li>
<a href="/css/" title="Add us on Linkedin"><img src="/img/ico_linkedin.png" data-hover="img/ico_linkedin_alt.png" alt="Linkedin"></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>Loop handlers</span></h1>
<p>Loop handlers are a special kind of HTTP handlers used when the response can not be sent right away. The handler enters instead a receive loop waiting for the right message before it can send a response.</p>
<p>Loop handlers are used for requests where a response might not be immediately available, but where you would like to keep the connection open for a while in case the response arrives. The most known example of such practice is known as long-polling.</p>
<p>Loop handlers can also be used for requests where a response is partially available and you need to stream the response body while the connection is open. The most known example of such practice is known as server-sent events.</p>
<p>While the same can be accomplished using plain HTTP handlers, it is recommended to use loop handlers because they are well-tested and allow using built-in features like hibernation and timeouts.</p>
<p>Loop handlers essentially wait for one or more Erlang messages and feed these messages to the <code>info/3</code> callback. It also features the <code>init/3</code> and <code>terminate/3</code> callbacks which work the same as for plain HTTP handlers.</p>
<h2 id="initialization">Initialization</h2>
<p>The <code>init/3</code> function must return a <code>loop</code> tuple to enable loop handler behavior. This tuple may optionally contain a timeout value and/or the atom <code>hibernate</code> to make the process enter hibernation until a message is received.</p>
<p>This snippet enables the loop handler.</p>
<script type="syntaxhighlighter" class="brush: erlang"><![CDATA[
init(_Type, Req, _Opts) ->
{loop, Req, undefined_state}.
]]></script>
<p>However it is largely recommended that you set a timeout value. The next example sets a timeout value of 30s and also makes the process hibernate.</p>
<script type="syntaxhighlighter" class="brush: erlang"><![CDATA[
init(_Type, Req, _Opts) ->
{loop, Req, undefined_state, 30000, hibernate}.
]]></script>
<h2 id="receive_loop">Receive loop</h2>
<p>Once initialized, Cowboy will wait for messages to arrive in the process' mailbox. When a message arrives, Cowboy calls the <code>info/3</code> function with the message, the Req object and the handler's state.</p>
<p>The following snippet sends a reply when it receives a <code>reply</code> message from another process, or waits for another message otherwise.</p>
<script type="syntaxhighlighter" class="brush: erlang"><![CDATA[
info({reply, Body}, Req, State) ->
{ok, Req2} = cowboy_req:reply(200, [], Body, Req),
{ok, Req2, State};
info(_Msg, Req, State) ->
{loop, Req, State, hibernate}.
]]></script>
<p>Do note that the <code>reply</code> tuple here may be any message and is simply an example.</p>
<p>This callback may perform any necessary operation including sending all or parts of a reply, and will subsequently return a tuple indicating if more messages are to be expected.</p>
<p>The callback may also choose to do nothing at all and just skip the message received.</p>
<p>If a reply is sent, then the <code>ok</code> tuple should be returned. This will instruct Cowboy to end the request.</p>
<p>Otherwise a <code>loop</code> tuple should be returned.</p>
<h2 id="streaming_loop">Streaming loop</h2>
<p>Another common case well suited for loop handlers is streaming data received in the form of Erlang messages. This can be done by initiating a chunked reply in the <code>init/3</code> callback and then using <code>cowboy_req:chunk/2</code> every time a message is received.</p>
<p>The following snippet does exactly that. As you can see a chunk is sent every time a <code>chunk</code> message is received, and the loop is stopped by sending an <code>eof</code> message.</p>
<script type="syntaxhighlighter" class="brush: erlang"><![CDATA[
init(_Type, Req, _Opts) ->
{ok, Req2} = cowboy_req:chunked_reply(200, [], Req),
{loop, Req2, undefined_state}.
info(eof, Req, State) ->
{ok, Req, State};
info({chunk, Chunk}, Req, State) ->
ok = cowboy_req:chunk(Chunk, Req),
{loop, Req, State};
info(_Msg, Req, State) ->
{loop, Req, State}.
]]></script>
<h2 id="cleaning_up">Cleaning up</h2>
<p>It is recommended that you set the connection header to <code>close</code> when replying, as this process may be reused for a subsequent request.</p>
<p>Please refer to the <a href="/docs/en/cowboy/1.0/guide/http_handlers">HTTP handlers chapter</a> for general instructions about cleaning up.</p>
<h2 id="timeout">Timeout</h2>
<p>By default Cowboy will not attempt to close the connection if there is no activity from the client. This is not always desirable, which is why you can set a timeout. Cowboy will close the connection if no data was received from the client after the configured time. The timeout only needs to be set once and can't be modified afterwards.</p>
<p>Because the request may have had a body, or may be followed by another request, Cowboy is forced to buffer all data it receives. This data may grow to become too large though, so there is a configurable limit for it. The default buffer size is of 5000 bytes, but it may be changed by setting the <code>loop_max_buffer</code> middleware environment value.</p>
<h2 id="hibernate">Hibernate</h2>
<p>To save memory, you may hibernate the process in between messages received. This is done by returning the atom <code>hibernate</code> as part of the <code>loop</code> tuple callbacks normally return. Just add the atom at the end and Cowboy will hibernate accordingly.</p>
<!-- a.code -->
</div>
<div class="span3 sidecol">
<div class="input-append">
<form id="form-search" class="form-search" action="#">
<input id="input-search" type="text" placeholder="Function search" autocomplete="off" autofocus class="input-medium search-query span2">
<button type="submit" class="btn btn-success">Go</button>
</form>
</div>
<h3 id="docs-nav">Navigation</h3>
<h3>See also</h3><ul><li><a href="/docs/en/cowboy/1.0/manual/">Function Reference</a></li><li><a href="/docs/en/cowboy/1.0/index.html">README</a></li></ul>
<h3>Version select</h3>
<ul>
<li><a href="/docs/en/cowboy/1.0/guide/"><strong>1.0</strong></a></li>
<li><a href="/docs/en/cowboy/HEAD/guide/"><strong>HEAD</strong></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 © Nine Nines 2012-2014</p>
</div>
</div>
</div>
</footer>
<!-- Javascript -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script>
<script src="/js/bootstrap-carousel.js"></script>
<script src="/js/bootstrap-dropdown.js"></script>
<script src="/js/custom.js"></script>
<script type="text/javascript" src="/js/shCore.js"></script>
<script type="text/javascript" src="/js/shlang/shBrushBash.js"></script>
<script type="text/javascript" src="/js/shlang/shBrushErlang.js"></script>
<script type="text/javascript" src="/js/shlang/shBrushJScript.js"></script>
<script type="text/javascript" src="/js/shlang/shBrushPlain.js"></script>
<script type="text/javascript">SyntaxHighlighter.all();</script>
<script type="text/javascript" src="/js/fuse.min.js"></script>
<script type="text/javascript">
$(document).ready(function(){
var f;
$.getJSON("/docs/db.json", function(data){
f = new Fuse(data, {keys: ["n"], threshold: 0.3});
$("<ul id=\"search-results\">").insertAfter("#form-search");
});
$("#input-search").keyup(function(e){if(f){if (e.which != 13 ){
var results = f.search($(this).val());
if (results.length == 0){
$("#form-search").attr("action", "#");
}else{
$("#form-search").attr("action", results[0].l);
}
$("#search-results").empty();
for (var i = 0; i < 10 && i < results.length; i++){
$("<li><a href=\"" + results[i].l + "\">" + results[i].n + "</a></li>")
.appendTo("#search-results");
}
}}});
});
</script>
</body>
</html>
