From 5da7d1ef059ec4d7f5b211db962e65c86a3662be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Fri, 23 Dec 2016 17:20:54 +0100 Subject: Update cowboy_loop manual --- doc/src/manual/cowboy_handler.asciidoc | 8 +- doc/src/manual/cowboy_loop.asciidoc | 144 +++++++++++++++++-------------- doc/src/manual/cowboy_websocket.asciidoc | 1 + 3 files changed, 86 insertions(+), 67 deletions(-) diff --git a/doc/src/manual/cowboy_handler.asciidoc b/doc/src/manual/cowboy_handler.asciidoc index 28ac311..93dad22 100644 --- a/doc/src/manual/cowboy_handler.asciidoc +++ b/doc/src/manual/cowboy_handler.asciidoc @@ -28,10 +28,10 @@ init(Req, State) -> {ok, Req, State} terminate(Reason, Req, State) -> ok %% optional -Req :: cowboy_req:req() -State :: any() -Reason :: normal - | {crash, error | exit | throw, any()} +Req :: cowboy_req:req() +State :: any() +Reason :: normal + | {crash, error | exit | throw, any()} ---- These two callbacks are common to all handlers. diff --git a/doc/src/manual/cowboy_loop.asciidoc b/doc/src/manual/cowboy_loop.asciidoc index eb17b15..3f4cfed 100644 --- a/doc/src/manual/cowboy_loop.asciidoc +++ b/doc/src/manual/cowboy_loop.asciidoc @@ -2,85 +2,103 @@ == Name -cowboy_loop - loop handlers +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. +The module `cowboy_loop` defines a callback interface for +long running HTTP connections. -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. +You should switch to this behavior for long polling, +server-sent events and similar long-running requests. -The `info/3` callback is specific to loop handlers and will be -called as many times as necessary until a reply is sent. +There are generally two usage patterns: -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. +* Loop until receiving a specific message, then send + a response and stop execution (for example long polling); -== Terminate reasons +* Or initiate a response in `init/2` and stream the + body in `info/3` as necessary (for example server-sent events). -The following values may be received as the terminate reason -in the optional `terminate/3` callback. +== Callbacks -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. +Loop handlers implement the following interface: -stop:: - The handler requested to close the connection by returning - a `stop` tuple. +[source,erlang] +---- +init(Req, State) + -> {cowboy_loop, Req, State} + | {cowboy_loop, Req, State, hibernate} + | {cowboy_loop, Req, State, timeout()} + | {cowboy_loop, Req, State, timeout(), hibernate} -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`. +info(Info, Req, State) + -> {ok, Req, State} + | {ok, Req, State, hibernate} + | {stop, Req, State} -{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. +terminate(Reason, Req, State) -> ok %% optional -== Callbacks +Req :: cowboy_req:req() +State :: any() +Info :: any() +Reason :: stop | timeout + | {crash, error | exit | throw, any()} +---- -=== info(Info, Req, State) -> {ok, Req, State} | {ok, Req, State, hibernate} | {stop, Req, State} +The `init/2` callback is common to all handlers. To switch +to the loop behavior, it must return `cowboy_loop` as the +first element of the tuple. -Info = any():: Message received by the process. -Req = cowboy_req:req():: The Req object. -State = any():: Handler state. +The `info/3` callback will be called for every Erlang message +received. It may choose to continue the receive loop or stop +it. -Handle the Erlang message received. +The optional `terminate/3` callback will ultimately be called +with the reason for the termination of the handler. +Cowboy will terminate the process right after this. There +is no need to perform any cleanup in this callback. -This function will be called every time an Erlang message -has been received. The message can be any Erlang term. +The following terminate reasons are defined for loop handlers: -The `stop` return value can be used to stop the receive loop, -typically because a response has been sent. +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`. -The `hibernate` option will hibernate the process until -it receives another message. +{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. + +== Changelog + +* *2.0*: Cowboy temporarily no longer checks the socket for data with HTTP/1.1. +* *1.0*: Behavior introduced. + +== See also + +link:man:cowboy(7)[cowboy(7)], +link:man:cowboy_handler(3)[cowboy_handler(3)] diff --git a/doc/src/manual/cowboy_websocket.asciidoc b/doc/src/manual/cowboy_websocket.asciidoc index 3ae811a..73f5e72 100644 --- a/doc/src/manual/cowboy_websocket.asciidoc +++ b/doc/src/manual/cowboy_websocket.asciidoc @@ -161,5 +161,6 @@ timeout:: == See also link:man:cowboy(7)[cowboy(7)], +link:man:cowboy_handler(3)[cowboy_handler(3)], link:man:cowboy_http(3)[cowboy_http(3)], link:man:cowboy_http2(3)[cowboy_http2(3)] -- cgit v1.2.3