mirror of
https://github.com/ninenines/cowboy.git
synced 2025-07-15 12:40:25 +00:00
86 lines
2.8 KiB
Text
86 lines
2.8 KiB
Text
= cowboy_loop(3)
|
|
|
|
== Name
|
|
|
|
cowboy_loop - loop handlers
|
|
|
|
== Description
|
|
|
|
The `cowboy_loop` module implements a handler interface for
|
|
long running HTTP connections. It is the recommended interface
|
|
for long polling and server-sent events, amongst others.
|
|
|
|
This module is a sub protocol that defines three callbacks to
|
|
be implemented by handlers. The `init/2` and `terminate/3`
|
|
callbacks are common to all handler types and are documented
|
|
in the manual for the link:cowboy_handler.asciidoc[cowboy_handler] module.
|
|
|
|
The `info/3` callback is specific to loop handlers and will be
|
|
called as many times as necessary until a reply is sent.
|
|
|
|
It is highly recommended to return a timeout value from the
|
|
`init/2` callback to ensure that the process is terminated
|
|
when no data has been received during that timespan. The
|
|
default timeout is `infinity`, which should only be used if
|
|
you have alternate means of ending inactive connections.
|
|
|
|
== Terminate reasons
|
|
|
|
The following values may be received as the terminate reason
|
|
in the optional `terminate/3` callback.
|
|
|
|
normal::
|
|
The connection was closed normally before switching to the
|
|
loop sub protocol. This typically happens if an `ok` tuple is
|
|
returned from the `init/2` callback.
|
|
|
|
stop::
|
|
The handler requested to close the connection by returning
|
|
a `stop` tuple.
|
|
|
|
timeout::
|
|
The connection has been closed due to inactivity. The timeout
|
|
value can be configured from `init/2`. The response sent when
|
|
this happens is a `204 No Content`.
|
|
|
|
{crash, Class, Reason}::
|
|
A crash occurred in the handler. `Class` and `Reason` can be
|
|
used to obtain more information about the crash. The function
|
|
`erlang:get_stacktrace/0` can also be called to obtain the
|
|
stacktrace of the process when the crash occurred.
|
|
|
|
{error, overflow}::
|
|
The connection is being closed and the process terminated
|
|
because the buffer Cowboy uses to keep data sent by the
|
|
client has reached its maximum. The buffer size can be
|
|
configured through the environment value `loop_max_buffer`
|
|
and defaults to 5000 bytes.
|
|
+
|
|
If the long running request comes with a body it is recommended
|
|
to process this body before switching to the loop sub protocol.
|
|
|
|
{error, closed}::
|
|
The socket has been closed brutally without a close frame being
|
|
received first.
|
|
|
|
{error, Reason}::
|
|
A socket error ocurred.
|
|
|
|
== Callbacks
|
|
|
|
=== info(Info, Req, State) -> {ok, Req, State} | {ok, Req, State, hibernate} | {stop, Req, State}
|
|
|
|
Info = any():: Message received by the process.
|
|
Req = cowboy_req:req():: The Req object.
|
|
State = any():: Handler state.
|
|
|
|
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 `stop` 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.
|