diff options
Diffstat (limited to '_build/static/docs/en/cowboy/1.0/guide/loop_handlers/index.html')
| -rw-r--r-- | _build/static/docs/en/cowboy/1.0/guide/loop_handlers/index.html | 264 |
1 files changed, 0 insertions, 264 deletions
diff --git a/_build/static/docs/en/cowboy/1.0/guide/loop_handlers/index.html b/_build/static/docs/en/cowboy/1.0/guide/loop_handlers/index.html deleted file mode 100644 index 8d177942..00000000 --- a/_build/static/docs/en/cowboy/1.0/guide/loop_handlers/index.html +++ /dev/null @@ -1,264 +0,0 @@ -<!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> |