aboutsummaryrefslogtreecommitdiffstats
path: root/manual/cowboy_loop_handler.md
blob: ccbb9b0afc782dea886d85af6e0114a13bba0645 (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
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
cowboy_loop_handler
===================

The `cowboy_loop_handler` behaviour defines the interface used
by HTTP handlers that do not send a response directly, instead
requiring a receive loop to process Erlang messages.

This interface is best fit for long-polling types of requests.

The `init/3` callback will always be called, followed by zero
or more calls to `info/3`. The `terminate/3` will always be
called last.

Types
-----

None.

Callbacks
---------

### init({TransportName, ProtocolName}, Req, Opts)
	-> {loop, Req, State}
	| {loop, Req, State, hibernate}
	| {loop, Req, State, Timeout}
	| {loop, Req, State, Timeout, hibernate}
	| {shutdown, Req, State}

> Types:
>  *  TransportName = tcp | ssl | atom()
>  *  ProtocolName = http | atom()
>  *  Req = cowboy_req:req()
>  *  Opts = any()
>  *  State = any()
>  *  Timeout = timeout()
>
> Initialize the state for this request.
>
> This callback will typically be used to register this process
> to an event manager or a message queue in order to receive
> the messages the handler wants to process.
>
> The receive loop will run for a duration of up to `Timeout`
> milliseconds after it last received data from the socket,
> at which point it will stop and send a `204 No Content` reply.
> By default this value is set to `infinity`. It is recommended
> to either set this value or ensure by any other mechanism
> that the handler will be closed after a certain period of
> inactivity.
>
> The `hibernate` option will hibernate the process until it
> starts receiving messages.
>
> The `shutdown` return value can be used to skip the receive
> loop entirely.

### info(Info, Req, State) -> {ok, Req, State} | {loop, Req, State}
	| {loop, Req, State, hibernate}

> Types:
>  *  Info = any()
>  *  Req = cowboy_req:req()
>  *  State = any()
>
> Handle the Erlang message received.
>
> This function will be called every time an Erlang message
> has been received. The message can be any Erlang term.
>
> The `ok` return value can be used to stop the receive loop,
> typically because a response has been sent.
>
> The `hibernate` option will hibernate the process until
> it receives another message.

### terminate(Reason, Req, State) -> ok

> Types:
>  *  Reason = {normal, shutdown} | {normal, timeout} | {error, closed} | {error, overflow} | {error, atom()}
>  *  Req = cowboy_req:req()
>  *  State = any()
>
> Perform any necessary cleanup of the state.
>
> This callback will typically unregister from any event manager
> or message queue it registered to in `init/3`.
>
> This callback should release any resource currently in use,
> clear any active timer and reset the process to its original
> state, as it might be reused for future requests sent on the
> same connection.