diff options
Diffstat (limited to 'docs/en/cowboy/1.0/guide/loop_handlers/index.html')
| -rw-r--r-- | docs/en/cowboy/1.0/guide/loop_handlers/index.html | 264 |
1 files changed, 264 insertions, 0 deletions
diff --git a/docs/en/cowboy/1.0/guide/loop_handlers/index.html b/docs/en/cowboy/1.0/guide/loop_handlers/index.html new file mode 100644 index 00000000..d9d1bb30 --- /dev/null +++ b/docs/en/cowboy/1.0/guide/loop_handlers/index.html @@ -0,0 +1,264 @@ +<!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="http://lists.ninenines.eu">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_twitter.png" data-hover="/img/ico_twitter_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> |