aboutsummaryrefslogtreecommitdiffstats
path: root/guide/loop_handlers.md
blob: 41f9e763562ba6da5ccbba59ed79002c40f9ad27 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
Loop handlers
=============

Purpose
-------

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.

They are most useful when performing long-polling operations or
when using server-sent events.

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.

Callbacks
---------

@todo Describe the callbacks.

Usage
-----

@todo Explain how to use them.

The following handler waits for a message `{reply, Body}` before
sending a response. If this message doesn't arrive within 60
seconds, it gives up and a `204 No Content` will be replied.
It also hibernates the process to save memory while waiting for
this message.

``` erlang
-module(my_loop_handler).
-behaviour(cowboy_loop_handler).

-export([init/3]).
-export([info/3]).
-export([terminate/2]).

init({tcp, http}, Req, Opts) ->
    {loop, Req, undefined_state, 60000, hibernate}.

info({reply, Body}, Req, State) ->
    {ok, Req2} = cowboy_req:reply(200, [], Body, Req),
    {ok, Req2, State};
info(Message, Req, State) ->
    {loop, Req, State, hibernate}.

terminate(Req, State) ->
    ok.
```